shipitagent

Tools · Agents and tools

sub_agent

Changes things

Delegate a focused task to a sub-agent with its own context and tools. Use for searches that would flood your context, or for independent work you can run in parallel.

When to use: Delegate when a task would flood your context (a wide search, a long file to summarize) or when several independent pieces of work can run at once. Do NOT delegate work you can do with one tool call. Reading a file, listing a directory, one lookup, or writing the answer are all faster done yourself, and a sub-agent doing them costs an extra model call and loses everything it saw. If you find yourself delegating every step, use the tools directly instead. The sub-agent starts fresh: it sees only the `task` and `details` you give it, not your conversation. Say what you want back. `agent_type` picks a specialist (researcher, code-reviewer, data-analyst, …); omit it for a general-purpose one. `background=true` returns a task id immediately so you can keep working; `collect="<id>"` fetches the result. Anything you start in the background must be collected in this same turn — the run ends with your answer, and there is no later turn in which results arrive on their own.

Example

Run for real by scripts/tool-examples.py in a small demo project, with Haiku 5.5 where the tool calls a model. The output is exactly what the tool returned, in 11.1s.

The call

tool call
{
  "tool": "sub_agent",
  "arguments": {
    "task": "Read README.md and src/pricing.py, then describe the project in one sentence."
  }
}

Real output

The project is a seat-based pricing service (per the README, "Seat-based pricing, with tests") whose `src/pricing.py` defines three plans with per-seat monthly prices (starter $12, team $29, enterprise $79) and a `price(plan, seats)` function that returns the plan price multiplied by the seat count.

Parameters

NameTypeDescription
task*stringThe task, stated so someone with no other context could do it. Say what to return.
detailsstringFacts the sub-agent needs — paths, ids, constraints. It cannot see your conversation.
agent_typestringA specialist role, e.g. 'researcher', 'code-reviewer'. Omit for general-purpose.
backgroundbooleanStart it and return a task id immediately so you can keep working.
collectstringA task id from a background call — waits for and returns that task's result. Pass 'all' to collect every outstanding task. When collecting, `task` is ignored, so repeat the original task text there.

* required

Hand work to sub-agents and find the right tool when there are many.