Building a subagent team

A roster is not a feature list. Every subagent you add is a routing decision the parent has to get right, and a description it pays for whether it delegates or not.

The parts

You declare subagents through the subagents parameter, and the parent reaches them with the task tool. The exact field names inside a subagent declaration are a reference lookup, and the casing differs between Python and TypeScript, so this lesson teaches the design rather than the schema. That is the right trade for a semi open book exam: the fields are one click away, the judgement is not.

What matters is that a subagent is another agent. Everything you know about model choice, tools, prompts and context applies to it unchanged. That is the architectural reading rather than a stated rule, and it holds because the whole library is one layer built out of the one below.

Descriptions are routing, not documentation

The corollary is the design rule for a team: descriptions must be mutually distinguishable. If two of them could plausibly cover the same request, the parent is not choosing badly, it is choosing between indistinguishable options. That is a writing problem, and reaching for a bigger model to fix it is treating a design fault as a capability shortfall.

Give each child the narrowest reach

A subagent that only reads and searches should not be holding execute. Two reasons, and the second is the one people skip.

Safety. A tool it does not have is a tool it cannot be talked into using, and module 2 established that nothing in the sandbox story defends against being talked into things.

Cost. Every tool the child holds contributes a description to the child’s context on every one of its turns. A forty-turn subagent pays that forty times.

Prompt instructions are not a substitute here. A prompt is a request; an absent tool is a constraint. The layered version, in increasing strength: shape the offering with LLMToolSelectorMiddleware, scope filesystem reach with permissions, bound the environment with the backend, and gate the irreversible with interrupt_on. Simply not registering the tool beats all of them and costs nothing.

Brief and contract

Because the parent never sees the child’s intermediate work, two things carry the whole relationship.

The brief is the child’s entire world. It cannot ask you a question halfway through and, in the default isolated mode, it does not inherit your reasoning. Anything you left out is not merely unmentioned, it is absent. (deepagents has one experimental exception, mode="fork", covered in the previous lesson; the default, and the exam, assume isolation.)

The output contract matters more than the instructions. The transcript is discarded. Whatever the child chose not to report is unrecoverable without re-running the whole thing, so specifying what comes back is a higher-leverage sentence than specifying how to work.

Write the contract as a shape the parent can act on. Return the three candidate files with a one-line reason each is a contract. Investigate thoroughly is a hope.

subagents = [
    {
        "name": "contract-reader",
        "description": (
            "Reads a contract end to end, extracts every clause "
            "mentioning renewal, notice periods or auto-escalation, "
            "ignores boilerplate, and returns them verbatim with "
            "page numbers, working paragraph by paragraph."
        ),
        "system_prompt": "You read contracts.",
        "tools": [read_file, grep],
    },
    {
        "name": "crm-lookup",
        "description": "Answers questions about accounts, owners and stages.",
        "system_prompt": "You query the CRM and report what you find.",
        "tools": [crm_search, crm_get],
    },
]