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

# Per-turn grounding citations: audit what an agent grounded a reply on

> Every agent turn — chat and voice — carries an audit of the knowledge chunks retrieved, the citations the model actually used, retrieval confidence, and the tools it called.

# Per-turn grounding citations

An AI agent that draws on your knowledge base can answer out of it — or it can answer *around* it, and the reply reads the same either way until the agent says something wrong. The grounding audit closes that gap: every turn the agent takes, on chat and on voice alike, carries a record of what the model actually grounded on.

## What each turn carries

Every completed turn exposes a `grounding` block on the agent runtime's response, alongside the flat fields that were already there. The audit is per turn, additive, and identical whichever channel the turn came through.

| Field                                     | Contents                                                                                                                                                                      |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chunks`                                  | Knowledge-base chunks retrieved for this turn, in retrieval order, each with its cosine similarity score and the document it came from. Empty when the turn had no retrieval. |
| `citations`                               | The chunks the model *actually cited* inline — `[KB-N]` markers in the reply resolved back to chunk metadata. A subset of `chunks`, and empty when the model cited nothing.   |
| `confidence`                              | The turn's retrieval confidence — the highest similarity score across `chunks`, clamped to `0…1`. `null` (not `0`) when no retrieval happened.                                |
| `tools`                                   | Tool calls the turn made, each with name, arguments, result, duration, and status — so failed tool calls are on the record as well as successful ones.                        |
| `model`                                   | The model id that produced the reply, or `null` when the agent used the platform default.                                                                                     |
| `tokens_used`, `cost_cents`, `latency_ms` | The turn's telemetry, mirrored into the block so the block alone is enough to debug a turn.                                                                                   |

`citations` is the part that makes it an audit rather than just a retrieval log: the model *received* the chunks in context, and it *chose* which — if any — to cite inline. `chunks` tells you the surface retrieval found; `citations` tells you what the answer actually stood on.

## Voice agents get the same audit

Voice agents run on the same agent runtime as chat agents — the voice gateway calls it turn by spoken turn. The grounding audit is attached to every turn either way, with nothing to configure and no second surface to learn: if a chat agent grounded its answers, its voice twin grounds them identically, and the audit follows.

For each spoken turn the caller hears, the operator can answer three questions afterward: what knowledge was in front of the model, what it cited, and how well retrieval matched.

### Read the audit in the dashboard

Open **Agents → your agent → Conversations → a conversation → turn debug**. Per turn, the retrieval hits and tool calls are expandable inline with the transcript — the same surface that carries the turn's latency and cost already carries its grounding audit.

A `null` confidence on a turn means the agent answered without a retrieval pass — read that as "no knowledge grounding ran this turn", not as a score of zero.

## The citations-audit surface: grade every turn, one verdict per turn

The audit also feeds a dedicated review surface that grades each turn's citations against what retrieval actually found. Open **Agents → your agent → the "Citations audit" tab** — each turn is labeled one of four verdicts:

* **`ok`** — retrieval ran and the model cited a valid marker. The answer stood on knowledge.
* **`no_marker`** — retrieval ran but the model emitted no `[KB-N]` marker. An ungrounded answer slipped through.
* **`orphan_marker`** — the model emitted marker(s) but either nothing was retrieved, or every marker index pointed past the retrieval window. That's a hallucinated citation, and the conversation view silently drops these markers — this audit is the only place they are visible.
* **`empty_retrieval`** — no retrieval and no markers (a greeting, a small-talk turn). Counted separately so a "no KB" setup doesn't read as 100 % ungrounded.

The tab shows a page-scoped rollup — ground-rate, count per verdict — that refolds as you page through, and each row is owned by the same verdict the API computes. Accessible to workspace roles with agent read access (owner, admin, developer).

### Via the API

The same verdicts are available programmatically, per agent, newest first:

```
GET /agents/:id/grounding/citations?limit=50
    &cursor=<opaque-cursor>
    &from=2026-08-01T00:00:00Z
    &to=2026-08-25T00:00:00Z
```

Each page returns:

| Field         | Contents                                                                                                                                                                                                                                               |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `rows[]`      | Per-turn verdicts: the reason, the cited chunk indexes, the raw marker count, and the retrieval metadata the turn grounded on. Only pointer metadata comes back — the verbatim transcript stays behind the supervisor-only conversation audit surface. |
| `summary`     | Page-scoped rollup: turns with retrieval, grounded vs ungrounded counts, the grounded rate (`null` when nothing retrieved), and a count per verdict.                                                                                                   |
| `next_cursor` | Pass it back to walk older pages; `null` at the end.                                                                                                                                                                                                   |

`limit` accepts 1–200 (default 50). No new storage — the audit reads the same per-turn governance records the agent runtime already writes.

A **tenant-wide voice rollup** lives at `GET /agents/grounding-citations-audit` for owner/admin roles: totals across every voice agent, a per-agent breakdown, the most recent ungrounded turns as a triage list, and a daily trend.

## Enforce citations for high-trust agents

The audit is observational — it reports, it doesn't block. When a turn that drew on retrieved knowledge must *refuse* to answer uncited — on a healthcare line, a financial disclosure, a regulated workflow — opt the agent in with `safetyConfig.require_citation`.

With the flag on, a turn that received retrieval context and emitted no well-formed `[KB-N]` marker fails the output guardrail instead of being delivered. Turns with no retrieval (a greeting, an off-topic reply) pass through unaffected; enforcement only bites on a grounded turn. See the model's `[KB-N]` citation convention in your agent's system prompt and the `require_citation` field on the safety config.