Subagents and Claude Managed Agents

What you’ll learn

Phase 3 continues. Lesson 8 built the agent-loop substrate. Lesson 9 catalogued the six canonical patterns. Lesson 10 added Agent Skills plus Claude Code. This lesson covers the two Anthropic-specific primitives that realize patterns 4 (orchestrator-workers) and 6 (autonomous agent) directly. The single capability this lesson builds: pick the right primitive for an agent workload (a single L8-style loop, a Subagent fan-out inside it, or Claude Managed Agents if you would rather not run the harness yourself), define a Subagent and a Managed Agent end to end, and reason about the cost, isolation, and data-retention trade-offs.

Concretely, you will know what a Subagent is (Anthropic docs verbatim: separate agent instances that your main agent can spawn to handle focused subtasks. Use subagents to isolate context for focused subtasks, run multiple analyses in parallel, and apply specialized instructions without bloating the main agent’s prompt), the four benefits (context isolation with only the final message returns to the parent, parallelization, specialized instructions, tool restrictions), the three creation paths (programmatic via the agents parameter on the SDK query() call as an AgentDefinition; filesystem-based as markdown in .claude/agents/; the built-in general-purpose agent), the AgentDefinition fields (description as the routing signal, prompt, tools whitelist, disallowedTools, model alias as a cost lever per L3, skills per L10, mcpServers per L6, memory per-subagent context, permissionMode security posture, maxTurns per L8, effort per L3, background), what subagents inherit (own prompt + Agent tool’s prompt string + project CLAUDE.md + tool definitions) and do NOT inherit (parent’s conversation history, preloaded Skills unless listed, parent’s system prompt), the constraint that subagents cannot spawn their own subagents, and the Workflow tool for fan-out beyond dozens to hundreds of agents.

You will also know what Claude Managed Agents is (verbatim: Pre-built, configurable agent harness that runs in managed infrastructure. Best for long-running tasks and asynchronous work; verbatim: Claude Managed Agents provides the harness and infrastructure for running Claude as an autonomous agent. Instead of building your own agent loop, tool execution, and runtime, you get a fully managed environment where Claude can read files, run commands, browse the web, and execute code securely), the four core concepts (Agent = model + system + tools + MCP + Skills; Environment = sandbox; Session = running instance; Events = messages), the five-step flow (POST /v1/agents → POST /v1/environments → POST /v1/sessions → send events / stream SSE → steer or interrupt), the managed-agents-2026-04-01 beta header (SDK auto-sets), the agent_toolset_20260401 tool type that enables the full pre-built set (bash, file operations, web search and fetch, MCP servers), and the data-retention posture (NOT ZDR eligible; NOT HIPAA BAA eligible; stateful by design; you delete sessions and uploaded files via the API).

Finally, you will know the decision frame between the three primitives (self-built L8 loop when ZDR matters or harness control matters; Subagents inside that loop for orchestrator-workers / parallelization / cost; Managed Agents for long-running async + minimal infrastructure when ZDR is not a constraint; the three compose).

Every substantive claim verifies against the public Anthropic Claude Agent SDK documentation at code.claude.com/docs/en/agent-sdk/subagents and the public Claude Managed Agents documentation at platform.claude.com/docs/en/managed-agents/.

Where this fits

This is lesson 11 of 12 of Track 22, the fourth lesson of Phase 3 (agent patterns). Lesson 8 built the substrate; lesson 9 catalogued the patterns; lesson 10 added the durable-instructions layer plus Claude Code; this lesson adds the two Anthropic-specific primitives for patterns 4 and 6. Lesson 12 (next, the track closer) ships whichever path you chose to production.

The cross-track companion is Track 20 (AI Agents and Tool Use) for the deeper engineering discipline of harness design and the broader principles that Subagents + Managed Agents productionize.

Before you start

Prerequisites: lessons 1-10 of this track. Lesson 8 is load-bearing (Subagents run inner L8-style loops; Managed Agents IS an L8-style loop, productionized and hosted). Lesson 9 is load-bearing (the patterns Subagents and Managed Agents realize). Lesson 3 is load-bearing for the per-Subagent model cost lever. Lesson 10 is load-bearing for the Agent Skills that Subagents preload via AgentDefinition.skills and Claude Code’s filesystem-based .claude/agents/ path.

Soft recommended: an Anthropic Console account at https://platform.claude.com/ and an API key (lesson 1). For the try-it-yourself (reasoning + dispatch, not coding), no setup required. To actually run the code samples, install the Claude Agent SDK (pip install claude-agent-sdk) for Subagents or use the standard Anthropic SDK with the managed-agents-2026-04-01 beta header for Managed Agents.

About the math

None. This lesson is taxonomic and structural: the Subagent primitive, the Managed Agents harness, and the decision frame between the three primitives. Cost arithmetic from lesson 3 (per-model rates) and the usage fields from lessons 2 + 7 apply unchanged; lesson 12 turns those into production monitoring.

By the end, you’ll be able to

The single capability this lesson builds: pick the right primitive for an agent workload, define a Subagent and a Managed Agent end to end, and reason about the cost, isolation, and data-retention trade-offs (per the Phase 0 lesson 11 capability mapping). Concretely, you will be able to:

State the Subagent definition verbatim and the four benefits (context isolation with only-final-message-returns; parallelization; specialized instructions; tool restrictions), and recognize the three creation paths (programmatic via agents parameter on query(), filesystem-based as markdown in .claude/agents/, built-in general-purpose)
Compose a valid AgentDefinition (required description as the routing signal, required prompt as the system prompt, optional tools whitelist, optional model alias as a cost lever, optional skills + mcpServers + maxTurns + effort) and respect the constraint that subagents cannot spawn their own subagents
State Claude Managed Agents verbatim and identify what Anthropic hosts (agent loop, sandbox, tool execution, runtime, session state, event history, caching, compaction) versus what you provide (agent definition, environment config, user events)
Walk the Managed Agents five-step flow (POST /v1/agents + POST /v1/environments + POST /v1/sessions + send events / stream SSE + steer or interrupt) and recognize the managed-agents-2026-04-01 beta header and the agent_toolset_20260401 tool type
Apply the decision frame across the three primitives (self-built L8 loop for control or ZDR; Subagents inside that loop for orchestrator-workers / parallelization / cost; Managed Agents for long-running asynchronous work when ZDR is not a constraint) and recognize Managed Agents’ data-retention posture (NOT ZDR eligible; NOT HIPAA BAA eligible)

Time and difficulty

Read time: about 16 minutes
Practice time: about 15 minutes (the try-it-yourself walks the decision frame on three real workloads and picks the simplest primitive for each, plus flashcards for retrieval)
Difficulty: standard. Two primitives, four-property + four-concept taxonomies, one decision frame. The hardest skill is recognizing the data-retention constraint that pushes a workload off Managed Agents; the easiest is recognizing the orchestrator-workers fit for Subagents on any task with independent subtasks.