Render inline citations

When an agent answers using data it retrieved from connectors, the orchestrator embeds inline citations that link each claim in its answer text to the specific source data part that backs it. The server strips the citation markers from all client-visible text and delivers the citations as structured metadata on the artifact, so you can render clean prose while still linking each claim to its source. This guide explains the citation metadata, how to resolve a citation to its source data part, and how to render citations. It also covers the orchestrator-only restriction and the graceful error handling the server applies.

Prerequisites

An existing agent with at least one connector that produces data parts (for example, PubMed or Medical Coding)
Understanding of the task lifecycle, artifacts, and parts
Understanding of streaming responses

How inline citations work

The orchestrator receives the user message and decides which connectors to call.
Each connector call produces one or more data parts stored on the task. Every data part gets a stable data part ID (GID) such as tool_data_01.
The orchestrator writes its answer text and embeds citation markers that reference the GIDs of the data parts it used.
The server parses the markers, strips them from the text, and attaches a citations array to the answer artifact’s text part metadata.
The cited data parts are emitted alongside the answer text in the same artifact, each carrying its GID in its metadata.dataPartId.

You render the answer text verbatim and use the citations metadata to link each claim back to its source data part.

Inline citations are produced by the orchestrator only, the agent runtime that serves your top-level task. Connector (expert) sub-answers do not embed citation markers themselves; their outputs are data parts that the orchestrator then cites or passes through. You only need to handle citations on the top-level task answer.

Marker format

The orchestrator uses the OpenAI citation formatting guide, with three private-use Unicode characters as delimiters:

Codepoint	Name	Role
`U+E200`	citation start	Opens a marker
`U+E202`	citation delimiter	Separates fields inside a marker
`U+E201`	citation stop	Closes a marker

A marker has the form:

\ue200cite\ue202<source_id>\ue201                 whole-part citation
\ue200cite\ue202<source_id>\ue202<locator>\ue201   citation with a locator

cite: backs a claim with a source. The marker is stripped from the text and an entry is added to the citations metadata.
<source_id>: the GID of the cited data part, for example tool_data_02.
<locator>: an optional sub-reference into the cited part: a JSON Pointer path such as /data/5/population, or a line range such as L8-L13. Empty means the whole part is the source.

You should never observe raw U+E200 / U+E202 / U+E201 characters in text you receive from the API. The server strips all valid markers before the artifact reaches you. If you do see these codepoints, treat the text as malformed. Do not display the markers to users.

Citation metadata

Citations ride on the text part metadata of the answer artifact, not on the data parts. The text part metadata contains a citations key: an array with one entry per citation marker, in text order. Each entry in the citations array has the following fields:

Field	Type	Description
`data_part_id`	string	GID of the cited data part (for example `tool_data_02`); join this against the cited part’s `metadata.dataPartId`
`offset`	int	Character (rune) offset into the joined artifact text where the marker stood, snapped past any trailing punctuation so the citation lands on a clause boundary
`locator`	string	JSON Pointer (for example `/data/0/name`) or line range (for example `L8-L13`); empty means the whole part is the source

The array is sorted by offset.

Example: answer with citations

A PubMed-backed answer whose text part metadata looks like this:

{
  "text": "Doxorubicin is associated with dose-dependent cardiotoxicity. The recommended cumulative dose limit is 450 mg/m².",
  "metadata": {
    "citations": [
      { "data_part_id": "tool_data_02", "offset": 53, "locator": "/results/0/findings" },
      { "data_part_id": "tool_data_03", "offset": 107, "locator": "" }
    ]
  }
}

The cited data parts appear as sibling parts in the same artifact, each carrying its GID:

{
  "data": {
    "value": {
      "results": [
        { "findings": "Doxorubicin carries a dose-dependent risk of cardiomyopathy." }
      ]
    }
  },
  "metadata": {
    "dataPartId": "tool_data_02",
    "toolName": "pubmed_search"
  }
}

To resolve the first citation: take data_part_id (tool_data_02), find the sibling part whose metadata.dataPartId equals tool_data_02, then apply the locator (/results/0/findings) as a JSON Pointer to that part’s data.value.

Streaming and citations

When the answer is streamed, the orchestrator emits one text part per token delta, then a closing event that replaces the deltas with the canonical consolidated text. The citations metadata is attached to that final consolidated text part.

Offsets index the joined artifact text, the concatenation of all text parts in order. If you process the artifact as multiple parts, join them before applying offsets. Do not apply an offset to a single part.

During streaming, the server also strips citation markers from each delta as it arrives, so partial markers never reach your client even when a delta splits a marker across a chunk boundary.

Render citations

The text you receive is already clean (markers stripped). Render it verbatim and use the citations metadata to add your own citation UI:

Read metadata.citations.
For each entry, insert your rendered citation marker (superscript, footnote, or popover) at offset characters into the joined artifact text.
Resolve data_part_id to the sibling data part whose metadata.dataPartId matches.
If locator is non-empty and starts with /, apply it as a JSON Pointer to the part’s data.value to highlight the specific field. If it matches L<digits> or L<digits>-L<digits>, treat it as a line or line-range reference. If empty, cite the whole part.

Best practices

Do

Render the artifact text verbatim. The server has already stripped markers; do not attempt to find or strip U+E200 / U+E202 / U+E201 yourself.
Join all text parts of the artifact in order before applying offsets. Offsets index the concatenated text, not any single part.
Treat offset as a character (rune) offset, not a UTF-8 byte offset.
Resolve citations by data_part_id, joining against the cited part’s metadata.dataPartId.
Apply locator as a JSON Pointer when it starts with /, or as a line range when it matches L<digits>. Fall back to citing the whole part when the locator is empty or does not resolve.

Don’t

Don’t display raw U+E200 / U+E202 / U+E201 markers. They are private-use codepoints that render as nothing or boxes. If you see them, treat the input as malformed.
Don’t treat offsets as byte offsets, or apply them to a single text part.
Don’t fail the whole response if a locator doesn’t resolve. The server keeps the citation with its locator intact; mirror that by falling back to citing the whole data part.
Don’t treat user_data_* or user_text_* GIDs as resolvable citation targets. The server rejects user-origin parts as citation sources; guard against them on the client as well.

Graceful error handling

Citations never fail a task. The server handles malformed citations gracefully, and your client should mirror that behavior:

Condition	Server behavior	Client handling
Invalid marker (does not match the grammar)	Kept as literal text; logged	Render the text as normal prose
Unknown GID (the cited data part is missing)	Citation dropped; logged	You will not receive an entry for it
Unresolvable JSON Pointer locator	Citation kept with the locator intact	Fall back to citing the whole data part
User-origin GID (`user_data_`, `user_text_`)	Rejected as a citation target	Guard against these GIDs

If every cited part was user-origin and no answer text was produced, the server retries rather than completing with an empty artifact.

Orchestration and persistence

The orchestrator’s system prompt instructs it to emit citation markers only when it has backing source data parts. The raw text with markers intact is persisted internally for cache reuse across turns, but the artifact you receive always contains the clean text and resolved citation metadata. Connector outputs reach the user only when the orchestrator cites them in its final answer. Calling a connector produces a data part, but only a citation marker in the orchestrator’s text passes that data part through to the client artifact.

Next steps

Learn how to stream responses and consume token deltas
Read about the task lifecycle and artifacts
Explore registry connectors that produce citable data parts

Quickstart

Concepts

Guides

Reference

Registry Connectors

Agent SDK

v1 Documentation (archived)

Prerequisites

How inline citations work

Marker format

Citation metadata

Example: answer with citations

Streaming and citations

Render citations

Best practices

Do

Don’t

Graceful error handling

Orchestration and persistence

Next steps

​Prerequisites

​How inline citations work

​Marker format

​Citation metadata

​Example: answer with citations

​Streaming and citations

​Render citations

​Best practices

​Do

​Don’t

​Graceful error handling

​Orchestration and persistence

​Next steps

Prerequisites

How inline citations work

Marker format

Citation metadata

Example: answer with citations

Streaming and citations

Render citations

Best practices

Do

Don’t

Graceful error handling

Orchestration and persistence

Next steps