What is a subagent?

One run delegates another bounded run

The orchestrator receives a goal and decides that part of the work can be isolated. It creates a subtask with explicit inputs and a return contract. The subagent gets its own model calls and loop, may use a restricted tool set, and returns findings or artifacts. The orchestrator checks them and decides what happens next.

flowchart TB
  G[User goal] --> O[Orchestrator]
  O -->|bounded task A| A[Subagent run]
  O -->|bounded task B| B[Subagent run]
  A -->|evidence + artifact IDs| V[Verification and merge]
  B -->|evidence + artifact IDs| V
  V --> O
  O --> R[Final result]

This is still ordinary application orchestration. A “manager” may use a model to choose tasks, but the harness owns run creation, identity, context, permissions, deadlines, cancellation, shared state, and effect ordering.

Delegation needs a contract

A useful subtask declares:

• the exact question or deliverable and what is outside scope;
• relevant evidence, source freshness, and repository or environment snapshot;
• available tools and the authority attached to them;
• permitted files, resources, and external effects;
• token, turn, time, and cost budgets;
• dependencies on other work and whether concurrent execution is safe;
• the output schema, artifact location, evidence, and terminal states.

“Research this” or “review the code” leaves too much implicit. “List three primary sources that support or contradict this claim, with URL, date, and one-sentence relevance; do not edit files” is inspectable.

Subagents are especially useful when independent directions can run concurrently, a task benefits from a clean focused context, or a specialist tool surface would otherwise overload one agent. A deterministic function, search query, or ordinary job queue is usually better when the work does not require adaptive model decisions.

Shared effects require serialization

Parallel reading is easier than parallel writing. Two coding subagents can edit the same file, run migrations against shared state, consume one-time credentials, or make decisions from different repository revisions. Give each worker an isolated workspace or immutable snapshot. Merge through one owner that can detect conflicts and rerun validation against the combined result.

Artifacts should outlive chat summaries. Store reports, patches, test output, source records, and trace IDs in durable locations and return references. The orchestrator should not accept “done” as completion evidence when it can inspect the actual state.

Cancellation must propagate. If the parent run stops, workers should stop acquiring new work and their in-flight effects should be reconciled. A worker timeout is not proof that its external operation did not happen.

More agents do not imply better work

A subagent is not automatically a different model, expertise, identity, or security principal. A role prompt saying “you are the security expert” does not create verified competence. Several agents agreeing is not independent evidence when they share the same model, prompt assumptions, or source error.

Multi-agent architecture is not inherently better than one agent. It often consumes more tokens, increases latency, duplicates search, expands tool authority, and creates new failure modes in routing, handoff, merging, and cancellation. Parallelism helps only when the tasks are sufficiently independent and the merge contract is sound.

Evaluate decomposition and merge quality

Start with the same task solved by a single-agent baseline. Compare final correctness, severe failures, wall time, total tokens, tool calls, and cost across repeated trials. A multi-agent design should justify its coordination overhead with a measured improvement on the intended tasks.

Test the orchestrator with scripted workers. Return success, partial result, refusal, malformed output, timeout, duplicate response, stale artifact, contradictory findings, and a result from the wrong task ID. Assert budget accounting, cancellation propagation, retry limits, evidence validation, and deterministic terminal states.

For parallel workers, force overlapping edits, dependency inversion, reordered completion, parent cancellation, and one worker acting on an outdated snapshot. Prove tenant and permission isolation between workers. Include hostile content in one worker's sources and ensure it cannot rewrite parent policy or another worker's authority.

Finally, grade the merged state rather than the number of worker messages. Preserve the task graph, version manifest, worker traces, artifact hashes, conflicts, decisions, and final verification so a failure can be reproduced without reconstructing an informal conversation.