Feature GuidesAgents

Session IDs

Identify agent sessions from supported coding agents and custom clients
View as Markdown

A session ID is the stable identifier Dynamo uses for one agent reasoning/tool chain. A root agent, planner, researcher subagent, or OpenCode subtask can each have its own session. Every LLM request in that chain should carry the same session_id; child sessions can also carry a parent_session_id so traces and replay tools can rebuild the tree. Some academic papers also call this a program_id.

Session identity is passive metadata. Sending X-Dynamo-Session-ID does not enable sticky sessions or change request placement. Tracing records the identity when DYN_REQUEST_TRACE is enabled, and a session-aware routing policy can consume it only when that policy is configured separately.

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.

HeaderNormalized agent_context fieldRequiredMeaning
X-Dynamo-Session-IDsession_idYesOne reasoning/tool chain inside the run.
X-Dynamo-Parent-Session-IDparent_session_idNoParent session when using subagents.
X-Dynamo-Session-Finalsession_finalNotrue marks the session’s last request for lifecycle-aware consumers.

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.

SourceSession inputParent inputDynamo behavior
Claude Codex-claude-code-session-id; x-claude-code-agent-id for child agentsInferred from x-claude-code-session-id when x-claude-code-agent-id differsRoot turns use the session header as session_id; child-agent turns use the agent header as session_id and the session header as parent_session_id.
Codexsession-idNonesession-id becomes the session_id.
OpenCodex-session-idx-parent-session-idx-session-id becomes the session_id; x-parent-session-id becomes parent_session_id when present.

X-Dynamo-Session-Final applies with either canonical or agent-native session identity.

Custom Agent Harnesses

For a custom HTTP client that only needs a session ID, send the generic header:

$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":"..."}]}'