Building agents: When to fold subagents into your main agent loop
by Anthropic
When one agent loop with skills and tool search beats a router plus specialist subagents, and how to migrate in stages.
Overview
Building agents: When to fold subagents into your main agent loop is an October 22, 2026 article on claude.com by Diane Sarkis, drawn from Anthropic Applied AI work with enterprise deployments where a single agent with skills often scored higher than both a one-prompt design and a subagent design, at lower cost and latency per task. It opens with the failure modes of large organisations that give each team its own agent and put an orchestrator on top: lossy handoffs between agents, subagent sprawl, a 'Frankenprompt' of conflicting rules, unowned evals, and latency (one customer's single loop ran about 2x faster than its multi-agent harness). It then makes the case for one context window using skills and tool search, and keeps subagents for context bloat, parallel work with discardable context, and black-box verification. The migration section is the practical core: build task-completion evals first (10 golden examples is enough to start), merge subagents that chain together, call others as tools, then fold one at a time into skills and MCP tools and check which tasks flipped. It closes with how several teams can contribute skills, tools and knowledge bases to one agent, and notes that tool choice degrades past about 30 to 50 tool definitions. A companion Apache-2.0 repo, anthropics/single-agent-loop-kit, packages the workflow as a Claude Code skill with a runnable support-desk demo.
At a Glance
- Topic
- Agentic
- Level
- Intermediate
- Format
- Guide
- Cost
- Free
- Duration
- ~18 min read, plus a few hours with the companion migration kit
- Provider
- Anthropic
- Hands-on
- Yes — code/exercises
- Certificate
- None
What You’ll Learn
- ✓Recognise when an orchestrator-subagent design has come to mirror the org chart
- ✓Decide which subagents to keep for parallel work, context isolation or independent verification
- ✓Build a shared end-to-end task-completion eval before changing any agent architecture
- ✓Merge specialist subagents that chain on each other's output or share the same data
- ✓Convert a subagent's prompt into a skill and its API calls into MCP tools
- ✓Move hard preconditions and per-user permissions into tools that return actionable refusals
- ✓Compare folded and unfolded variants task by task instead of on aggregate score alone
- ✓Run the companion kit's audit, baseline, merge and fold steps against your own agent repo
Highlights
- •Grounded in Anthropic Applied AI's enterprise deployments, with concrete failure cases such as a fold that broke a delivery-date lookup in one of two runs
- •Ships with anthropics/single-agent-loop-kit on GitHub (about 550 stars), whose support-desk demo has a free offline smoke test with no API key
- •Covers the organisational side: one central team owning the system prompt and evals while domain teams own skills and tools
- •Pairs with the claude-api build-eval, prompt-audit, hillclimb and cost-optimize commands for measuring each change
Who It’s For
Best For
- ✓Teams whose multi-agent system has grown one subagent per team or problem type
- ✓Platform engineers deciding between orchestrator-subagent and single-loop designs
- ✓Engineers planning an agent migration to newer models that rigid harnesses are blocking
Prerequisites
- •Experience building or operating an LLM agent with tools, ideally one with subagents
- •Basic understanding of agent evals; Python 3 and Claude Code to run the companion kit
FAQ
What is Building agents: When to fold subagents into your main agent loop?
This Anthropic guide is for teams running multi-agent systems, typically a router in front of specialist subagents, who suspect the design is costing them quality and latency. It explains when a single agent loop with progressively disclosed skills and tools does better, and walks through an eval-driven migration that folds subagents in one at a time.
Is Building agents: When to fold subagents into your main agent loop free?
Building agents: When to fold subagents into your main agent loop is free to access.
What level is Building agents: When to fold subagents into your main agent loop for?
Building agents: When to fold subagents into your main agent loop is aimed at a intermediate audience. Recommended background: Experience building or operating an LLM agent with tools, ideally one with subagents, Basic understanding of agent evals; Python 3 and Claude Code to run the companion kit.
How long does Building agents: When to fold subagents into your main agent loop take?
Expect roughly ~18 min read, plus a few hours with the companion migration kit. Most learners work through it at their own pace.
What will I learn from Building agents: When to fold subagents into your main agent loop?
You'll learn: Recognise when an orchestrator-subagent design has come to mirror the org chart; Decide which subagents to keep for parallel work, context isolation or independent verification; Build a shared end-to-end task-completion eval before changing any agent architecture; Merge specialist subagents that chain on each other's output or share the same data; Convert a subagent's prompt into a skill and its API calls into MCP tools; Move hard preconditions and per-user permissions into tools that return actionable refusals; Compare folded and unfolded variants task by task instead of on aggregate score alone; Run the companion kit's audit, baseline, merge and fold steps against your own agent repo.
Topics
Sources
This page was written from 3 sources, 2 on domains other than claude.com.