Subagents

A subagent is another agent loop the parent calls as a tool with a task. The child runs its own reasoning loop with its own tools and returns only its final text. There are three kinds.

The model ruleCopy Anchor Link

Every subagent of an agent — linked, derived, or started by delegate_task — runs on that agent's Sub-agent model (aiModel.subAgentModel). Unset (Same as main agent), it runs on the model the parent's turn runs on. A sub-agent model nothing can serve falls back to the main model with a warning in the logs; the subagent is never dropped.

There is no per-subagent model, and a linked child's own default model is not used. Set the sub-agent model to something cheaper than the main list — it doesn't have to be on it. See Agents.

Linked subagentsCopy Anchor Link

A stored agent mounted by id: { "type": "agent", "agentId": "<id>" }. The parent sees it as subagent_<name>, named after the child, with the child's description as the tool description. The child runs with its own instructions and its own tools.

A linked child mounts only for callers inside its own sharing audience; with no sharing set, it inherits the parent's.

Derived subagentsCopy Anchor Link

Defined inline on the parent — no separate agent to create:

{
  "type": "agent",
  "derive": {
    "name": "researcher",
    "description": "Finds and summarizes sources",
    "instructions": "Research the question and cite what you find.",
    "tools": { "allow": ["web_search", "web_fetch"], "deny": [] }
  }
}

• name — required: 1–64 letters, digits, spaces, _ or -, starting with a letter or digit, and unique on the parent. The tool is subagent_<name>.
• description — the tool description the parent sees. Default: "Derived helper of" plus the parent's name.
• instructions — replace the parent's instructions for this child. Default: the parent's.
• tools — narrow the parent's tool list. Entries match by type, name, or id; deny always wins, and a non-empty allow keeps only what it names. A tool the parent doesn't have can never be added.

Derived subagents need a stored parent agent; an inline chat agent can't have them. An invalid or duplicate entry is skipped with a warning.

delegate_taskCopy Anchor Link

A built-in tool (Add tool → Built-in tools) that lets the agent start its own helpers. Each call starts a fresh helper with the parent's instructions — behind a short preamble telling it to work alone and reply with the complete result — and the parent's tools. The helper can't see the conversation, so the task must carry everything it needs; an optional label (up to 60 characters) names the helper for the user.

Calls in the same step run in parallel. A turn may start at most 5 helpers; past that, the tool tells the agent to finish the work itself.

What a child never getsCopy Anchor Link

All three kinds run on the server inside the parent's turn, as the same user, with these left out:

• other subagents and delegate_task — no nesting;
• the memory, handoff, and run_code built-ins;
• MCP servers, connected apps, and skills;
• browser tools (executeOnClient), which need a page to run in.

Tools are still narrowed by sharing for the chat user, exactly as for the parent.

Adding themCopy Anchor Link

Add delegate_task from the agent editor. Linked and derived entries go in the agent's tools list through the API (PATCH /agents/:id); the editor lists saved ones in the Toolbox, where they can be removed but not added.

Which to pickCopy Anchor Link

Derive for a fixed helper with a small tool set — the researcher, the formatter. Link when the child is a real agent in its own right: chatted with directly, shared with its own audience. Turn on delegate_task when the work splits into independent pieces the agent can't predict.