> ## Documentation Index
> Fetch the complete documentation index at: https://claritylabs.inc/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Agent Pipeline: Citations and Grounded Answers

> Learn how the 6-phase query agent answers insurance questions against stored documents with grounded, citation-backed, verifiable responses.

The query agent transforms natural-language questions into grounded, citation-backed answers by running your question through a structured multi-phase pipeline. Each phase builds on the previous one — from interpreting any attached files, through parallel retrieval and reasoning, to a final verified response with inline source references. You get a confidence score, follow-up suggestions, and a full token usage report alongside every answer.

## Quick Start

Install the SDK and wire up your stores, then create an agent instance and call `agent.query()`.

```typescript theme={"system"}
import { createQueryAgent } from "@claritylabs/cl-sdk";

const agent = createQueryAgent({
  generateText,
  generateObject,
  documentStore,
  memoryStore,
  sourceRetriever,
});

const result = await agent.query({
  question: "What is the deductible on our GL policy?",
  conversationId: "conv-123",
});

console.log(result.answer);
// "The general liability policy has a $1,000 per-occurrence deductible [1]."

console.log(result.citations);
// [{ index: 1, chunkId: "doc-456:coverage:0", quote: "...", ... }]

console.log(result.confidence); // 0.92
```

### Querying with Attachments

Pass one or more `attachments` alongside your question. The pipeline interprets each file during Phase 1 before retrieval begins, so evidence from the attachments is available to every downstream reasoner.

```typescript theme={"system"}
const result = await agent.query({
  question:
    "What details should we collect from this photo, and is there policy context?",
  conversationId: "conv-123",
  attachments: [
    {
      kind: "image",
      name: "damage.jpg",
      mimeType: "image/jpeg",
      base64: damagePhotoBase64,
    },
    {
      kind: "pdf",
      name: "coi.pdf",
      mimeType: "application/pdf",
      base64: coiPdfBase64,
    },
  ],
});
```

***

## Pipeline Phases

The query agent runs six sequential phases for every question. Retrieval and reasoning phases run in parallel across sub-questions to keep latency low.

**1. Interpret Attachments**

If attachments are present, the agent processes each one with a vision-capable or PDF-aware model. Each interpreted file becomes an `EvidenceItem` that flows into the retrieval and reasoning phases alongside document store results.

**2. Classify**

The question is classified into a `QueryIntent`, broken into sub-questions, and evaluated for storage requirements. Classification drives which retrieval strategies run in Phase 4.

**Supported intents:** `policy_question` · `coverage_comparison` · `document_search` · `claims_inquiry` · `general_knowledge`

**3. Plan Retrieval and Retrieve**

The planner checks whether a lookup is actually needed — for example, if the conversation history already contains a complete answer, retrieval can be skipped entirely. This keeps token usage low for follow-up questions.

When retrieval is needed, four strategies run in parallel up to the configured `concurrency` limit:

* **Chunk search** — semantic similarity search across indexed document chunks
* **Document lookup** — structured look up by carrier, policy number, or document type
* **Source retrieval** — fetches raw source spans via the optional `SourceRetriever`
* **Conversation history** — recent turns for continuity and reference

Results are merged and deduplicated into a ranked evidence list.

**4. Reason (Parallel)**

Each sub-question gets its own reasoner, and they all run in parallel. Critically, **each reasoner only sees its assigned evidence items — never full documents.** This constraint enforces grounding and makes citation tracking possible: every factual claim maps back to a specific chunk.

**5. Verify**

The verifier checks three properties across all sub-answers:

* **Grounding** — every claim has a citation that actually supports it
* **Consistency** — sub-answers don't contradict each other
* **Completeness** — the original question is fully addressed

If any check fails, the verifier can trigger a targeted retry on specific sub-questions before the pipeline advances.

**6. Respond**

Sub-answers are merged into a single coherent response. Citations are deduplicated and assigned sequential display numbers (`[1]`, `[2]`, etc.). The final `QueryOutput` is returned with the answer, citations, confidence score, and review report.

> [!NOTE]
>
> Reasoners only see evidence items, never full documents. This design forces grounding and enables precise citation tracking — every `[n]` reference in the answer maps to a specific chunk ID and quoted passage.

***

## Configuration

Pass options to `createQueryAgent()` to tune retrieval depth, parallelism, and observability hooks.

```typescript theme={"system"}
const agent = createQueryAgent({
  generateText,
  generateObject,
  documentStore,
  memoryStore,
  sourceRetriever,      // optional SourceRetriever
  concurrency: 3,       // max parallel retrievers / reasoners
  maxVerifyRounds: 1,   // verification loop iterations
  retrievalLimit: 10,   // max evidence items per sub-question
  retrievalMode: "hybrid",
  onTokenUsage: (usage) => void,
  onProgress: (message) => void,
});
```

**generateText** `GenerateTextFn` *required*

Text generation function from your AI provider (e.g. Vercel AI SDK's `generateText`).

**generateObject** `GenerateObjectFn` *required*

Structured object generation function for classification and reasoning schemas.

**documentStore** `DocumentStore` *required*

Store used for chunk search and document lookup during retrieval.

**memoryStore** `MemoryStore` *required*

Conversation memory store used to retrieve and persist turn history.

**sourceRetriever** `SourceRetriever`

Optional retriever for raw source spans. When omitted, source retrieval is skipped.

**concurrency** `number` (default: 3)

Maximum number of retrievers or reasoners to run in parallel.

**maxVerifyRounds** `number` (default: 1)

How many times the verifier may trigger a targeted retry before accepting the current answers.

**retrievalLimit** `number` (default: 10)

Maximum number of evidence items fetched per sub-question during retrieval.

**retrievalMode** `"hybrid" | "semantic" | "keyword"` (default: "hybrid")

Strategy used when searching document chunks. `hybrid` combines semantic and keyword matching.

**onTokenUsage** `(usage: TokenUsage) =\> void`

Callback fired after each phase with a cumulative token usage snapshot.

**onProgress** `(message: string) =\> void`

Callback fired with a human-readable progress message at each phase transition.

***

## Output Shape

Every call to `agent.query()` resolves to a `QueryOutput` object.

```typescript theme={"system"}
interface QueryOutput {
  answer: string;
  citations: Citation[];
  intent: QueryIntent;
  confidence: number;
  followUp?: string;
  tokenUsage: TokenUsage;
  reviewReport: QueryReviewReport;
}
```

**answer** `string`

The final merged answer with inline citation markers like `[1]`, `[2]`.

**citations** `Citation[]`

Ordered list of citations referenced in the answer. See the [Citations guide](https://claritylabs.inc/docs/cl-sdk/query/citations.md) for the full `Citation` shape.

**intent** `QueryIntent`

Classified intent: `policy_question` · `coverage_comparison` · `document_search` · `claims_inquiry` · `general_knowledge`.

**confidence** `number`

Aggregate confidence score from `0` to `1` reflecting grounding quality and evidence coverage.

**followUp** `string`

Optional suggested follow-up question surfaced by the reasoner when the answer is partial or ambiguous.

**tokenUsage** `TokenUsage`

Total prompt and completion tokens consumed across all phases.

**reviewReport** `QueryReviewReport`

Detailed grounding, consistency, and completeness report from the verifier phase.

***

## Query Intents

The classifier assigns one of five intents to every question. The intent controls which retrieval strategies are prioritised in Phase 4.

| Intent | Description | Retrieval focus |
| - | - | - |
| `policy_question` | Specific coverage, limits, or deductibles | Coverage and declaration chunks |
| `coverage_comparison` | Comparing coverages across documents | Coverage chunks from multiple documents |
| `document_search` | Finding a document by carrier, number, or name | Structured document lookup |
| `claims_inquiry` | Claims history or loss experience questions | Loss history chunks |
| `general_knowledge` | Insurance concepts not tied to a document | Broader chunk search |

> [!TIP]
>
> For `coverage_comparison` queries, set `retrievalLimit` higher (e.g. `20`) so the agent can gather sufficient evidence from each document before reasoning begins.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.