Task Tool
Agent SDKDefinition
The built-in Agent SDK tool used to invoke a subagent. Takes a task description, available tools, and optional context. The subagent runs its own agentic loop in an isolated context and returns its final result. The primary mechanism for multi-agent delegation.
Example Usage
Use the Task tool to delegate 'search for recent papers on MCP' to a subagent with only the web_search tool available.
In Depth
The Task tool is the Agent SDK's built-in mechanism for delegating work to a Subagent. It is not a user-defined tool — it ships with the SDK and is available to any orchestrator agent automatically. When an orchestrator calls the Task tool, it provides three things: a natural-language task description, a list of tools the subagent is allowed to use, and any context the subagent needs (injected into the subagent's prompt). The SDK then spins up a new agent instance with a fresh context window, runs the full Agentic Loop for that subagent, and returns the subagent's final output as a tool_result back to the orchestrator.
From the orchestrator's perspective, calling the Task tool looks identical to calling any other tool: the SDK emits a tool_use content block with name: "Task", the SDK handles execution, and a tool_result block arrives in the next turn. This uniformity is deliberate — it means orchestrators can mix Task-tool calls with regular tool calls in parallel, and the orchestrator's loop logic does not need special casing.
The tool's isolation contract is important: the subagent only sees what the orchestrator explicitly puts into the task description. Shared state, session history, and orchestrator-level context are *not* automatically visible. This design enforces Least Privilege (Tool Access) and limits the blast radius of Prompt Injection attacks targeting subagents.
A common exam distractor conflates the Task tool with fork_session. They are different: the Task tool creates a fully independent subagent with no ongoing relationship to the orchestrator's session. fork_session copies the *current* session state for exploratory branching. Use the Task tool for delegation; use fork_session for parallel exploration within one logical task.
See also Subagent Invocation & the Task Tool for a deeper treatment of invocation patterns, context passing, and result handling.
How It's Tested & Common Confusions
Exam questions test three things about the Task tool:
- Invocation mechanics — knowing that the Task tool is the SDK-native way to spawn a subagent, not a custom tool you define.
- Context isolation — confirming that the subagent only sees what the orchestrator explicitly passes, not the full orchestrator history.
- Task tool vs. fork_session — distinguishing delegation (Task tool) from session branching (fork_session). Questions often present a scenario and ask which construct is appropriate.
Frequently Asked Questions
Is the Task tool something I define, or does the SDK provide it?
The SDK provides it. The Task tool is a built-in SDK primitive, not a user-defined tool. You do not write a handler for it — the SDK intercepts Task tool calls and handles subagent creation and result injection automatically.
Can a subagent also use the Task tool to spawn its own sub-subagents?
Yes. Subagents are full agent instances, so if the Task tool is in their allowed-tools list, they can delegate further. This enables hierarchical multi-agent topologies. However, deep nesting increases coordination overhead and makes debugging harder — keep hierarchies shallow unless the problem structure demands depth.
How do I pass context from the orchestrator to the subagent via the Task tool?
Embed the needed context directly in the task description string. The subagent starts fresh — it has no access to the orchestrator's conversation history. Treat it like writing a well-scoped ticket: include all inputs the subagent needs, but omit everything irrelevant to keep its context window lean.