Skip to content
Clawdemy

Summary: Subagents and Claude Managed Agents

Two Anthropic-specific primitives that realize lesson 9’s patterns 4 (orchestrator-workers) and 6 (autonomous agent) directly. Subagents (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) live in the Claude Agent SDK. Three creation paths: programmatic via the agents parameter on the SDK query() call (the AgentDefinition with description / prompt / tools / model / skills / mcpServers / maxTurns / effort / background); filesystem-based as markdown in .claude/agents/; the built-in general-purpose agent. Four properties: context isolation (only the final message returns to the parent; intermediate work stays in the subagent), parallelization (concurrent subagents), specialized instructions (per-subagent system prompt), tool restrictions (per-subagent tools whitelist). Per-subagent model is a real cost lever (small subagents on Haiku or Sonnet under an Opus parent). Subagents cannot spawn subagents. Beyond dozens to hundreds of subagents, use the Workflow tool. Claude Managed Agents (verbatim: Pre-built, configurable agent harness that runs in managed infrastructure. Best for long-running tasks and asynchronous work) is the Anthropic-hosted harness: Anthropic provides the agent loop, sandbox (cloud or self-hosted), tool execution (bash + file ops + web search + MCP), long-running session state, and server-side event history; you POST user events and receive SSE events. Four core concepts: Agent (model + system + tools + MCP + Skills), Environment (sandbox), Session (running instance), Events (messages). Three endpoints: POST /v1/agents, POST /v1/environments, POST /v1/sessions. Beta header managed-agents-2026-04-01 (SDK auto-sets). Built-in tool set via agent_toolset_20260401. NOT ZDR or HIPAA BAA eligible (stateful by design). Decision frame: L8-style self-built loop when ZDR matters or harness control matters; Subagents inside that loop for patterns 4 (orchestrator-workers) + 3 (parallelization) + cost optimization via smaller per-subagent models; Managed Agents for long-running asynchronous work where you skip the harness and ZDR is not a constraint. The three compose; most production stacks mix them. Lesson 12 ships whichever path you chose.

Core ideas

Section titled “Core ideas”
  • Subagents = the spawn primitive for focused inner loops. Verbatim: separate agent instances that your main agent can spawn to handle focused subtasks. Defined programmatically (agents parameter on SDK query()), filesystem-based (.claude/agents/ markdown), or via the built-in general-purpose.
  • Four Subagent benefits: (1) context isolation (only the final message returns to the parent); (2) parallelization (concurrent subagents); (3) specialized instructions (per-subagent system prompt); (4) tool restrictions (per-subagent tools whitelist).
  • AgentDefinition essentials: description (routing signal), prompt (system prompt), tools (whitelist), model (alias or full ID; cost lever per L3), skills (L10 preload), mcpServers (L6), maxTurns (L8 discipline), effort (L3 dial). Subagents cannot spawn subagents.
  • Inheritance: Subagent receives its own prompt + Agent tool’s prompt string + project CLAUDE.md + tool definitions. Does NOT receive parent’s conversation history, preloaded Skill content (unless listed), or parent’s system prompt.
  • Subagents realize L9 patterns directly: pattern 4 (orchestrator-workers) = parent loop + worker subagents; pattern 3 (parallelization, sectioning) = concurrent subagents; pattern 6 (autonomous agent) = parent spawning many subagents over a long run. Workflow tool scales beyond dozens to hundreds of agents.
  • Per-subagent model is a cost lever. Smaller cheaper model per subagent is L3’s mix-and-match applied per-step. The docs’ worked example: strict security review on opus; balanced on sonnet; orchestrator on opus.
  • Claude Managed Agents = the hosted harness. Verbatim: Pre-built, configurable agent harness that runs in managed infrastructure. Best for long-running tasks and asynchronous work. Anthropic provides: agent loop, sandbox, tool execution, runtime, session state, event history, caching, compaction.
  • Four core concepts + five-step flow: Agent / Environment / Session / Events. (1) agents.create (2) environments.create (3) sessions.create (4) send events / stream SSE (5) steer or interrupt. Beta header managed-agents-2026-04-01 auto-set by SDK.
  • Built-in tools via agent_toolset_20260401: bash, file operations, web search and fetch, MCP servers.
  • Data retention: Managed Agents NOT ZDR eligible; NOT HIPAA BAA eligible (stateful by design). You retain control via delete sessions + delete uploaded files.
  • Decision frame: L8-style loop for control + ZDR; Subagents for orchestrator-workers + parallelization + cost; Managed Agents for long-running async + minimal infrastructure (when ZDR not required). The three compose.
  • Where this fits: Phase 3 fourth lesson. L12 (next) ships the result.

What changes for you

Section titled “What changes for you”

Before this lesson, patterns 4 (orchestrator-workers) and 6 (autonomous agent) from lesson 9 were design intent without concrete primitives; you would have had to build the spawn-and-context-isolation primitive yourself. After this lesson, Subagents (Claude Agent SDK) give you that primitive in a single API call with per-subagent tools and per-subagent model, and Claude Managed Agents give you the entire harness when you would rather not run the sandbox at all. The two highest-leverage takeaways for the week: (1) for any agentic workload that has obvious independent subtasks (review checks, multi-source research, multi-file refactors), reach for Subagents and put each subtask on the smallest model that holds quality on your eval (the per-subagent model field is a real cost lever); (2) for any workload that runs longer than a few minutes and persists state across turns (background research, long-running automation, multi-session work), the Managed Agents path saves you from building a harness that ends up being more complex than the agent itself, as long as ZDR is not a constraint. Lesson 12 (the track closer) turns whichever path you chose into a shipped production application with cost monitoring on usage + usage.iterations, eval-set discipline, and the rollout checklist.