diff --git a/docs/tools/subagents.md b/docs/tools/subagents.md index d1696f8d43..6712e2b623 100644 --- a/docs/tools/subagents.md +++ b/docs/tools/subagents.md @@ -6,146 +6,465 @@ read_when: title: "Sub-Agents" --- -# Sub-agents +# Sub-Agents -Sub-agents are background agent runs spawned from an existing agent run. They run in their own session (`agent::subagent:`) and, when finished, **announce** their result back to the requester chat channel. +Sub-agents let you run background tasks without blocking the main conversation. When you spawn a sub-agent, it runs in its own isolated session, does its work, and announces the result back to the chat when finished. -## Slash command +**Use cases:** -Use `/subagents` to inspect or control sub-agent runs for the **current session**: +- Research a topic while the main agent continues answering questions +- Run multiple long tasks in parallel (web scraping, code analysis, file processing) +- Delegate tasks to specialized agents in a multi-agent setup -- `/subagents list` -- `/subagents stop ` -- `/subagents log [limit] [tools]` -- `/subagents info ` -- `/subagents send ` +## Quick Start -`/subagents info` shows run metadata (status, timestamps, session id, transcript path, cleanup). +The simplest way to use sub-agents is to ask your agent naturally: -Primary goals: +> "Spawn a sub-agent to research the latest Node.js release notes" -- Parallelize “research / long task / slow tool” work without blocking the main run. -- Keep sub-agents isolated by default (session separation + optional sandboxing). -- Keep the tool surface hard to misuse: sub-agents do **not** get session tools by default. -- Avoid nested fan-out: sub-agents cannot spawn sub-agents. +The agent will call the `sessions_spawn` tool behind the scenes. When the sub-agent finishes, it announces its findings back into your chat. -Cost note: each sub-agent has its **own** context and token usage. For heavy or repetitive -tasks, set a cheaper model for sub-agents and keep your main agent on a higher-quality model. -You can configure this via `agents.defaults.subagents.model` or per-agent overrides. +You can also be explicit about options: -## Tool +> "Spawn a sub-agent to analyze the server logs from today. Use gpt-5.2 and set a 5-minute timeout." -Use `sessions_spawn`: +## How It Works -- Starts a sub-agent run (`deliver: false`, global lane: `subagent`) -- Then runs an announce step and posts the announce reply to the requester chat channel -- Default model: inherits the caller unless you set `agents.defaults.subagents.model` (or per-agent `agents.list[].subagents.model`); an explicit `sessions_spawn.model` still wins. -- Default thinking: inherits the caller unless you set `agents.defaults.subagents.thinking` (or per-agent `agents.list[].subagents.thinking`); an explicit `sessions_spawn.thinking` still wins. + + + The main agent calls `sessions_spawn` with a task description. The call is **non-blocking** — the main agent gets back `{ status: "accepted", runId, childSessionKey }` immediately. + + + A new isolated session is created (`agent::subagent:`) on the dedicated `subagent` queue lane. + + + When the sub-agent finishes, it announces its findings back to the requester chat. The main agent posts a natural-language summary. + + + The sub-agent session is auto-archived after 60 minutes (configurable). Transcripts are preserved. + + -Tool params: + +Each sub-agent has its **own** context and token usage. Set a cheaper model for sub-agents to save costs — see [Setting a Default Model](#setting-a-default-model) below. + -- `task` (required) -- `label?` (optional) -- `agentId?` (optional; spawn under another agent id if allowed) -- `model?` (optional; overrides the sub-agent model; invalid values are skipped and the sub-agent runs on the default model with a warning in the tool result) -- `thinking?` (optional; overrides thinking level for the sub-agent run) -- `runTimeoutSeconds?` (default `0`; when set, the sub-agent run is aborted after N seconds) -- `cleanup?` (`delete|keep`, default `keep`) +## Configuration -Allowlist: +Sub-agents work out of the box with no configuration. Defaults: -- `agents.list[].subagents.allowAgents`: list of agent ids that can be targeted via `agentId` (`["*"]` to allow any). Default: only the requester agent. +- Model: target agent’s normal model selection (unless `subagents.model` is set) +- Thinking: no sub-agent override (unless `subagents.thinking` is set) +- Max concurrent: 8 +- Auto-archive: after 60 minutes -Discovery: +### Setting a Default Model -- Use `agents_list` to see which agent ids are currently allowed for `sessions_spawn`. - -Auto-archive: - -- Sub-agent sessions are automatically archived after `agents.defaults.subagents.archiveAfterMinutes` (default: 60). -- Archive uses `sessions.delete` and renames the transcript to `*.deleted.` (same folder). -- `cleanup: "delete"` archives immediately after announce (still keeps the transcript via rename). -- Auto-archive is best-effort; pending timers are lost if the gateway restarts. -- `runTimeoutSeconds` does **not** auto-archive; it only stops the run. The session remains until auto-archive. - -## Authentication - -Sub-agent auth is resolved by **agent id**, not by session type: - -- The sub-agent session key is `agent::subagent:`. -- The auth store is loaded from that agent’s `agentDir`. -- The main agent’s auth profiles are merged in as a **fallback**; agent profiles override main profiles on conflicts. - -Note: the merge is additive, so main profiles are always available as fallbacks. Fully isolated auth per agent is not supported yet. - -## Announce - -Sub-agents report back via an announce step: - -- The announce step runs inside the sub-agent session (not the requester session). -- If the sub-agent replies exactly `ANNOUNCE_SKIP`, nothing is posted. -- Otherwise the announce reply is posted to the requester chat channel via a follow-up `agent` call (`deliver=true`). -- Announce replies preserve thread/topic routing when available (Slack threads, Telegram topics, Matrix threads). -- Announce messages are normalized to a stable template: - - `Status:` derived from the run outcome (`success`, `error`, `timeout`, or `unknown`). - - `Result:` the summary content from the announce step (or `(not available)` if missing). - - `Notes:` error details and other useful context. -- `Status` is not inferred from model output; it comes from runtime outcome signals. - -Announce payloads include a stats line at the end (even when wrapped): - -- Runtime (e.g., `runtime 5m12s`) -- Token usage (input/output/total) -- Estimated cost when model pricing is configured (`models.providers.*.models[].cost`) -- `sessionKey`, `sessionId`, and transcript path (so the main agent can fetch history via `sessions_history` or inspect the file on disk) - -## Tool Policy (sub-agent tools) - -By default, sub-agents get **all tools except session tools**: - -- `sessions_list` -- `sessions_history` -- `sessions_send` -- `sessions_spawn` - -Override via config: +Use a cheaper model for sub-agents to save on token costs: ```json5 { agents: { defaults: { subagents: { - maxConcurrent: 1, - }, - }, - }, - tools: { - subagents: { - tools: { - // deny wins - deny: ["gateway", "cron"], - // if allow is set, it becomes allow-only (deny still wins) - // allow: ["read", "exec", "process"] + model: "minimax/MiniMax-M2.1", }, }, }, } ``` -## Concurrency +### Setting a Default Thinking Level -Sub-agents use a dedicated in-process queue lane: +```json5 +{ + agents: { + defaults: { + subagents: { + thinking: "low", + }, + }, + }, +} +``` -- Lane name: `subagent` -- Concurrency: `agents.defaults.subagents.maxConcurrent` (default `8`) +### Per-Agent Overrides -## Stopping +In a multi-agent setup, you can set sub-agent defaults per agent: -- Sending `/stop` in the requester chat aborts the requester session and stops any active sub-agent runs spawned from it. +```json5 +{ + agents: { + list: [ + { + id: "researcher", + subagents: { + model: "anthropic/claude-sonnet-4", + }, + }, + { + id: "assistant", + subagents: { + model: "minimax/MiniMax-M2.1", + }, + }, + ], + }, +} +``` + +### Concurrency + +Control how many sub-agents can run at the same time: + +```json5 +{ + agents: { + defaults: { + subagents: { + maxConcurrent: 4, // default: 8 + }, + }, + }, +} +``` + +Sub-agents use a dedicated queue lane (`subagent`) separate from the main agent queue, so sub-agent runs don't block inbound replies. + +### Auto-Archive + +Sub-agent sessions are automatically archived after a configurable period: + +```json5 +{ + agents: { + defaults: { + subagents: { + archiveAfterMinutes: 120, // default: 60 + }, + }, + }, +} +``` + + +Archive renames the transcript to `*.deleted.` (same folder) — transcripts are preserved, not deleted. Auto-archive timers are best-effort; pending timers are lost if the gateway restarts. + + +## The `sessions_spawn` Tool + +This is the tool the agent calls to create sub-agents. + +### Parameters + +| Parameter | Type | Default | Description | +| ------------------- | ---------------------- | ------------------ | -------------------------------------------------------------- | +| `task` | string | _(required)_ | What the sub-agent should do | +| `label` | string | — | Short label for identification | +| `agentId` | string | _(caller's agent)_ | Spawn under a different agent id (must be allowed) | +| `model` | string | _(optional)_ | Override the model for this sub-agent | +| `thinking` | string | _(optional)_ | Override thinking level (`off`, `low`, `medium`, `high`, etc.) | +| `runTimeoutSeconds` | number | `0` (no limit) | Abort the sub-agent after N seconds | +| `cleanup` | `"delete"` \| `"keep"` | `"keep"` | `"delete"` archives immediately after announce | + +### Model Resolution Order + +The sub-agent model is resolved in this order (first match wins): + +1. Explicit `model` parameter in the `sessions_spawn` call +2. Per-agent config: `agents.list[].subagents.model` +3. Global default: `agents.defaults.subagents.model` +4. Target agent’s normal model resolution for that new session + +Thinking level is resolved in this order: + +1. Explicit `thinking` parameter in the `sessions_spawn` call +2. Per-agent config: `agents.list[].subagents.thinking` +3. Global default: `agents.defaults.subagents.thinking` +4. Otherwise no sub-agent-specific thinking override is applied + + +Invalid model values are silently skipped — the sub-agent runs on the next valid default with a warning in the tool result. + + +### Cross-Agent Spawning + +By default, sub-agents can only spawn under their own agent id. To allow an agent to spawn sub-agents under other agent ids: + +```json5 +{ + agents: { + list: [ + { + id: "orchestrator", + subagents: { + allowAgents: ["researcher", "coder"], // or ["*"] to allow any + }, + }, + ], + }, +} +``` + + +Use the `agents_list` tool to discover which agent ids are currently allowed for `sessions_spawn`. + + +## Managing Sub-Agents (`/subagents`) + +Use the `/subagents` slash command to inspect and control sub-agent runs for the current session: + +| Command | Description | +| ---------------------------------------- | ---------------------------------------------- | +| `/subagents list` | List all sub-agent runs (active and completed) | +| `/subagents stop ` | Stop a running sub-agent | +| `/subagents log [limit] [tools]` | View sub-agent transcript | +| `/subagents info ` | Show detailed run metadata | +| `/subagents send ` | Send a message to a running sub-agent | + +You can reference sub-agents by list index (`1`, `2`), run id prefix, full session key, or `last`. + + + + ``` + /subagents list + ``` + + ``` + 🧭 Subagents (current session) + Active: 1 · Done: 2 + 1) ✅ · research logs · 2m31s · run a1b2c3d4 · agent:main:subagent:... + 2) ✅ · check deps · 45s · run e5f6g7h8 · agent:main:subagent:... + 3) 🔄 · deploy staging · 1m12s · run i9j0k1l2 · agent:main:subagent:... + ``` + + ``` + /subagents stop 3 + ``` + + ``` + ⚙️ Stop requested for deploy staging. + ``` + + + + ``` + /subagents info 1 + ``` + + ``` + ℹ️ Subagent info + Status: ✅ + Label: research logs + Task: Research the latest server error logs and summarize findings + Run: a1b2c3d4-... + Session: agent:main:subagent:... + Runtime: 2m31s + Cleanup: keep + Outcome: ok + ``` + + + + ``` + /subagents log 1 10 + ``` + + Shows the last 10 messages from the sub-agent's transcript. Add `tools` to include tool call messages: + + ``` + /subagents log 1 10 tools + ``` + + + + ``` + /subagents send 3 "Also check the staging environment" + ``` + + Sends a message into the running sub-agent's session and waits up to 30 seconds for a reply. + + + + +## Announce (How Results Come Back) + +When a sub-agent finishes, it goes through an **announce** step: + +1. The sub-agent's final reply is captured +2. A summary message is sent to the main agent's session with the result, status, and stats +3. The main agent posts a natural-language summary to your chat + +Announce replies preserve thread/topic routing when available (Slack threads, Telegram topics, Matrix threads). + +### Announce Stats + +Each announce includes a stats line with: + +- Runtime duration +- Token usage (input/output/total) +- Estimated cost (when model pricing is configured via `models.providers.*.models[].cost`) +- Session key, session id, and transcript path + +### Announce Status + +The announce message includes a status derived from the runtime outcome (not from model output): + +- **successful completion** (`ok`) — task completed normally +- **error** — task failed (error details in notes) +- **timeout** — task exceeded `runTimeoutSeconds` +- **unknown** — status could not be determined + + +If no user-facing announcement is needed, the main-agent summarize step can return `NO_REPLY` and nothing is posted. +This is different from `ANNOUNCE_SKIP`, which is used in agent-to-agent announce flow (`sessions_send`). + + +## Tool Policy + +By default, sub-agents get **all tools except** a set of denied tools that are unsafe or unnecessary for background tasks: + + + + | Denied tool | Reason | + |-------------|--------| + | `sessions_list` | Session management — main agent orchestrates | + | `sessions_history` | Session management — main agent orchestrates | + | `sessions_send` | Session management — main agent orchestrates | + | `sessions_spawn` | No nested fan-out (sub-agents cannot spawn sub-agents) | + | `gateway` | System admin — dangerous from sub-agent | + | `agents_list` | System admin | + | `whatsapp_login` | Interactive setup — not a task | + | `session_status` | Status/scheduling — main agent coordinates | + | `cron` | Status/scheduling — main agent coordinates | + | `memory_search` | Pass relevant info in spawn prompt instead | + | `memory_get` | Pass relevant info in spawn prompt instead | + + + +### Customizing Sub-Agent Tools + +You can further restrict sub-agent tools: + +```json5 +{ + tools: { + subagents: { + tools: { + // deny always wins over allow + deny: ["browser", "firecrawl"], + }, + }, + }, +} +``` + +To restrict sub-agents to **only** specific tools: + +```json5 +{ + tools: { + subagents: { + tools: { + allow: ["read", "exec", "process", "write", "edit", "apply_patch"], + // deny still wins if set + }, + }, + }, +} +``` + + +Custom deny entries are **added to** the default deny list. If `allow` is set, only those tools are available (the default deny list still applies on top). + + +## Authentication + +Sub-agent auth is resolved by **agent id**, not by session type: + +- The auth store is loaded from the target agent's `agentDir` +- The main agent's auth profiles are merged in as a **fallback** (agent profiles win on conflicts) +- The merge is additive — main profiles are always available as fallbacks + + +Fully isolated auth per sub-agent is not currently supported. + + +## Context and System Prompt + +Sub-agents receive a reduced system prompt compared to the main agent: + +- **Included:** Tooling, Workspace, Runtime sections, plus `AGENTS.md` and `TOOLS.md` +- **Not included:** `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` + +The sub-agent also receives a task-focused system prompt that instructs it to stay focused on the assigned task, complete it, and not act as the main agent. + +## Stopping Sub-Agents + +| Method | Effect | +| ---------------------- | ------------------------------------------------------------------------- | +| `/stop` in the chat | Aborts the main session **and** all active sub-agent runs spawned from it | +| `/subagents stop ` | Stops a specific sub-agent without affecting the main session | +| `runTimeoutSeconds` | Automatically aborts the sub-agent run after the specified time | + + +`runTimeoutSeconds` does **not** auto-archive the session. The session remains until the normal archive timer fires. + + +## Full Configuration Example + + +```json5 +{ + agents: { + defaults: { + model: { primary: "anthropic/claude-sonnet-4" }, + subagents: { + model: "minimax/MiniMax-M2.1", + thinking: "low", + maxConcurrent: 4, + archiveAfterMinutes: 30, + }, + }, + list: [ + { + id: "main", + default: true, + name: "Personal Assistant", + }, + { + id: "ops", + name: "Ops Agent", + subagents: { + model: "anthropic/claude-sonnet-4", + allowAgents: ["main"], // ops can spawn sub-agents under "main" + }, + }, + ], + }, + tools: { + subagents: { + tools: { + deny: ["browser"], // sub-agents can't use the browser + }, + }, + }, +} +``` + ## Limitations -- Sub-agent announce is **best-effort**. If the gateway restarts, pending “announce back” work is lost. -- Sub-agents still share the same gateway process resources; treat `maxConcurrent` as a safety valve. -- `sessions_spawn` is always non-blocking: it returns `{ status: "accepted", runId, childSessionKey }` immediately. -- Sub-agent context only injects `AGENTS.md` + `TOOLS.md` (no `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, or `BOOTSTRAP.md`). + +- **Best-effort announce:** If the gateway restarts, pending announce work is lost. +- **No nested spawning:** Sub-agents cannot spawn their own sub-agents. +- **Shared resources:** Sub-agents share the gateway process; use `maxConcurrent` as a safety valve. +- **Auto-archive is best-effort:** Pending archive timers are lost on gateway restart. + + +## See Also + +- [Session Tools](/concepts/session-tool) — details on `sessions_spawn` and other session tools +- [Multi-Agent Sandbox and Tools](/tools/multi-agent-sandbox-tools) — per-agent tool restrictions and sandboxing +- [Configuration](/gateway/configuration) — `agents.defaults.subagents` reference +- [Queue](/concepts/queue) — how the `subagent` lane works