Skip to main content
An agent that spawns a subagent sends two independent streams of requests. The subagent starts with its own system prompt and its own history, so it cannot reuse the parent’s session id. Without a nest signal the gateway records the subagent as a separate top-level conversation, and the work it did reads as unrelated traffic. Subagent correlation fixes that. A spawned conversation nests under its parent, and the parent lists its subagents in a Subagent sessions table, where each row links to the child conversation.
Subagent sessions table showing two Claude Code subagent conversations with model, API key, activity, usage, and last active time

Subagent sessions for one conversation. Each row is a subagent conversation with its own model, request count, tool calls, and token usage.

​
With off-the-shelf headers

When you use x-session-id or x-session-affinity as the session signal, x-parent-session-id carries the parent pointer on its own. It needs no matching <name>, because the generic session headers have no name to match.
Common agent harnesses like Codex, Claude Code, and OpenCode send these headers natively without requiring any custom code.

​
Custom applications

Give each spawned subagent its own session id, and name the parent’s. The parent header must use the same <name> as the session header. A parent header whose <name> does not match the session header is ignored. For example, a custom application built with LangChain could use the following header structure:
The first value is the subagent’s own session id. The second value is the session id of the conversation that spawned it, exactly as that conversation sends it. Follow these four rules:
  • Give each spawned subagent a fresh session id of its own. Never reuse the parent’s session id for a child.
  • The parent value is the parent’s session id exactly as the parent sends it. Do not transform it.
  • Point at the conversation that directly spawned the subagent, not at the root of the whole run. A subagent of a subagent names its immediate parent.
  • The link fills in on a later request if the subagent’s first request arrives before its parent has sent anything.