Skip to main content
When an agent delegates work to a subagent, the subagent runs in a session of its own. The parent session’s transcript records the delegation, and the child session is retrievable like any other, so you can show the parent’s reply, each subagent as a step under it, and drill into what a subagent did.

​
The parent’s transcript

Delegation shows up in the assistant message parts of the parent session. The agent’s message_agent tool call is a normal tool_invocation part. Each subagent it launched is a subagent_invocation part whose parentToolCallId is that tool call, and whose child_session_id is the subagent’s session:
  • result.args.name is the task the agent gave the subagent; gummieId is the agent that ran it.
  • result.result.status is completed, error, timeout or aborted. For a subagent the parent waited on, result.result.response is the subagent’s final answer.
  • is_background: true means the parent did not wait. Its launch part completes as soon as the subagent is dispatched, with response: null; the subagent’s answer arrives later as a tool_invocation part named subagent_result with the same child_session_id, placed where the parent received it. A tool_invocation part named subagent_message is a note a subagent sent the parent mid-run.
Group every part with the same parentToolCallId under its tool call, and every subagent_result or subagent_message with the same child_session_id under its launch. timestamp and completedAt order them.

​
Open a subagent’s session

Pass child_session_id to Retrieve session. The child comes back in the same shape as any session, with type: "subagent" and parent_session_id pointing back at the parent. If the subagent delegated further, its own transcript carries subagent_invocation parts of its own.

​
List a session’s subagents

Subagent sessions are hidden from the unfiltered List sessions response. Pass the parent’s ID as parent_session_id to list them, with their state and usage:

​
Live events

When you stream a session, the parent’s event stream reports each subagent as it starts and finishes. subagent-started carries interactionId (the child session), name, gummieId, parentToolCallId, is_background and mode; subagent-completed carries interactionId, status, result and error, plus completedAt and durationMs. The subagent’s own text does not stream on the parent; open the child session for it.