Passing Context

Context tells the agent what the user is looking at — selected documents, active filters, a tag scope, uploaded documents, or records from an external system. Pass it via conversation_context at the top level of the request, or as a content_parts entry with type: "context" on a specific message.

tip

This is the API-side counterpart to Configuring Context Sources. The request sends context; the agent configuration controls which context sources are active.

Two Placement Options

Placement	When to use
Top-level conversation_context	Request-wide state: the page the user is on, active search filters, selected tag
Message content_parts with type: "context"	Context the user attaches to a specific turn, or preserved context from a previous agent response

Both use the same ConversationContext shape. You can combine them — e.g. pass filters at the top level and attach a document to the current message.

ConversationContext Fields

Field	Shape	Purpose
document_context	{ "document_ids": string[], "retrieval_unit": "document" | "chunk" }	Ground the answer in specific indexed documents or chunks
custom_context	{ "items": [{ "document_id": string, "content": string | object }] }	Pass arbitrary content not in Zeta Alpha's index
tag_context	{ "tag_ids": string[] }	Scope to a tag/collection the user is viewing
filter_context	{ "filters": object }	Forward active search filters
user_document_context	{ "enabled": boolean }	Include the user's uploaded documents

document_context and custom_context are mutually exclusive. The others combine freely.

Examples

Document Context (top-level)

Scope the conversation to specific indexed documents:

{
  "agent_identifier": "my-agent",
  "conversation": [
    {"sender": "user", "content": "Summarize this paper"}
  ],
  "conversation_context": {
    "document_context": {
      "document_ids": ["df40f22694ea7515ef8cd321d877e54c30d336ca_0"],
      "retrieval_unit": "document"
    }
  }
}

Custom Context (top-level)

Pass content from your own system. Each item needs a document_id (for citation linking via custom://{document_id} URLs) and content (string or JSON object):

{
  "agent_identifier": "my-agent",
  "conversation": [
    {"sender": "user", "content": "What's the weather on Tuesday?"}
  ],
  "conversation_context": {
    "custom_context": {
      "items": [
        {
          "document_id": "forecast-mon",
          "content": "The weather on Monday will be sunny"
        },
        {
          "document_id": "forecast-tue",
          "content": {
            "title": "Forecast for Tuesday",
            "prediction": "Cloudy",
            "temperature": "17°C"
          }
        }
      ]
    }
  }
}

Message-Level Context (content_parts)

Attach context to a specific message. Include a text part alongside it:

{
  "agent_identifier": "my-agent",
  "conversation": [
    {
      "sender": "user",
      "content": "Compare these documents",
      "content_parts": [
        {
          "type": "context",
          "context": {
            "document_context": {
              "document_ids": ["doc-id-1", "doc-id-2"],
              "retrieval_unit": "document"
            }
          }
        },
        {"type": "text", "text": "Compare these documents"}
      ]
    }
  ]
}

Full Streaming Example with Custom Context

import json
import os

import requests
import sseclient

TENANT = "zetaalpha"
url = f"https://api.zeta-alpha.com/v0/service/chat/stream?tenant={TENANT}"

headers = {
    "accept": "text/event-stream",
    "Content-Type": "application/json",
    "X-Auth": os.getenv("ZETA_ALPHA_API_KEY"),
}

response = requests.post(
    url,
    headers=headers,
    json={
        "agent_identifier": "chat_with_dynamic_retrieval",
        "conversation": [
            {"sender": "user", "content": "What's the weather on Tuesday?"}
        ],
        "conversation_context": {
            "custom_context": {
                "items": [
                    {"document_id": "myID_1", "content": "The weather on Monday will be sunny"},
                    {"document_id": "myID_2", "content": {"title": "Forecast for Tuesday", "prediction": "Cloudy", "temperature": "17°C"}},
                    {"document_id": "myID_3", "content": "The weather on Wednesday will be windy"},
                ]
            }
        },
    },
    stream=True,
)
response.raise_for_status()

client = sseclient.SSEClient(response)
for event in client.events():
    message = json.loads(event.data)

# Final response
print(message["content"])
print(message["evidences"])
# Evidence document_hit_url will be "custom://myID_2"

Dynamic Context in Responses

Agents may retrieve context while answering (e.g. via search). They include it in response content_parts:

{
  "sender": "bot",
  "content": "Based on the retrieved documents...",
  "content_parts": [
    {"type": "context", "context": {"document_context": {"document_ids": ["found-chunk-id"], "retrieval_unit": "chunk"}}},
    {"type": "text", "text": "Based on the retrieved documents..."}
  ]
}

When sending conversation history back to the API, preserve these content_parts — they let the agent retain context across turns without re-retrieving.