> ## Documentation Index
> Fetch the complete documentation index at: https://85be67f-opencomputer.manicule.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For every page in one file, fetch https://85be67f-opencomputer.manicule.dev/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://85be67f-opencomputer.manicule.dev/api/mcp.
> Every agent surface: https://85be67f-opencomputer.manicule.dev/.well-known/llms-manifest.json

# Subagents (/api/subagents)

<!-- agent-signals: reading_time_min: 2 · est_tokens: 859 · updated: 2026-11-13 -->
Related: [Overview](/api/overview.md), [Sessions](/api/sessions.md), [Turns](/api/turns.md), [Events](/api/events.md), [Asks](/api/asks.md), [Terminals](/api/terminals.md)

> A subagent is an agent the session's harness launches for part of a task; one with `background: true` can outlive its turn

<Note>Not in the public code yet: launch blocker 4 (API on a self-hosted instance). See [API overview](/api/overview).</Note>

The Slack side is in [Subagents](/slack/subagents). A subagent's id is `sa_` followed by 12 characters. Fields of the `Subagent` object: [API schema](/reference/api-schema#objects).

## Events

| Source                                                                | What it gives                                                                              |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `subagent.started`, `subagent.ended`                                  | The whole object. In events and lists a long `result` is cut and `resultTruncated` is true |
| `tool.started`, `tool.completed`, `tool.failed` with `subagentId` set | Tool calls made inside the subagent                                                        |
| `subagent.progress` [deltas](/api/events#deltas)                      | `activity`, `toolCalls` and `tokens`, on a WebSocket attached with `deltas: true`          |
| `Session` object                                                      | Running subagents in its `subagents` list                                                  |

A subagent with `background: true` can outlive the turn that launched it. When it ends after its turn did, the harness starts a new turn for the result, with `trigger: "subagent"`, the `subagentId`, and no `author`.

## List and read

| Method                                                        | Returns                                                                                                                                |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `subagents.list` (`GET /sessions/{id}/subagents`)             | Running subagents, newest first. `status=all` includes ended ones. `limit` is 1 to 100, default 20; pass `nextCursor` back as `cursor` |
| `subagents.get` (`GET /sessions/{id}/subagents/{subagentId}`) | One subagent with its whole `result`                                                                                                   |

## Stop

`subagents.stop` (`POST /sessions/{id}/subagents/{subagentId}/stop`) stops a running subagent, as the Stop button on the Slack agents panel does. Suspending a session also stops its running subagents.

```json
{"jsonrpc":"2.0","id":6,"method":"subagents.stop","params":{"sessionId":"cs_0123456789abcdef","subagentId":"sa_0123456789ab"}}
```

The result is the subagent and a `seq`. A `subagent.ended` event follows with `status: "stopped"` and `stoppedBy`.

| Error                | Cause                                                                                                                             |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `409 subagent_ended` | The subagent has already ended. The error carries the subagent. A repeat by the actor who stopped it returns the subagent instead |