Subagent Invocation & the Task Tool

Core

Configure subagent invocation, context passing, and spawning · Difficulty 3/5

subagenttask-toolspawningcontext-passing

Prerequisites

Coordinator-Subagent (Orchestrator) Pattern

Subagents in the Agent SDK are spawned using the Task tool. The coordinator must be configured with allowedTools that includes "Task" to invoke subagents.

Key Mechanics

Task tool: The mechanism for spawning subagents. Each Task tool call creates an independent subagent execution.

allowedTools: The coordinator's tool list must include "Task" or it cannot delegate work.

AgentDefinition: Configures each subagent type with descriptions, system prompts, and tool restrictions.

Context Isolation

Subagents do NOT automatically inherit parent context or share memory between invocations. All necessary context must be explicitly provided in the subagent's prompt. This means:

Pass complete findings from prior agents directly in the prompt

Use structured data formats to separate content from metadata (URLs, document names, page numbers) for attribution

Don't assume the subagent knows anything not in its prompt

Parallel Spawning

Spawn parallel subagents by emitting multiple Task tool calls in a single coordinator response rather than across separate turns. This is analogous to Claude's parallel tool use -- multiple tasks in one response minimizes round-trips.

Coordinator Prompt Design

Specify research goals and quality criteria rather than step-by-step procedural instructions. This enables subagent adaptability -- the subagent can decide HOW to achieve the goal rather than rigidly following prescribed steps.

Key Takeaways

✓The Task tool spawns subagents; allowedTools must include "Task" for the coordinator
✓Subagents have isolated context -- all needed information must be passed explicitly in the prompt
✓Spawn parallel subagents with multiple Task calls in a single coordinator response
✓Design coordinator prompts with goals and quality criteria, not step-by-step procedures