Kodi Tax Agent

An autonomous tax agent that gathers evidence, understands obligations, resolves missing information, calculates tax, and guides compliance from one simple objective.

Comment

The problem

Imagine asking someone to handle your taxes. Before they calculate anything, they first need to understand your situation. Which tax year are we dealing with? Are you a resident? Where did your income come from? How much tax has already been deducted? Which documents do you have? Which ones are missing? Which rules apply to you?

The problem is that these answers rarely exist in one place. Your employer has some of them. Your bank may have others. Some are sitting inside tax documents. Some may be in previous returns or accounting systems. Others only exist in your head.

This is one of the reasons tax is so difficult. The problem is not simply that we lack tax calculators. The real challenge is bringing together the right tax rules, taxpayer facts, evidence, calculations and actions for one person, then knowing what should happen next.

This affects taxpayers, accountants, tax agents, businesses and tax authorities. The progress we are seeing with AI agents in other industries raises an interesting question about whether the same ideas could change how people work through tax.

The idea

Software development has changed dramatically because of AI agents. Today, I can give a coding agent an objective such as, "Fix the authentication bug in this project." I do not have to tell it which file to open first, which function to inspect or which test to run.

A good coding agent can inspect the repository, understand the existing code, read documentation, run tests, make changes, observe failures, correct itself and continue working. The developer gives it an objective. The agent works through the problem using the tools and information available to it.

That leads to an interesting question:

What would happen if tax worked the same way?

Instead of forcing someone to understand every form, rule, document and process before they can even begin, what if they could simply say:

Help me handle my taxes.

The system would then work through the case. It would determine what it knows, what it can find, what it needs, what action should happen next and when it needs help from the taxpayer.

That is what I built with Kodi Tax Agent.

What Kodi does

Kodi treats tax as a case to be worked on, not simply a question to be answered. A taxpayer gives Kodi an objective, and Kodi creates a persistent Tax Case around that objective.

It starts by checking what is already known. It examines available facts and evidence. It checks whether relevant documents are still being processed. It identifies information that is missing and determines whether it can resolve that information using the capabilities available to it.

If useful evidence exists in a document, Kodi can work with that evidence. If a relevant document is still being processed, Kodi can recognise that the information may still be on the way. If the evidence has been exhausted and something genuinely requires the taxpayer, Kodi can ask a focused question.

When the taxpayer answers, Kodi records that information as part of the durable Tax Case and continues working from the updated state.

The important part is that this process does not disappear after one chat response. The case has durable memory. Its facts, evidence, tasks, questions, computations, validations, artifacts and progress can be persisted. If the browser is refreshed, Kodi can reconstruct the case and continue from the same state.

This is not another tax chatbot

A normal chatbot usually follows a simple pattern:

Question
   ↓
AI generates an answer

That is useful for many things, but tax requires more than a good answer. A tax workflow may involve documents, missing information, calculations, retries, evidence, validation and actions that happen over time.

Kodi therefore works more like this:

Objective
   ↓
Understand the Tax Case
   ↓
Check facts and evidence
   ↓
Decide the next useful action
   ↓
Perform that action
   ↓
Observe the result
   ↓
Save what happened
   ↓
Reassess the case
   ↓
Continue

This is much closer to how modern coding agents work. A coding agent has a repository. Kodi has a Tax Case. A coding agent inspects files. Kodi inspects taxpayer facts and evidence. A coding agent uses development tools. Kodi uses governed tax capabilities. A coding agent runs tests to verify its work. Kodi uses evidence checks, deterministic rules and validation. A coding agent has Git history. Kodi maintains case history, evidence provenance and an audit trail.

The goal is not to build AI that simply knows a lot about tax. The goal is to build an AI agent that can work on tax.

How I built it

For this hackathon, I built Kodi as a complete tax platform around the idea of an autonomous Tax Case. The system includes authentication, document processing, tax knowledge, deterministic tax computation, validation, forms, reports, storage, orchestration, audit infrastructure and the autonomous Agent Runtime.

The autonomous Tax Case runtime uses Google ADK with Gemini 3.7 Flash through Vertex AI for planning. The model receives a bounded view of the current Tax Case and proposes the next useful action, but it does not have unrestricted control over the system.

Kodi first evaluates the current case and determines which actions are appropriate at that point. Gemini then chooses from that bounded set of actions. The proposed decision is validated against the case state, evidence, tool contract and policy before anything is executed.

I also did not use the same Gemini model for every workload.

Gemini 3.7 Flash handles autonomous Tax Case planning.

Gemini 3.6 Flash handles document understanding and grounded response synthesis.

Gemini 3.5 Flash handles more difficult semantic relationships between evidence claims.

Gemini 3.5 Flash-Lite handles bounded tasks such as conversation-turn resolution and canonical claim extraction.

All of these generation and semantic workloads run through Vertex AI using Google Cloud authentication. OpenAI remains in Kodi only for retrieval embeddings.

The principle behind the model routing is simple. Use the stronger model where the reasoning genuinely requires it, and use a lighter model where the task is more constrained.

Kodi performs one meaningful action at a time. After that action finishes, the result is recorded in the durable Tax Case. Kodi then reloads the latest state and determines what should happen next.

The core loop is:

Plan
  ↓
Act
  ↓
Observe
  ↓
Persist
  ↓
Reassess
  ↓
Plan again

This separation is important. Gemini contributes semantic intelligence and strategy, while Kodi remains responsible for trusted identity, permissions, evidence, execution, durable state, deterministic tax logic, validation, retries and auditability.

I deployed the platform across 12 Google Cloud Run services covering Agent Runtime, authentication, orchestration, Document AI, Tax Core, Knowledge, Validation, Forms, Reports, Storage, Event Store and Gateway.

Document processing runs separately through a Cloud Run Job. Cloud Scheduler triggers the worker, while PostgreSQL on Cloud SQL provides durable Tax Case state and the document-processing work queue.

The fact that these capabilities are deployed does not mean the autonomous agent has unrestricted access to all of them. Kodi deliberately separates what exists in the platform from what the agent is permitted to use autonomously at a particular point in a case.

Evidence comes before guessing

One of the most important things I learned while building Kodi is that tax is fundamentally an evidence problem.

Suppose Kodi needs someone's employment income. There are two very different situations. The information may genuinely be missing, or a document containing that information may still be processing. Those situations should not produce the same response.

Kodi distinguishes between them.

If useful evidence may already exist in the taxpayer's documents, Kodi first attempts to work with that evidence instead of immediately asking the taxpayer to type the same information again.

Uploaded documents move through a durable processing workflow. Document AI records the work that needs to be performed. A Cloud Run worker picks up the processing item and uses Gemini 3.6 Flash through Vertex AI for structured document understanding.

But Gemini's interpretation does not automatically become tax truth.

Kodi validates the structured observations, transforms them into its canonical representation and preserves the connection between the resulting evidence and the source document. Retrieval embeddings are created separately so that relevant evidence can later be searched and retrieved.

The flow is closer to:

Source document
      ↓
Document understanding
      ↓
Structured observations
      ↓
Validation
      ↓
Canonical evidence
      ↓
Tax Case

That distinction is important because a language model should not be allowed to quietly turn an interpretation into an authoritative taxpayer fact.

If the available evidence still cannot answer the question, Kodi can ask for clarification.

In the current workflow, for example, Kodi can identify that residency information remains unresolved and ask the taxpayer a focused question about their residency status.

Once the taxpayer answers, that response becomes part of the durable Tax Case. Kodi then reassesses the case and continues automatically.

This also creates a much more important capability: provenance.

A tax result should not simply exist as a number. The system should be able to preserve a path such as:

Source document
      ↓
Canonical evidence
      ↓
Case evidence
      ↓
Taxpayer fact
      ↓
Computation
      ↓
Validation
      ↓
Artifact

That makes it possible to keep asking a simple question:

Where did this tax result come from?

For tax, that question should never be optional.

What was challenging

Building an AI agent that can call tools is relatively easy. Building one that can be trusted to work on a tax case is much harder.

One of the first challenges was keeping the agent grounded. The model needs enough freedom to choose what to do next, but it should not invent taxpayer facts, invent tools or perform actions that do not make sense for the current case.

I addressed this by deriving a bounded set of actions from the current Tax Case and allowing the model to choose from that set. Gemini proposes what should happen next, but Kodi determines whether that action is actually allowed.

Another challenge was durability. A tax workflow may take several steps and may not finish in one session. A taxpayer may answer a question later. A downstream service may temporarily fail. A document may still be processing. The browser may be refreshed.

Because of that, I could not rely on the model's temporary conversation memory.

Kodi stores the actual workflow state in PostgreSQL so that the case can be reconstructed later. The durable Tax Case, rather than the model context, is the source of truth.

Retries were another difficult area. If a tool fails and Kodi tries again, the same business action should not accidentally happen twice. I built durable tasks and stable idempotency so that Kodi can recover the same logical piece of work safely.

Document processing introduced another challenge because it happens asynchronously. The API can accept a document before the processing itself has finished. Kodi therefore needs to understand that "I do not have this evidence yet" and "this evidence does not exist" are not necessarily the same thing.

I also had to think carefully about stopping.

An autonomous agent should not continue simply because it can. If required evidence is missing, Kodi should identify the blocker. If a human answer is required, it should ask. If a document is still processing, it should wait instead of treating the information as missing.

Sometimes the correct autonomous decision is to stop and explain what is needed next.

What I am proud of

The most important achievement for me is that Kodi is not only an architecture diagram. I deployed the complete backend platform to Google Cloud and tested the autonomous workflow against the real services.

The deployment includes 12 Cloud Run services, a Cloud Run Job for asynchronous document processing, Cloud Scheduler for worker execution, PostgreSQL on Cloud SQL for durable state, Vertex AI for Gemini inference and Cloudflare R2 for private source documents.

The frontend is wired to the deployed Cloud Run endpoints, so the working demo is not dependent on a local backend.

I tested the actual workflow from authentication through Tax Case creation, Gemini planning, governed tool execution, document upload, cloud worker processing, Gemini document understanding, canonical evidence retrieval, taxpayer clarification, answer persistence, automatic workflow resume and browser reload recovery.

The Document AI worker also processes real durable work items in the cloud. A synthetic document can be uploaded, processed through the Cloud Run worker, interpreted using Gemini 3.6 Flash, transformed into canonical evidence and indexed for retrieval.

During testing, I deliberately reached a case where the available synthetic tax document did not provide the employment income evidence Kodi needed.

Kodi stopped.

It did not invent a salary. It did not fill the gap with a plausible number simply so the workflow could appear complete.

It recognised that the evidence was not there.

For me, that was a successful result. A trustworthy tax agent must know when it has enough evidence to continue and when it does not.

What I learned

The biggest lesson was that building an autonomous tax agent is not mainly about connecting an LLM to tax APIs. The model is only one part of the system.

A useful tax agent needs several things working together:

Tax knowledge
+
Taxpayer context
+
Evidence
+
Tools
+
Permissions
+
Durable state
+
Validation
+
Recovery
+
Auditability

The same pattern is already making modern coding agents powerful. They do not succeed simply because the language model knows programming. They succeed because the model can inspect a real environment, use tools, observe results, preserve state and verify its work.

Tax needs the same kind of architecture, but the consequences of getting the underlying facts wrong can be much higher. That means evidence, deterministic computation and traceability have to sit alongside AI reasoning.

I also learned that adding more autonomy is not automatically an improvement.

Kodi has capabilities for tax knowledge, computation, validation, forms, reports, document processing and other parts of the tax lifecycle, but the autonomous policy does not simply expose everything to the agent.

The ability to call a service and the authority to call that service are different things.

That distinction became one of the most important architectural ideas in the project.

The same applies to model selection. The strongest model is not automatically the correct model for every task. Planning, document understanding, classification, extraction and semantic comparison have different requirements.

Using different Gemini models for different workloads allowed the system to match model capability to the actual complexity of the task instead of treating every AI operation as the same problem.

Where I want to take Kodi

The current hackathon implementation focuses on proving the autonomous Tax Case architecture, but the opportunity is much larger.

The Kodi platform includes tax computation, validation, tax knowledge, forms, reports, storage, document processing and other capabilities, although not all of them are currently enabled for autonomous use.

A mature tax agent should eventually be able to work across the complete tax lifecycle.

A taxpayer should be able to give Kodi an objective and let the system determine the relevant obligations, gather available information, identify missing evidence, ask only necessary questions, apply the correct rules, calculate tax, validate the result, prepare the required artifacts and support the next authorised compliance action.

For a tax professional, the same system could help manage many taxpayer cases without manually tracking every document, question, deadline and outstanding task.

For a business, it could coordinate tax obligations across payroll, accounting systems, invoices and financial records.

For governments and tax authorities, the same agentic principles could improve taxpayer assistance, evidence gathering, case management and compliance workflows.

The challenge is not simply switching every capability on and giving the agent access to everything.

The challenge is expanding autonomy carefully while preserving evidence, permissions, deterministic calculation, validation, recovery and auditability.

I believe the future of tax should not be another complicated form that expects the taxpayer to understand the entire process before they can begin.

It should feel more like this:

Tell Kodi what you need to achieve. Give it access to the information it is authorised to use. Let it work through the tax case with you.

That is the direction I am building toward.

Built With

Share this project:

Updates

Submission history