Delegate work to another agent

When a piece of work is separable, hand it to another agent and keep going. This guide covers choosing how to invoke that agent, waiting for the result, and handling what comes back.

Delegation has a model behind it: who may act, how far authority reaches, and how results are trusted. See Multi-agent collaboration.

Supervisor/child lifecycle and task-handle contracts are in the Tasks spec.

Invocation Styles

Supervised Child Subagent

Create a private subordinate agent strictly supervised by the current agent:

{
  "target": {
    "kind": "new_subagent",
    "template": "code-reviewer",
    "workspace_mode": "worktree"
  },
  "initial_message": "Review pull request changes in src/runtime/"
}

Peer Invocation

Invoke an existing long-lived agent as an equal peer:

{
  "target": {
    "kind": "existing_agent",
    "agent_id": "auditor"
  },
  "initial_message": "Please audit runtime SQLite database retention rules."
}

Child Agent Token Usage

Task status and output snapshots include a token_usage field with the child agent's cumulative token consumption:

{
  "total": {
    "input_tokens": 12450,
    "output_tokens": 3840,
    "total_tokens": 16290
  },
  "total_model_rounds": 5,
  "last_turn": {
    "input_tokens": 2100,
    "output_tokens": 720,
    "total_tokens": 2820
  }
}

Field	Description
`total`	Cumulative tokens across all child turns
`total_model_rounds`	Number of model round-trips the child has made
`last_turn`	Token usage for the most recent turn (if available)

Use token usage to estimate child agent costs, detect unexpectedly expensive delegations, or decide whether to stop a child that is consuming more tokens than its output warrants.

Usage Patterns

Parallel investigation

Invoke multiple agents to explore different aspects simultaneously:

Parent agent:
  InvokeAgent("Review src/runtime/ for performance issues")
  InvokeAgent("Review src/runtime/ for error handling gaps")
  InvokeAgent("Review src/runtime/ for missing tests")
  → Wait for all task handles to complete
  → Aggregate findings into final report

Specialized delegates

Assign specialized agents for distinct concerns:

Parent agent:
  InvokeAgent("Code review", template="code-reviewer")
  InvokeAgent("Test writing", template="test-writer")

Safe experimentation

Use worktree mode to let a child experiment without affecting the main workspace:

Parent agent:
  InvokeAgent("Try alternative implementation approach",
              workspace_mode=worktree)
  → Child works in isolated worktree
  → Parent reviews child's output
  → Parent applies the best approach to main workspace

Supervision Flow

A typical parent-child interaction:

Invoke — Parent calls InvokeAgent with initial_message describing the task
Monitor — Parent uses TaskStatus to check if the child is still working, sleeping, or waiting
Review — Parent reads TaskOutput to get bounded previews or wait for completion
Deliver — Parent aggregates child results into the final user-facing answer

The parent remains responsible for:

Verification — Child output is evidence, not authority
Aggregation — Combining results from multiple children
Final delivery — The parent produces the user-facing answer

Best Practices

Keep delegations focused. Each child should have one clear objective.
Supervise explicitly. Check TaskStatus before assuming completion.
Treat child output as evidence. Review and verify before passing to the user.
Limit parallelism. Invoke only as many agents as the task actually benefits from.
Stop idle children. Use TaskStop for children that are no longer needed.