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 unless session affinity is explicitly enabled. Sending X-Dynamo-Session-ID alone does not change request placement. Tracing records the identity when DYN_REQUEST_TRACE is enabled. When --router-session-affinity-ttl-secs is configured, the router uses the ID for an immutable endpoint- and phase-scoped worker binding.

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 agentsx-claude-code-parent-agent-id; falls back to x-claude-code-session-idRoot turns use the session header as session_id; child-agent turns use the agent header as session_id. Nested children use the parent-agent header as parent_session_id; top-level children use the root session header.
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. With session affinity enabled, a final request routes normally and then terminally closes its binding. Close invalidation across replicas is eventual. Do not send more requests with that session ID after close.

etcd and FileStore on a shared filesystem coordinate bindings across frontend processes. MemoryStore and Kubernetes discovery retain process-local affinity only. The affinity TTL controls local cache cleanup, not the distributed claim lifetime. Claims follow the creating frontend’s etcd lease or FileStore ownership. If a claim expires or its bound worker disappears, create a new session with a new ID instead of reusing or rebinding the old ID. See Router session affinity for the full contract.

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