HQAI Engineering HQ
Search
Checking sign-in...

Subagents

Concept9 min readadvanced

What you’ll understand

  • Explain how a parent agent delegates bounded work to subagents
  • Identify when parallel or specialized agents improve a workflow
  • Design context, permissions, coordination, and evaluation for multi-agent tasks

Helpful first: Agents · Harness Engineering · Context engineering

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.

A parent agent delegates independent work and merges evidence A user goal enters a parent agent on the left. The parent decomposes it and sets task, context, tool, and stop boundaries. Three independent subagents then work in parallel: one traces authentication with read-only code access, one runs tests with command tools, and one researches a dependency with web access but no writes. Their evidence converges on the parent, which verifies claims and resolves conflicts before producing an integrated result. A note explains that dependent work waits instead of joining the parallel fan-out. Parent agent owns the user goal and final outcome Decompose work bounded task relevant context limited tools clear stop condition Subagent A trace authentication read-only code Subagent B run test suite command tools Subagent C research dependency web, no writes Parent merges check evidence resolve conflicts integrated result Dependent work waits for prerequisite evidence instead of joining the parallel fan-out. Parallelize independent work; serialize tasks that depend on changing shared state.
The parent remains responsible for decomposition and integration, while each subagent gets only the context and authority needed for one bounded task.

The parent and child roles

The parent is responsible for the overall outcome. It should:

  1. Break the goal into tasks with clear boundaries.
  2. Decide which tasks can run independently.
  3. Give each subagent the minimum context and permissions it needs.
  4. Track status, dependencies, and failures.
  5. Review and combine returned results.
  6. 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.

Saved in this browser only. Not synced to your account.