Subagent / delegated agent

Why you'd careThe problem it solves

The design that keeps getting drawn is “a skill for the reviewer, a skill for the researcher, a skill for the writer”. It never works the way the diagram implies, because all three skills load into the same conversation. The reviewer's instructions are still sitting there while the writer works, the researcher's forty tool results are still in the transcript, and by the third handoff the model is reasoning over a context that contains three jobs and the debris of two of them. What the diagram actually wanted was three context windows. That is a subagent: a fresh model instance with its own history, given a scoped task and reporting back a summary. The distinction is not stylistic. A skill changes what is in this conversation; a subagent starts another one.

ConceptWhat it is

A subagent is a separate model instance, spawned by a coordinating agent, with its own context window, its own system prompt, its own tool set, and its own transcript. It receives a task description, works, and returns a result — typically a summary rather than its full trace. The coordinator's context grows by the summary, not by everything the subagent read.

It is not an API primitive. There is no subagent parameter on the Messages API; if you are calling that endpoint directly and want fan-out, you write it — more requests, your own coordination. Delegation exists at the harness level, in three concrete places: Claude Code's built-in delegation, the Claude Agent SDK's subagents, and Managed Agents, where a coordinator declares a roster of agents it may delegate to in a top-level multiagent field on the Agent object.

The moving parts worth naming: the roster (which agents may be delegated to, and at what version), the thread (each subagent's own event stream and history), the shared surface (in Managed Agents, threads share the session's container filesystem but not conversation state), and the return channel (a message back to the coordinator, which is the only thing that lands in the coordinator's context).

Against neighbours: a skill adds instructions here; a tool adds capability here; a subagent adds an elsewhere. If your complaint is “the model does not know the review standard”, that is a skill. If it is “this conversation is too crowded to think in”, that is a subagent.

How it worksThe mechanics

On Managed Agents the roster is declared on the coordinator's Agent object, not on the session and not as a tool entry:

multiagent = {
  "type": "coordinator",
  "agents": [
    "agent_abc123",                                 # latest version
    {"type": "agent", "id": "agent_def456", "version": 4},
    {"type": "self"}                                # copies of the coordinator
  ]
}

One to twenty roster entries; the coordinator may spawn multiple copies of each, up to 25 concurrent threads. Delegation is one level deep and that is enforced, not silently flattened — rostering an agent that itself carries a roster fails the create or update with a validation error.

Each spawned agent gets a thread with its own event stream, addressable through per-thread list and stream endpoints. The session-level stream shows a condensed view: thread created, thread status transitions, and the cross-thread messages, rather than every subagent tool call. Two details bite people. First, message direction is relative to the thread whose stream you are reading — the same delegated task appears as a message sent on the coordinator's stream and a message received on the child's, so reading “received” as “a subagent finished” is wrong once you are watching a child. Second, when a subagent needs your client — a tool confirmation, a custom tool result — the request is cross-posted to the primary thread carrying the originating thread's id, so you only have to watch one stream.

Delegation propensity does not drift across model versions; it flips. Opus 4.6 over-spawned and needed reining in. Opus 4.7 spawned fewer. Opus 4.8 under-delegated to the point that the documented remedy was explicit guidance telling it when fanning out is worth the overhead. Claude Opus 5 reverses that again — it reaches for subagents readily, and the documented remedy is an explicit cap plus removing the “delegate more” guidance written for 4.8. Carrying a prompt forward across an upgrade therefore inverts your intent rather than merely weakening it. Re-read your delegation instructions on every model change.

At a glanceSee it

Delegation is for a separate context window; instructions in the same window are a skill.

Where it runsSurfaces and availability

Delegation is the least portable construct in this family, and the reason is structural: it lives in the harness, and the harness is what changes when you change platforms. If you build on Managed Agents you get rosters, threads and cross-posted confirmations for free and cannot take them to Bedrock. If you build on the raw Messages API you own the fan-out and it runs anywhere. That is a genuine architectural fork, and the honest framing is that you are choosing who writes the coordinator, not whether one exists.

ExampleIn the real world

A platform team is migrating 180 services off a deprecated auth library. A coordinator agent is configured with a roster of two: a migrator and a reviewer, both pinned to specific versions so a mid-run prompt tweak cannot change behaviour halfway through.

The coordinator reads the service inventory and delegates in batches. Each migrator thread gets one service: its own context, the repository mounted in the shared container, and a task description that includes everything it needs, because it cannot see the coordinator's conversation. It edits, runs the tests, and reports back four lines — what changed, what passed, what it could not resolve. Those four lines are what enters the coordinator's context, not the two hundred tool calls behind them.

The reviewer threads read diffs and flag anything touching token refresh. When one hits a bash command the permission policy gates, the confirmation request is cross-posted to the primary stream carrying that thread's id; the operator approves once and the child resumes.

The coordinator finishes 180 services with a context containing 180 summaries. Run the same job inline and it exhausts its window somewhere around service nine, having spent most of it on test output nobody will read again.

Not thisWhat it is often confused with

• Not a skilla skill loads instructions into the conversation you are already in. A subagent starts a new one. Reaching for “a skill per role” when the real problem is context pressure is the single most common misdiagnosis here.
• Not a tooleven where a harness exposes delegation through something tool-shaped, what you get back is a model's summary of work it did in its own window, not a deterministic function result. Do not treat it as one.
• Not parallel tool callsseveral tool_use blocks in one response run concurrently and every result lands in the same context. That is concurrency without isolation, which is often exactly what you want and is much cheaper.
• Not model routingputting a cheaper model on a sub-task is a real reason to spawn a subagent, since switching models mid-conversation invalidates the cache. But routing is the motive, not the mechanism.
• Not a hierarchyon Managed Agents delegation is one level deep and the platform rejects a nested roster outright. Designs that assume a tree of managers will fail at configuration time, not at runtime.

LimitsWhen not to reach for it

• The sub-task is a handful of tool calls.A file read, a grep, a small edit. Delegation costs a fresh context that must be re-established from nothing, plus a report the coordinator then re-reads. Do it inline.
• The work needs the conversation's state.Threads share a filesystem, not history. If the sub-task depends on something discussed three turns ago, either say it in the delegated message or keep the work where the context is.
• You only want different instructions.A reviewer persona, a stricter output format, a domain procedure. That is a skill, and it costs nothing beyond its description.
• You are delegating verification.On Claude Opus 5 this is actively counterproductive — it verifies its own work by default, and adding a verifier subagent produces over-verification. Keep checking in the main loop.
• You carried the delegation prompt across a model upgrade.The guidance that made Opus 4.8 delegate enough will make Claude Opus 5 delegate far too much. Re-tune before you scale the run out, not after the bill arrives.

RelatedGo deeper