How the Agent Answers

When you ask the agent a question, in the app or via `POST /v1/ask`, it does not run a retrieval-augmented prompt over a pile of chunks. It runs a full agent turn over a corpus that was structured at ingestion: every document already has OCR markdown, captured fields with provenance, and a place in the field registry before the first question arrives. The turn plans its own retrieval, queries structured data directly, gathers evidence, writes the answer, and then has that answer checked. This page explains each stage so you can predict what the agent will be good at and read its output critically.

Three retrieval planes

The agent looks for relevant material on three planes at once. The field-registry plane matches the question semantically against the canonical field concepts discovered across your documents: a question about "contract end dates" finds the registry concept for termination dates even if no document uses that exact phrase. The value plane matches lexically over the extracted cell values themselves: asking about "Globex" finds every document where that string was captured as a party, vendor, or counterparty. The text plane runs semantic and full-text search over the raw document text through a persistent chunk index, catching prose that never became a structured field. Because all three planes are consulted, the agent is not hostage to any single representation of your data.

SQL over the structured plane

For counting, listing, and aggregating, the agent runs read-only SQL over the structured cell plane. "How many of our agreements auto-renew?" is answered by a query over extracted cells with the denominator taken from real corpus coverage, not by reading a sample of documents and extrapolating. This is the decisive difference from chat-over-RAG tools: aggregate questions get database answers, and the coverage plane turns absence into evidence, so "no document mentions an exclusivity clause" is a checkable corpus-wide statement rather than a guess from an empty search.

Extract-and-persist at query time

When a question needs a concept that was captured at ingestion but never bound into the queryable plane, the agent promotes it on the spot: an instant, LLM-free, reversible operation that lifts the already-extracted values into structured cells. When the concept was never extracted at all, the agent can mine it from the document text. Either way the result is persisted: the second time anyone asks about that concept, in the app or over the API, the answer is a plain SQL read. Your corpus becomes progressively more structured along the exact lines your team actually cares about, driven by the questions themselves.

Citations and the verification badge

Every load-bearing claim in an answer carries a citation that deep-links to the source document with the exact span highlighted: click it and you are looking at the sentence or the captured field the claim came from. After the answer is written, a separate verification pass re-checks its claims against the evidence the turn itself gathered, and the verdict is shown as a badge on the answer: supported, issues, or unverifiable.

Asks are read-only with respect to your workspace configuration. Through the public API the turn runs under the least-privilege viewer role, and in the app the agent respects your team role: a question never edits documents, schemas, pipelines, or settings. The same machinery is available programmatically, with the citations returned as a structured array and the verification verdict in the payload.

curl -s -X POST https://api.talonic.com/v1/ask \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question": "Which agreements auto-renew, and with what notice period?"}'

{
  "status": "completed",
  "answer": "Two agreements auto-renew. The [Acme master services agreement](https://app.talonic.com/documents/1b6f...?citeq=renews%20automatically) renews automatically with [90 days notice](https://app.talonic.com/documents/1b6f...?cite=notice_period_days)...",
  "citations": [
    { "quote": "90 days notice", "kind": "field", "reference": "notice_period_days", "document_id": "1b6f...", "app_url": "https://app.talonic.com/documents/1b6f...?cite=notice_period_days" }
  ],
  "verification": { "verdict": "supported", "checks_total": 4, "checks_unsupported": 0 }
}