Subagent Invocation & Context Passing

How to spawn subagents using the Task tool, pass context explicitly (since nothing is inherited), configure AgentDefinitions with restricted tool sets, and leverage fork-based session management for parallel exploration.

Quick Reference

→The Task tool is the mechanism for spawning subagents -- allowedTools must include 'Task' for the coordinator
→Subagents inherit NOTHING automatically -- all context must be explicitly provided in the prompt
→AgentDefinition configures each subagent: description, system prompt, allowed tools, and model
→Multiple Task tool calls in a single response spawn parallel subagents
→Use structured data formats (JSON, XML) to separate content from metadata in subagent prompts
→Include source attribution metadata (URLs, page numbers, timestamps) for traceability
→fork_session creates divergent branches for comparing approaches without affecting the main session
→Subagent tool sets should be restricted to only what the subtask requires
→Design subagent prompts with clear output format expectations for consistent coordinator parsing
→Keep subagent prompts focused -- a 200-word focused prompt outperforms a 2000-word unfocused one

The Task Tool: Spawning Subagents

Definition

The Task tool is the built-in mechanism in the Claude Agent SDK for spawning subagents. When the coordinator calls the Task tool, a new agent instance is created with its own isolated context, system prompt, and tool set. The coordinator's allowedTools configuration must include 'Task' for this to work.

Spawning a subagent is conceptually simple: the coordinator makes a tool call to 'Task' with a description of what needs to be done. The Agent SDK creates a new Claude instance, runs it to completion (its own agentic loop), and returns the result to the coordinator as a tool result. The subagent's entire lifecycle -- from prompt to final answer -- is encapsulated in a single tool call from the coordinator's perspective.

Each subagent receives explicit context and runs in isolation

Basic subagent spawning with the Task tool

Explicit Context Passing

Since subagents inherit nothing from the coordinator, every piece of information they need must be explicitly included in the Task tool call. This is both a constraint and an advantage: it forces you to think carefully about what context each subagent actually needs, and it prevents subagents from being distracted by irrelevant information.

AgentDefinition Configuration

Each subagent is configured through an AgentDefinition that specifies its identity, capabilities, and constraints. Thoughtful configuration is the difference between a subagent that produces focused, useful results and one that wanders off-task.

Sign in to read this article

This is a premium article. Sign in with your Google account to continue.