Handling Citations

Agents that ground their answers in documents return citation markers in the response text and corresponding evidence objects. This guide explains how to parse and render them.

Evidence Structure

Each agent response may include an evidences array:

{
  "sender": "bot",
  "content": "BERT is a bidirectional model <sup>1</sup> developed by Google <sup>2</sup>.",
  "evidences": [
    {
      "document_hit_url": "/documents/chunk/list?tenant=zetaalpha&property_name=id&property_values=abc123_0",
      "text_extract": "BERT 101\n<b>BERT is a deeply bidirectional, unsupervised language representation model.</b>",
      "anchor_text": "<sup>1</sup>"
    },
    {
      "document_hit_url": "/documents/chunk/list?tenant=zetaalpha&property_name=id&property_values=def456_0",
      "text_extract": "What is BERT?\n<b>In 2018 Google developed a transformer-based NLP pretraining model called BERT.</b>",
      "anchor_text": "<sup>2</sup>"
    }
  ]
}

Field	Description
document_hit_url	Relative URL path to retrieve the source document or chunk
text_extract	The relevant passage, with the key sentence wrapped in <b> tags
anchor_text	The citation marker as it appears in content (e.g., <sup>1</sup>, <sup>abc123</sup>)

Rendering Citations

The anchor_text field tells you exactly where in the response text each citation appears. Replace it with your preferred UI element:

content = message["content"]
for evidence in message.get("evidences") or []:
    anchor = evidence["anchor_text"]
    link = f'<a href="{evidence["document_hit_url"]}">{anchor}</a>'
    content = content.replace(anchor, link)

Common Patterns

Pattern	Description
Clickable superscript	Replace anchor_text with a link to the document
Tooltip preview	Show text_extract on hover over the citation marker
Side panel	Clicking a citation opens the source document in a side panel
Numbered list	Collect all evidences and render a numbered reference list below the answer

Citation Formats

The format of anchor_text depends on the agent's citation policy configuration:

• Numbered — <sup>1</sup>, <sup>2</sup>, etc.
• Hash-based — <sup>a1b2c3d4</sup> (short hash of the document ID)
• Named — <sup>doc0_chunk1</sup> (document index + chunk position)

Always use the anchor_text field to match citations — do not hard-code a format.

Custom Context Citations

When using custom_context, the document_hit_url has the format:

custom://{document_id}

Where document_id matches the ID you passed in the custom_context.items array. Use this to link citations back to your own data:

for evidence in message.get("evidences") or []:
    url = evidence["document_hit_url"]
    if url.startswith("custom://"):
        doc_id = url[len("custom://"):]
        # Look up your own data by doc_id

Multi-Turn Conversations

Evidences are specific to the message they appear in. When displaying a conversation thread, render citations per message — each agent response has its own evidences array independent of other messages in the conversation.