跳到导航
Agents

Identify Agent Sessions

Tell Dynamo which requests belong to which agent session
以 Markdown 格式查看

By the end of this guide, every LLM request from your agent carries a session ID, and subagent requests point to their parent. Dynamo uses that identity to group requests in traces and replay, to keep a session on one worker when you enable session affinity, and for any session-aware routing policy you configure.

Most coding agents send a session ID on their own. See Connect an Agent Harness to confirm yours does. If you are building a custom client, send the header below on every request in a reasoning chain:

Custom client with session ID
curl http://localhost:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk-dummy' \
  -H 'x-dynamo-session-id: research-run-42:researcher' \
  -d '{"model":"my-model","messages":[{"role":"user","content":"..."}]}'

Use One ID Per Reasoning Chain

Use one session_id for one agent reasoning and tool-use chain. A root agent, planner, researcher subagent, or OpenCode subtask can each have its own ID. Child sessions can also send a parent ID so traces and replay tools can rebuild the tree. Some academic papers call this a program_id.

Session ID Inputs

Custom clients should send the canonical Dynamo headers. When X-Dynamo-Session-ID is present, Dynamo uses it and X-Dynamo-Parent-Session-ID instead of any agent-native identity values.

X-Dynamo-Session-ID
stringRequired

One reasoning or tool chain inside the run. Maps to agent_context.session_id.

X-Dynamo-Parent-Session-ID
string

Parent session when using subagents. Maps to agent_context.parent_session_id.

X-Dynamo-Session-Final
boolean

Set to true on a dedicated minimal request when the session ends. Lifecycle-aware consumers can release per-session state immediately instead of waiting for an idle timeout. This works with canonical or agent-native session identity and maps to agent_context.session_final.

Native Agent Headers

Dynamo also recognizes the current stable identity headers emitted by the following coding agents. The frontend API surface compliance test catches header changes as coding agents evolve. See Connect an Agent Harness for packaged setup.

Dynamo reads Claude Code headers and normalizes them to session_id and parent_session_id:

  • x-claude-code-session-id for root turns
  • x-claude-code-agent-id for child-agent turns
  • x-claude-code-parent-agent-id for nested children; top-level children fall back to x-claude-code-session-id

Session identity is passive metadata. Sending a session ID does not enable sticky sessions or change request placement. Tracing records the identity when DYN_REQUEST_TRACE=1 is enabled, and a session-aware routing policy can consume it only when that policy is configured separately. To keep a session on one worker, see Maintain session affinity.

Captured Agent Headers

Dynamo carries raw coding-agent HTTP headers in AgentContext.agent_headers without interpreting them. Capture includes the open x-claude-code-* and x-codex-* families alongside supported session and subagent headers. Names within those families are not hardcoded: new headers are captured without a Dynamo schema change. Header names and values can change as coding harnesses evolve. Plugin authors and trace consumers own any parsing or normalization between harnesses.

Names are lowercase. Values remain strings, including malformed JSON, percent encoding, whitespace, empty values, and repeated values in their received order. Core code only normalizes session identity and the explicit Dynamo terminal marker.

Capture requires a recognized session identity and is bounded to 64 header values, 16 KiB per value, and 32 KiB total, counting the name once per value. Sensitive-marked and non-text values are skipped. Values exceeding the limits are omitted whole; retained values are never truncated. Missing metadata means no observation was captured, not that an event did not occur. Ordinary authentication, cookie, and unrelated protocol headers are excluded. Do not place credentials in an agent metadata header; these values are exposed to plugins and request traces.

The map travels through the frontend and worker request envelope and is available through plugin SessionContext.agent_headers(). It contains HTTP headers only; request-body metadata is not captured. The default routing policy does not interpret the map. See Trace an Agent Run for the request-trace format and Custom Worker Selection for plugin access.

For Claude Code custom endpoints, enable gateway hints with CLAUDE_CODE_GATEWAY_HINT_HEADERS=1. Its gateway protocol defines the header semantics. Preserving observations in AgentContext does not implement transparent Anthropic request-body or header forwarding to upstream providers.

Next