A subagent is an agent started by another agent or coordinating application to complete a bounded part of a larger task. The original agent is often called the parent, coordinator, or orchestrator.
For example, a coding agent might delegate three independent jobs:
- Inspect the authentication flow.
- Run and summarize the test suite.
- Research the behavior of a dependency.
Each subagent works with its own context and returns a result. The parent combines those results into the final decision or implementation.
Subagents are not automatically better than one capable agent. They add concurrency and specialization, but also add coordination cost, duplicated work, and new failure modes.
The parent and child roles
The parent is responsible for the overall outcome. It should:
- Break the goal into tasks with clear boundaries.
- Decide which tasks can run independently.
- Give each subagent the minimum context and permissions it needs.
- Track status, dependencies, and failures.
- Review and combine returned results.
- Resolve conflicts or ask the user when a real decision remains.
A subagent should receive a bounded objective and a clear stopping point. “Review the entire system and improve anything” is difficult to coordinate. “Trace how password reset tokens are created and report security-relevant findings with file references” is much clearer.
When subagents help
Subagents are useful when work can be divided into separate, meaningful units.
Good candidates include:
- Independent research questions.
- Changes in separate repositories or services.
- Slow tests or builds that can run while other work continues.
- Specialized review, such as security or accessibility.
- Large batches where each item has the same clear output shape.
- Alternative approaches that should not affect each other’s state.
Parallel work helps only when tasks are truly independent. If task B depends on the answer from task A, running both at once creates guesses and rework.
Context isolation
Each subagent has a limited context window. The parent should not copy its entire history into every child. Instead, provide:
- The exact task.
- Confirmed requirements.
- Relevant files, identifiers, or data.
- Constraints and permissions.
- The expected result format.
- A clear instruction about when to stop.
This is a context engineering problem. Too little context causes incorrect assumptions. Too much context hides the objective and wastes tokens.
Isolation can also be valuable. A research subagent can explore one hypothesis without filling the parent’s context with every intermediate source and dead end.
Shared state and write conflicts
Multiple agents can interfere with each other when they edit the same files, update the same record, or act on the same external system.
Common controls include:
- Give each subagent a separate worktree, branch, or resource scope.
- Assign clear file ownership.
- Use read-only subagents for investigation.
- Record dependencies before work starts.
- Serialize tasks that modify the same state.
- Require the parent to review changes before integration.
A shared checkout with several writing agents is risky. One agent may overwrite another agent’s work or validate against an intermediate state.
Specialization
A subagent can use a different instruction set, tool set, or model suited to its task. For example:
- A security reviewer receives read-only code access and a vulnerability-report format.
- A test runner can execute verbose commands and return only failures.
- A research agent can use web sources but cannot edit the repository.
- An implementation agent can change one service but not deploy it.
Specialization should reduce ambiguity and authority. It should not be used to bypass controls that apply to the parent.
Coordination and result merging
The parent needs a predictable way to understand each result. Useful return fields include:
status: complete | blocked | failed
summary: short result
evidence: files, commands, sources, or measurements
changes: what was modified
risks: unresolved concerns
next_action: only if another step is required
The parent should verify high-impact claims. Agreement between two agents is not proof if both agents used the same incorrect assumption.
Conflicting results should be resolved against evidence: tests, source code, logs, or trusted documentation.
Failure modes
Multi-agent workflows commonly fail through:
- Duplicated work: two agents investigate the same question.
- Missing dependency: a child starts before required information exists.
- Context drift: the parent changes direction but a child continues with old requirements.
- Write conflict: children modify overlapping state.
- Authority expansion: a child receives broader tools than its task needs.
- Result overload: the parent receives more detail than it can evaluate.
- Recursive delegation: agents keep creating more agents without reducing the problem.
The harness should limit concurrency, total agents, time, cost, and delegation depth.
Safety and permissions
Subagents inherit risk from their tools. Give each child least-privilege access.
A read-only analysis task should not receive write tools. An agent that prepares a message should not be able to send it unless the user has approved that action. Sensitive data should be passed only when the task requires it.
Treat subagent results as untrusted input. A result may contain a mistaken command, a malicious instruction copied from a document, or a claim without evidence. The parent should not execute embedded instructions merely because they came from another agent.
Evaluating a multi-agent workflow
Compare the workflow with a strong single-agent baseline. Measure:
- End-to-end task success.
- Wall-clock time.
- Total model and tool cost.
- Duplicate work.
- Number of conflicts or retries.
- Parent review time.
- Unsafe or unauthorized action attempts.
- Quality of evidence in the final result.
Parallelism may reduce elapsed time while increasing total cost. Specialization may improve quality for one task and add overhead for another. Use subagents when the measured benefit justifies the coordination system.
The key idea
Subagents are isolated workers for bounded parts of a larger goal. The parent remains responsible for decomposition, permissions, shared state, evidence, and integration. Good multi-agent systems reduce a problem into independent work; bad ones multiply ambiguity.