> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gumloop.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subagents in a session

> Find the subagents an agent delegated to, open each one's own session, and list a session's children.

When an agent delegates work to a [subagent](https://docs.gumloop.com/core-concepts/agents.md#subagents), 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:

```json theme={"dark"}
{
  "id": "part_3264c4ee25fb43e9bc8498",
  "type": "subagent_invocation",
  "toolName": "subagent_invocation",
  "toolCallState": "completed",
  "parentToolCallId": "toolu_01Rv1S9CiBuUzATKZtxqTiXk",
  "child_session_id": "ALv5GNVFXGLXUCvsg3Uu58",
  "timestamp": "2026-11-05T02:50:45.642897",
  "completedAt": "2026-11-05T02:50:46.657186",
  "result": {
    "args": {
      "childInteractionId": "ALv5GNVFXGLXUCvsg3Uu58",
      "gummieId": "r5kUWM3gMBCSd1N7VzQUjd",
      "gummieType": "custom",
      "name": "Research Canada via Wikipedia",
      "is_background": true
    },
    "result": {
      "status": "completed",
      "gummieName": "Clever Handler",
      "response": null,
      "error": null
    }
  }
}
```

* `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](https://docs.gumloop.com/api-reference/sessions/retrieve-session.md). 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.

```bash theme={"dark"}
curl 'https://api.gumloop.com/api/v1/sessions/ALv5GNVFXGLXUCvsg3Uu58' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

```json theme={"dark"}
{
  "session": {
    "id": "ALv5GNVFXGLXUCvsg3Uu58",
    "agent_id": "r5kUWM3gMBCSd1N7VzQUjd",
    "type": "subagent",
    "parent_session_id": "n5RmBhCzTR5vTYKJ8cSump",
    "messages": [...]
  }
}
```

## List a session's subagents

Subagent sessions are hidden from the unfiltered [List sessions](https://docs.gumloop.com/api-reference/sessions/list-sessions.md) response. Pass the parent's ID as `parent_session_id` to list them, with their `state` and usage:

```bash theme={"dark"}
curl 'https://api.gumloop.com/api/v1/agents/r5kUWM3gMBCSd1N7VzQUjd/sessions?parent_session_id=n5RmBhCzTR5vTYKJ8cSump' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

```python theme={"dark"}
from gumloop import Gumloop

client = Gumloop(access_token="YOUR_ACCESS_TOKEN")

page = client.sessions.list("r5kUWM3gMBCSd1N7VzQUjd", parent_session_id="n5RmBhCzTR5vTYKJ8cSump")
for child in page.sessions:
    print(child.id, child.state, child.parent_session_id)
```

## 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.