BlogBuilding an AI Tax Agent

AI Accountant Workpapers for Complex Tax Returns

Trace each reported value to a source-linked workpaper, surface conflicting facts, and prepare the questions a reviewer must resolve before filing.

Maya needs more than another assistant summarizing her tax folder. She needs someone to answer why a number appears in the draft, which document supports it, what changed since last year, and what must be resolved before a return can be approved.

An AI accountant for complex tax returns should produce workpapers, records that show how reported values were assembled, and an exception queue. It can reduce the time spent opening PDFs, copying values, matching transactions, and finding missing records. Uncertain tax positions must remain visibly unresolved.

This article uses “AI accountant” as a product label for an evidence-handling preparation system. It is not tax advice, and a taxpayer or qualified professional must make the final filing decisions.

The agent-app pattern below keeps one sandbox per customer, with the client’s documents on its filesystem. Every proposal the agent makes goes through a submit_proposal tool call. The host queues it as queued_for_approval, and nothing is filed until a human approves it. A reader can check each run’s turn.state, the tool loop’s stopReason, and each proposal’s queue status.

The useful unit is a claim with a citation

The smallest useful unit is a claim with its source, status, calculation impact, and history.

Maya’s folder might contain:

Record Candidate claim Question left open
Form W-2 (wage and withholding statement) wages and withholding for the tax year does it cover every employer?
brokerage statement proceeds and reported basis, the tax cost used to measure gain or loss which acquisition lot is connected?
partnership agreement 20% ownership did the percentage change before year end?
Schedule K-1 (pass-through tax statement) 15% ownership and pass-through items which source controls the draft?
wallet export transfers and digital-asset dispositions which addresses belong to Maya?
prior return carryovers and prior positions did a later correction change the starting value?

The Internal Revenue Service (IRS) digital-asset guidance says taxpayers need records that establish positions taken on a federal return. The IRS page for Form 8949, the form used to reconcile many sales and exchanges, describes reconciling reported amounts with the amounts reported on the return. Those sources justify preserving source links. They do not authorize an AI model to decide every digital-asset event.

The agent reads the client’s documents in one sandbox

client.instances.ensure is keyed by the customer, so each customer reaches one sandbox. instance.box.write puts a document on that filesystem, and instance.turn asks the agent on a thread. While the turn’s state is running, the sandbox keeps working; asking again with the same turnId settles it.

One sandbox per customer, reading a documentRan on production 2026-11-12 from these bytes, exit 0, @tangle-network/sandbox 1.0.168. View result.
import { readFile } from "node:fs/promises";
import { Sandbox } from "@tangle-network/sandbox";

const client = new Sandbox({
  apiKey: process.env.TANGLE_API_KEY!,
  baseUrl: "https://sandbox.tangle.tools",
});

// One sandbox per customer. The platform keeps it, resumes it, replaces it.
export async function review(customerId: string, turnId: string, contract: string) {
  const instance = await client.instances.ensure({
    key: `customer:${customerId}`,
    profile: {
      version: "contracts-v1",
      backend: {
        type: "opencode",
        profile: {
          name: "contract-review",
          prompt: {
            systemPrompt: "You review contracts. Cite the clause for every finding.",
          },
        },
      },
    },
    create: { resources: { cpuCores: 1, memoryMB: 2048, diskGB: 10 } },
  });
  await instance.box.write("contracts/msa.md", contract);
  const ask = "Review contracts/msa.md. List the indemnity, liability and termination risks.";
  let turn = await instance.turn(ask, { thread: "main", turnId });
  // Same turnId: pick the turn back up.
  while (turn.state === "running") {
    await new Promise((wait) => setTimeout(wait, 3_000));
    turn = await instance.turn(ask, { thread: "main", turnId });
  }
  return turn.state === "completed" ? turn.text : turn.state;
}

console.log(await review("acme", "review-1", await readFile("msa.md", "utf8")));

The run shows that the agent received the file and returned a completed answer. It does not show that the answer is correct. The claim ledger still needs the source page and a reviewer decision.

A claim ledger makes uncertainty inspectable

The claim ledger uses separate fields for extracted text, normalized values, review state, and source evidence. An empty field should never become a confirmed zero without an explicit decision.

The following is illustrative TypeScript for an application model, not a Tangle SDK type.

type ReviewState =
  | 'candidate'
  | 'needs-review'
  | 'accepted'
  | 'rejected'
  | 'superseded'

type Claim = {
  id: string
  field: string
  originalValue: string
  normalizedValue?: string | number
  source?: {
    document: string
    page?: number
    excerpt: string
  }
  state: ReviewState
  affects: string[]
}

const claim: Claim = {
  id: 'claim-ownership-001',
  field: 'partnership.ownership',
  originalValue: 'Maya Stone: twenty percent interest',
  normalizedValue: 0.2,
  source: {
    document: 'partnership-agreement.pdf',
    page: 4,
    excerpt: 'Maya Stone: twenty percent interest',
  },
  state: 'needs-review',
  affects: ['K-1 allocation', 'state allocation'],
}

console.log(claim)

The claim stays in needs-review even though it has a page reference. A citation proves where the text came from. It does not prove that the document is current, controlling, or interpreted correctly.

Reconciliation is a product feature

Reconciliation compares records that describe the same field or transaction, before the system totals or drafts schedules.

Consider Maya’s 20% agreement and 15% K-1. An ordinary data-entry tool imports the K-1 and moves on. An AI accountant puts both records in front of a reviewer:

Field Source A Source B Downstream effect
ownership 20% in agreement, page 4 15% on K-1, page 2 pass-through and state amounts may change
effective date March 3, 2025 January 31, 2026 determine which period each source describes
source type governing document candidate entity-issued tax statement ask taxpayer or advisor which controls
status needs review needs review block dependent draft lines

The same screen handles duplicate uploads, a transfer that appears in two wallet exports, and an amount whose currency or conversion date was never recorded.

The system keeps a conflict rather than collapsing it. This JSON example keeps both values:

{
  "field": "partnership.ownership",
  "values": [
    {
      "value": 0.2,
      "document": "partnership-agreement.pdf",
      "page": 4
    },
    {
      "value": 0.15,
      "document": "k1-statement.pdf",
      "page": 2
    }
  ],
  "state": "needs-review",
  "question": "Which ownership record governs the return period?"
}

Calculate from structured facts

After review, deterministic code calculates narrow quantities from typed inputs. The model may help extract a number, but the number’s meaning must also live in typed code.

Maya has $180,000 of wages, $2,400 of interest, and $25,000 of proceeds from a digital-asset disposition. Her acquisition record is missing, so the system reports $182,400 of ordinary-income candidates and leaves the gain candidate unresolved. “Ordinary-income candidates” is a preparation label for amounts routed to ordinary-income review, not a completed tax classification.

type ReturnInputs = {
  wages: number
  interest: number
  proceeds: number
  basis: number | null
}

type ReturnSummary = {
  ordinaryIncomeCandidates: number
  gainCandidate: number | null
  questions: string[]
}

function summarize(input: ReturnInputs): ReturnSummary {
  const questions = input.basis === null
    ? ['Provide acquisition records before calculating gain or loss.']
    : []

  return {
    ordinaryIncomeCandidates: input.wages + input.interest,
    gainCandidate: input.basis === null
      ? null
      : input.proceeds - input.basis,
    questions,
  }
}

const summary = summarize({
  wages: 180_000,
  interest: 2_400,
  proceeds: 25_000,
  basis: null,
})

console.assert(summary.ordinaryIncomeCandidates === 182_400)
console.assert(summary.gainCandidate === null)
console.assert(summary.questions.length === 1)

This is a workpaper calculation, not a tax-liability estimate. The IRS Form 1099-DA guidance explains that a broker’s digital-asset statement may report proceeds and in some cases basis, while the taxpayer remains responsible for reporting income, gains, and losses. An AI accountant should show whether a statement supplied basis or whether the value came from a separate acquisition record.

Where Tangle fits in the work session

Tangle coordinates reusable service packages and the operators that run them. The Sandbox product provides the isolated runtime for agent jobs. The product described here is an illustrative Tangle Tax Agent architecture, not a claim that Tangle currently offers accounting or tax advice.

The Tangle Blueprint documentation defines a Blueprint as a reusable service template. For this workflow, a Blueprint could describe a prepare-workpapers job, its accepted input package, its review-package output, and its storage requirements.

  • A service instance is one live deployment of that Blueprint. An operator runs it.
  • A runtime is the isolated environment where the parser, model calls, calculators, and document store operate.
  • An agent profile pins the model, tools, budget, and policies for Maya’s run.
  • A Tangle Router selects an operator or provider route for a model request. It does not choose a tax position.
  • A trace records the files opened, tools called, outputs produced, reviewer decisions, and failures.
  • An evaluation runs known cases and checks result, cost, and policy behavior. The set should include conflicting ownership, missing basis, duplicate uploads, unreadable scans, and an amended K-1.
  • Attestation is a signed report on measured code and hardware-backed execution, when the runtime uses one. It supports a privacy or code-identity claim, not a claim that the conclusion is correct.
  • x402 is an HTTP payment flow: a request returns 402 Payment Required and accepts payment proof on retry. On Tangle’s asynchronous Blueprint gateway, settlement admits the job with 202 Accepted, and the runner delivers the result separately. Payment proves the request was paid. It does not prove the workpaper is accurate or complete.

These terms follow Tangle’s core concepts page. The x402 standard documentation describes payment over HTTP.

The Sandbox quickstart shows the public SDK. Its health check runs before any synthetic documents are uploaded:

npm install @tangle-network/sandbox
curl -fsS https://sandbox.tangle.tools/health

That command tests reachability only. It does not establish retention, isolation, tax-rule coverage, or the quality of a generated workpaper.

Route filing through submit_proposal

The agent never files. It calls submit_proposal, and the handler queues the call for a certified human. buildAppToolOpenAITools advertises the four app tools, createAppToolRuntimeExecutor validates each call and routes it to the handlers, and runAppToolLoop re-runs the model until it stops. Dispatch stamps regulated on each regulatedTypes entry, and the handler must queue those rather than execute them. The same tool names apply when a sandboxed agent runs the turn.

import { buildAppToolOpenAITools, createAppToolRuntimeExecutor, type AppToolHandlers, type AppToolTaxonomy } from '@tangle-network/agent-app/tools'
import { createOpenAICompatStreamTurn, runAppToolLoop, type LoopMessage, type ToolLoopEvent } from '@tangle-network/agent-app/runtime'

const taxonomy: AppToolTaxonomy = { proposalTypes: ['file-return', 'amend-return', 'open-question'], regulatedTypes: ['file-return', 'amend-return'] }
// A product writes proposals to its own store. This list only shows the shape.
const queue: Array<{ proposalId: string; type: string; title: string }> = []
const handlers: AppToolHandlers = {
  async submitProposal(args) {
    const proposalId = `proposal-${queue.length + 1}`
    queue.push({ proposalId, type: args.type, title: args.title })
    return { proposalId, deduped: false, status: 'queued_for_approval' }
  },
  async scheduleFollowup(args) { return { id: `followup-${args.dueDate}`, dueDate: args.dueDate, deduped: false } },
  async renderUi(args) { return { path: 'workpapers/summary.json', content: JSON.stringify(args.schema) } },
  async addCitation(args) { return { citationId: `cite-${args.path}`, path: args.path } },
}
const tools = buildAppToolOpenAITools(taxonomy)
const model = createOpenAICompatStreamTurn({ baseUrl: 'https://router.tangle.tools/v1', apiKey: process.env.TANGLE_API_KEY!, model: 'glm-5.3', tools })
// The model turn also yields reasoning and usage events; the loop reads text and tool calls.
async function* streamTurn(messages: LoopMessage[]): AsyncGenerator<ToolLoopEvent> {
  for await (const event of model(messages)) {
    if (event.type === 'text' || event.type === 'tool_call') yield event
  }
}
const result = await runAppToolLoop({
  systemPrompt: 'Prepare the 2025 workpapers. Propose a file-return only after every fact is accepted.',
  userMessage: 'Wages $180,000, interest $2,400, proceeds $25,000, basis missing. Propose the next step.',
  streamTurn,
  executeToolCall: createAppToolRuntimeExecutor({ handlers, taxonomy, ctx: { userId: 'maya-stone', workspaceId: 'client-2025', threadId: 'return-2025' } }),
  isExecutableTool: (name) => tools.some((tool) => tool.function.name === name),
  maxToolTurns: 12,
})
console.log(result.stopReason, queue)

The fence proves that a proposal reaches the queue as queued_for_approval in this process. It does not prove the approval screen, the filing service, or the reviewer’s decision.

The packet should survive a handoff

An advisor should receive a packet that can be reviewed without replaying the AI conversation. Its source index lists every input file, page reference, processing result, and missing record. For Maya, the packet contains:

Packet section Contents Reviewer action
source index every file, page count, year, owner, and processing result confirm the input set
fact ledger original value, normalized value, source, state, and history accept, reject, or correct facts
calculation workpapers inputs, units, rule version, and outputs reproduce or challenge calculations
reconciliation report conflicts, duplicates, unmatched transfers, and late records resolve or escalate issues
missing-fact list requested document and the decision it would unblock collect the right evidence
draft forms forms and schedules marked unapproved review the proposed filing
correction log old value, new value, reviewer, and timestamp understand version changes

The packet uses version identifiers. If Maya supplies a corrected K-1, the product shows which calculations and draft lines changed, and it does not overwrite the old result.

The change trail should explain a revision

Suppose the first draft uses the 15% K-1 allocation while the partnership agreement is still needs-review. Maya then uploads an amended K-1 that applies to the full tax year. That changes a tax fact, so dependent outputs must be recalculated.

Event Fact state Required product response
first K-1 received 15% candidate, source page 2 keep dependent lines provisional
agreement conflict found 20% and 15% both need review ask which record controls the period
amended K-1 received 20% accepted by reviewer create a new draft version and recalculate
reviewer opens the packet old and new values visible show which forms and totals changed

The model can suggest that the amended document supersedes the earlier value. The application still requires a reviewer decision and deterministic recalculation before it marks the new lines accepted. The old packet stays in the history.

Privacy needs a retention story

An AI accountant may receive identity documents, bank records, wallets, entity agreements, and prior tax returns. The product tells the reviewer which artifacts are temporary and which must survive the filing lifecycle.

At minimum, define:

  • who can access the source files and derived claims;
  • which model endpoints can receive document text;
  • whether tools can make network requests;
  • how traces are redacted or exported;
  • how deletion handles backups and generated workpapers;
  • which approved packet remains available for the taxpayer and advisor.

The AI Agent Sandbox documentation describes the separation between the hosted application, on-chain lifecycle records, and the operator API for live runtime state. That architecture is a design reference. It does not replace the tax product’s own retention and access policy.

Where an AI accountant should stop

An AI accountant should stop, ask, or escalate when:

Trigger Required behavior
source is missing name the document and the calculation it blocks
source is unreadable preserve the file and request a better copy
sources conflict show both values and their pages
rule version is unclear hold the draft until a supported rule set is selected
a foreign corporation appears route the ownership and filing questions for review
basis cannot be established keep the gain or loss unresolved
a reviewer changes a fact create a new version and rerun affected calculations
a model or tool fails preserve the partial trace and retry state

The failure message should help a human recover. “Foreign corporation mentioned in subscription-agreement.pdf, page 8; ownership percentage and officer status are unconfirmed” is useful. “International issue detected” gives the reviewer no next step.

The same rule applies to Form 8621, the information return for certain passive foreign investment company shareholders, and to foreign tax credits. The IRS describes the conditions that can require Form 8621 and publishes separate foreign tax credit guidance. The product can identify the questions and attach the sources. It should not infer an election, classification, or credit from a document label.

Pick the product by the packet it leaves behind

Choose an AI accountant for complex tax returns when it leaves an inspectable packet with source pages, calculation inputs, unresolved exceptions, correction history, and approval state. Keep a simpler bookkeeping or filing tool when those source joins do not exist. If the product cannot show that packet, keep its output as an unapproved draft for a qualified reviewer.

What is an AI accountant?

An AI accountant is software that organizes financial records, extracts and links facts, performs controlled calculations, drafts preparation artifacts, and surfaces questions for human review.

Can an AI accountant replace a CPA?

No. It can reduce document and reconciliation work, but taxpayers and qualified professionals still make the final decisions for complex or uncertain positions.

What should an AI accountant produce?

It should produce a source index, claim ledger, calculations, reconciliation report, missing-fact list, draft forms or schedules, and correction history.

How should I review AI accountant output?

Open the source for every high-impact claim, check units and tax year, inspect conflicts and missing records, review changed versions, and confirm the approval state before relying on the draft.

Can Tangle provide the tax answer?

Tangle can provide public infrastructure patterns for a runtime, service definition, operator, payment edge, and recorded run. The tax product still needs its own rules, sources, review controls, and professional escalation.