# Sub-agents

Let a managed agent delegate work to specialist sub-agents that spend its budget and inherit its limits, or run under tighter limits of their own.

A managed agent can hand part of a task to a **sub-agent**: a new one defined on the parent, or an existing agent picked from the registry. The parent's model sees each sub-agent's description and decides when to call it.

## Prerequisites

- A managed agent (sub-agents are not available on self-managed agents).

## Add a sub-agent

1. Open the parent agent's **Settings** tab and go to the **Tools** section, where its runtime is.
2. Under **Subagents**, type a name (lowercase letters, digits and hyphens) and choose **Add subagent** to define a new one, or pick an agent and choose **Add registered agent** to reuse an existing one.
3. Fill in the fields.

   | Field | Notes |
   | --- | --- |
   | Description | What the parent reads to decide to use it. Be specific about when, not just what. |
   | Instructions | The sub-agent's own brief. New sub-agents only. |
   | Context it is given | **Task only**, **Handoff note** (the parent writes one) or **Last 6 turns of this conversation**. Passed context counts against the budget. |
   | Model override / Provider override | Optional, new sub-agents only. Blank inherits the parent's. Use a cheaper model for narrow tasks. A provider override needs a model. |
   | Its MCP servers | New sub-agents only. Each tool list is held to what the parent itself may use on the same server. |
   | Context budget (`context_budget_tokens`) | Optional, new sub-agents only. The input one of its steps may send, 1,024 to 2,000,000 tokens, held to its own model's window when it runs. Blank uses the parent's budget. |
   | Reply cap (`max_tokens`) | Optional, new sub-agents only. The most tokens one of its replies may have, 1 to 32,000 and never more than its model can generate. Blank uses the reply cap the parent's run has. |
   | Step cap (`max_iterations`) | Optional, new sub-agents only. How many model calls one delegation may make, 1 to 100 and never more than the parent's. Blank uses the parent's. |
   | Run limits (`limits`) | Optional, new sub-agents only. The same keys as the parent's per-run limits (`max_seconds`, `max_tool_calls`, `max_tool_calls_per_step`, `max_identical_tool_calls`, `max_delegations`, `max_tokens_per_run`, `max_cost_usd_per_run`). Each is held to the parent's value for that key. |

4. Choose **Save runtime**, and test from the parent's **Playground**.

> [!NOTE]
> A sub-agent defined on the parent spends the parent's budget and cannot delegate further. A registered agent used as a sub-agent runs as itself, under its own guardrails, kill switch and budget, and its cost is billed on to the parent.

## Each sub-agent's own limits

A sub-agent defined on the parent inherits the parent's context budget, reply cap, step cap and per-run limits unless you set its own. Each of the four fields above is optional and is stored only when set, so a sub-agent saved before the fields existed runs exactly as it did.

- A value wider than the parent's is refused when you save, with a message that names the sub-agent and the field. A sub-agent cannot widen what the parent is held to.
- Its own run limits are nested inside the parent's. What the sub-agent spends still counts toward the parent's totals, so the parent's caps are checked on every call the sub-agent makes. When the sub-agent reaches one of its own limits, only that delegation ends. The parent is told why and carries on. When the parent's limit is reached inside a delegation, the whole run ends, as before.
- Its context budget is held to the window of the model it runs on, which may differ from the parent's when it has a model override.

`GET /api/agents/{key}/runtime` returns an `effective` object with the values a run will actually use, for the parent (`effective.agent`) and for each sub-agent (`effective.subagents.<name>`): `window_tokens` (the model's input window from the catalogue, or null when it is not known), `context_budget_tokens`, `max_tokens`, `max_iterations` and `limits`. These are computed from the saved runtime and the model catalogue and are never stored. A registered agent used as a sub-agent is shown with its own agent's values.

## How delegation is governed

- Each delegation is checked by the Cedar `delegate` action. You can also run one directly with `POST /api/agents/{parent}/delegate/{child}`, under the parent's budget.
- A sub-agent runs as its parent runs (**Run as**), so a per-user MCP server can be ticked for it only when the parent runs as the invoker.
- A delegation that would loop back to an agent already working on the request, or exceed the parent's **Delegation depth** (default 3, at most 5), is refused.
- Cost is billed to the real parent, and every usage row carries the delegation chain, so you can see which parent a sub-agent's spend belongs to.

## Next steps

- [Playground and evals](/docs/agents/playground-evals)
- [Budgets](/docs/ai-gateway/budgets)