Single agent vs multi-agent: when subagents are worth it
Single agent vs multi-agent is a trade-off between one shared context and several isolated ones. For many production setups in late 2026, Anthropic's Applied AI team now recommends defaulting to one agent loop with skills and tools loaded on demand, and keeping a subagent only when evals show it still beats the folded version — or when it truly needs its own context window, parallel runs, or permission isolation. That is the practical answer; the rest of this post is how to decide for your stack.
On 22 October 2026 Anthropic published Building agents: When to fold subagents into your main agent loop, arguing that enterprise agents with routers, planners and a subagent per team often lose quality, voice and speed to handoffs and "Frankenprompt" system prompts. The same week they shipped the single-agent-loop-kit on GitHub (Apache 2.0; README: reference implementation, not maintained, not accepting contributions). THE DECODER summarised the piece on 25 October, including Anthropic's note that one customer saw roughly 2× faster runtime on a single-agent loop than on their multi-agent harness in an internal comparison.
None of that means subagents are dead. It means the bar moved: newer models (Anthropic cites Opus 4.5 onward, plus Opus 5.5 and Fable 5.1) can carry more planning inside one loop, so a lot of harness code and org-chart architecture may be doing work the model no longer needs.
What changed in the single agent vs multi-agent debate
Multi-agent designs looked rational for a long time. Each team ships a specialist subagent; a central orchestrator routes intent; evals live next to each specialist. Conway's law, but for tokens.
Anthropic's write-up lists what that buys you in pain:
- Context loss at every handoff between agents.
- Subagent sprawl — hundreds of overlapping agents with no shared owner.
- Conflicting system prompts when every team adds a sentence.
- Local evals that optimise subtasks but dilute end-to-end quality.
- Latency from nested model loops; the ~2× runtime figure above is one datapoint from their customer comparison, not a guarantee for your workload.
Their counter-pattern is a single agent loop: one model, one context window, batched tool calls per turn, turn and cost budgets in the harness, and the model revising its own plan as tool results arrive — instead of a planner agent handing a lossy summary to a worker agent.
Progressive disclosure is the mechanism: short descriptions of skills and tools in context, full content only when the model selects them. Anthropic says that pattern let them cut Claude Code's system prompt for newer models by over 80%, partly by moving procedure into skills and actions into tools.
A single agent with skills and MCP tools
Skills and tools answer different questions. Anthropic's article is explicit:
- Skills — how a team does work: steps, rules, tone, edge cases. That is what used to sit in a subagent's long system prompt.
- Tools — what the agent can do: fetch live data, write with guardrails, call an API, or temporarily wrap a subagent you have not folded yet.
MCP fits on the tool side when the same integrations must work across hosts (Claude, ChatGPT, Cursor, your product). The model still chooses tools through ordinary function calling; MCP standardises discovery and execution. I wrote the layer cake in MCP vs function calling; the short version is that MCP does not replace tool use — it packages tools for reuse.
Anthropic also warns that tool choice degrades beyond roughly 30–50 tool definitions in the prompt at once. Mitigate with tool search, grouping tools by user intent, and preconditions inside the tool so the model gets a readable refusal.
One open-ended loop, procedure in skills, side effects in tools, and a small central team on the system prompt plus shared end-to-end eval — domain teams ship skills and tools with their own small evals, vetted before merge. Without that ownership, you get skill sprawl instead of subagent sprawl.
When a subagent still earns its place
Anthropic keeps subagents on the table when:
1. Context bloat is measurable — the single loop's quality drops as history and tool output accumulate, and trimming or summarising is not enough.
2. True parallelism — several heavy tasks need fresh context windows at the same time, then discard them.
3. Tool or instruction conflict — one prompt cannot reliably pick among overlapping tools, or teams have written incompatible rules.
They also use subagents for verification, parallel research paths, and modular permissioning in their own multi-agent research system. The guidance is not "never subagent"; it is "stop giving every team a subagent by default."
Even when you keep one, the article prefers calling it as a tool from the main loop so the primary agent keeps the user thread. Full handoff is for when the specialist must talk to the user directly.
Single agent vs multi-agent at a glance
| | Single agent loop | Multi-agent (orchestrator + subagents) |
| --- | --- | --- |
| Context | One window; shared history across steps | Separate windows; summaries passed between agents |
| Instructions | One system prompt + skills loaded on demand | Many prompts; risk of contradiction |
| Latency | One nested loop; parallel tools per turn | Often nested loops per subagent call |
| Parallelism | Parallel tool calls; sequential reasoning | Natural fit for parallel agents |
| Ownership | Central team on prompt + E2E eval | Easy to mirror teams; hard to maintain voice |
| Migration | Fold specialists into skills/tools incrementally | Already sunk cost in many prompts and evals |
| Best when | Most customer-facing and ops agents | Deep research, parallel paths, strict isolation |
Decision checklist: fold or keep?
Use this before you add another subagent — or when Anthropic's migration story lands on your roadmap:
- Does this work need its own context window? Deep research, long independent branches, or contexts you must discard after one task → subagent candidate. Everything else → try a skill first.
- Is the work truly parallel? If tasks must run at the same time with separate token budgets, subagents (or separate loop invocations) still make sense. If work is sequential but owned by different teams, that is not automatically parallel.
- Isolation or compliance handoff? Separate credentials, audit boundaries, or a verifier that must not see draft content → consider a dedicated loop or tool-gated subagent.
- Otherwise, fold it. Turn the subagent prompt into a skill, wire APIs as tools (MCP where reuse matters), run the shared eval, and keep the subagent only if scores drop.
Anthropic's support-desk example in the kit is instructive in the negative direction: folding one subagent lowered latency but broke a process that had been passing — the main agent answered shipping questions without calling the specialist. Their fix is boring and essential: eval tasks for every production chain and every rule that must not break, run more than once per task.
How to migrate one subagent at a time
You do not rewrite the fleet in a weekend. Anthropic's staged path:
1. Task-completion evals — shared end-to-end set plus per-skill sets; ten golden tasks beats zero.
2. Combine subagents that always run back-to-back on the same data.
3. Subagents as tools — baseline on the eval before rewriting.
4. Fold — prompt → skill, APIs → tools; compare scores; keep the subagent if the folded version loses.
The single-agent-loop-kit chains eval build, prompt audit, hillclimb and cost-optimize skills. README: reference implementation, not maintained.
Folding does not replace caps, idempotency or replay rules — see durable AI agents. For coding harnesses, Claude Code vs Codex is the parallel "one loop vs delegated queue" question.
Designing an agent architecture and want the eval set, tool boundaries and cost caps settled before you ship?
Costs and latency
Multi-agent setups pay nested model rounds and lossy handoffs — extra latency and input tokens even when the final answer looks fine. A single loop still needs good skill and tool descriptions and tool search; it is not automatic savings.
For build budgets see AI agent development cost; for token spend inside one loop, keeping Claude's token bill under control.
FAQ
What is the difference between a single agent and a multi-agent system?
A single agent is one model in one context window running an open-ended tool loop: it loads skills and tools on demand and keeps intermediate results in the same thread. A multi-agent system adds subagents — separate loops with their own prompts, tools and context — usually coordinated by a router or orchestrator. Multi-agent setups can parallelise work and isolate permissions; they also add handoffs, latency and duplicated instructions unless each subagent earns its place.
When should I use subagents?
Anthropic's guidance (October 2026) keeps subagents when a single loop shows measurable degradation from context bloat, when several tasks must run in parallel with fresh context windows, or when one agent cannot reliably choose tools or follow conflicting instructions in one prompt. If none of those apply, prefer folding specialist prompts into skills and their API calls into tools in the main loop, then compare on the same eval.
Are agent skills the same as MCP tools?
No. Skills hold procedural knowledge — steps, rules and judgment calls that used to live in a subagent's system prompt — and load when the model needs them. MCP tools (or plain function tools) are how the agent acts: read live data, call APIs, enforce permissions, or invoke a subagent you have not folded yet. Anthropic recommends skills for how a team works and tools grouped by user intent for what the agent can do.
How do I migrate from multi-agent to single agent without breaking production?
Build or reuse a shared end-to-end eval, then change one subagent at a time: turn its prompt into a skill and its integrations into tools, run the eval before and after, and keep the subagent only if the folded version scores worse. Anthropic's single-agent-loop-kit chains Claude API skills for evals, prompt audit and hillclimbing; it is Apache 2.0 and labelled a reference implementation that is not maintained.
---
I'm Joan Comadran, an AI engineer and full-stack developer in Barcelona (industrial engineering background). I write guides like this from vendor docs and shipped agent work — not from a fictional subagent migration on this site. If you want someone to draw the single-loop vs subagent line on a real product, that's what I do.
---
Originally published on joancomadran.dev. I'm Joan, an AI engineer in Barcelona — work with me.
3 reactions · 1 comment
Anthropic Says Fold Your Subagents. Let's Build a Tiny Single Agent Loop in TypeScript.
---
title: "Anthropic Says Fold Your Subagents. Let's Build a Tiny Single Agent Loop in TypeScript."
published: true
description: "Anthropic now suggests one agent loop that loads skills and tools on demand instead of a fleet of subagents. Build a tiny TypeScript version with a turn budget and a write gate. No API key."
tags: ai, typescript, agents, llm
cover_image: bhjr.dev
---
A lot of agent systems look like org charts.
There's a router at the top. Under it, a refunds agent. A shipping agent. A billing agent.
Each one has its own prompt, its own tools, and its own context window.
It feels organized. It also means every handoff is a summary of a summary.
Every handoff loses something.
This week, Anthropic published Building agents: When to fold subagents into your main agent loop. The opening line is the whole argument: "using fewer subagents in favor of progressively disclosed context and tools can improve quality while reducing cost and latency."
The idea is simple. The agent sees short descriptions of skills and tools up front. The full versions load only when needed.
Anthropic gives three reasons. Shared context produces better answers. Progressive disclosure prevents context bloat. And models are more capable now, starting with Opus 4.5.
One detail stood out. Anthropic says it cut Claude Code's system prompt for more advanced models by over 80%, including cuts from progressively disclosing skills and tools.
It also shipped a migration kit. The kit "does not assume a single loop always wins. It measures."
That distinction matters.
This isn't "subagents are bad." Anthropic still lists cases for them: measurable context bloat, parallel disposable work, and conflicting tools or instructions.
It's "stop splitting work just because the prompt got long."
I've built the other side of this before. My fan-out budget post was about limiting a thousand subagents. This one is about not needing most of them.
So let's build a tiny version.
By the end, you'll run one command:
npx tsx loop.ts
And watch one loop handle a refund by loading only what it needs, then stop at a write gate.
The full code is on GitHub.
Table of Contents
1. [The Problem With Org Chart Agents](#1-the-problem-with-org-chart-agents)
2. [Step 1: A Catalog With Two Levels](#2-step-1-a-catalog-with-two-levels)
3. [Step 2: What the Model Sees Up Front](#3-step-2-what-the-model-sees-up-front)
4. [Step 3: The Loader Tools](#4-step-3-the-loader-tools)
5. [Step 4: One Loop With Limits](#5-step-4-one-loop-with-limits)
6. [Step 5: Run It](#6-step-5-run-it)
7. [Where It Breaks Down](#7-where-it-breaks-down)
8. [The Bigger Idea](#8-the-bigger-idea)
1. The Problem With Org Chart Agents
Here's the usual shape:
Router
├→ refunds agent (own prompt, own tools, own context)
├→ shipping agent (own prompt, own tools, own context)
└→ billing agent (own prompt, own tools, own context)
A customer writes: "My package never came. Can I get a refund?"
That's shipping and refunds. The router picks one. Or both, and then something has to merge two summaries.
The shipping agent knows the package is lost. The refunds agent only knows what the summary said.
Teams split agents like this for a good reason. Putting every policy and every tool schema into one prompt makes it huge.
Progressive disclosure removes that reason.
The prompt doesn't have to be long if it only holds the table of contents.
2. Step 1: A Catalog With Two Levels
// tiny-single-loop: one agent, one context, skills and tools loaded on demand.
// Small model of the pattern Anthropic describes, not Claude's implementation.
// Fake model, fake tools, rough token estimate (chars / 4). No API key. No network.
type Skill = { name: string; description: string; body: string };
type Tool = { name: string; description: string; schema: string; write: boolean; run: (a: string) => string };
// Step 1: a catalog with two levels of detail
const skills: Skill[] = [
{ name: "refunds", description: "Refund or partially refund a customer order.",
body: "Refund policy: full refund within 30 days. After 30 days, store credit only. ".repeat(12) +
"Steps: look up the order, check the date, then issue_refund or issue_credit." },
{ name: "shipping", description: "Track, reroute, or reship a package.",
body: "Carrier rules, address change cutoffs, reship limits. ".repeat(20) },
{ name: "billing", description: "Explain charges, invoices, and failed payments.",
body: "Invoice formats, proration rules, retry schedules. ".repeat(20) },
];
const tools: Tool[] = [
{ name: "lookup_order", description: "Get an order by id.", schema: "{ id: string }".padEnd(240), write: false,
run: (id) => `order ${id}: $48.00, placed 12 days ago` },
{ name: "issue_refund", description: "Refund an order to the original payment.", schema: "{ id: string, amount: number }".padEnd(240), write: true,
run: (id) => `refunded order ${id}` },
{ name: "issue_credit", description: "Give store credit.", schema: "{ id: string, amount: number }".padEnd(240), write: true,
run: (id) => `credited order ${id}` },
{ name: "track_package", description: "Carrier tracking.", schema: "{ id: string }".padEnd(240), write: false, run: () => "" },
{ name: "reroute_package", description: "Change delivery address.", schema: "{ id: string, address: string }".padEnd(240), write: true, run: () => "" },
];
const tok = (s: string) => Math.ceil(s.length / 4);
Each skill has a one-line description and a long body.
Each tool has a one-line description and a full schema.
The descriptions are cheap. The bodies and schemas are not.
This mirrors Anthropic's Agent Skills format. A SKILL.md starts with a name and description. The body loads only when the skill is relevant.
My bodies are repeated filler so the token math is visible. Real ones would be real policy. Hopefully less repetitive. Probably not.
3. Step 2: What the Model Sees Up Front
// Step 2: what the model sees up front
function upfront(): string {
return skills.map((s) => `skill ${s.name}: ${s.description}`).join("\n") +
"\ntools: load_skill(name), tool_search(query)";
}
function everything(): string {
return skills.map((s) => s.body).join("\n") + tools.map((t) => t.schema).join("\n");
}
Two views of the same catalog.
upfront() is names, descriptions, and two loader tools.
everything() is what you'd paste into a giant system prompt.
The token estimate is rough: characters divided by four. Good enough to compare. Not good enough to bill.
4. Step 3: The Loader Tools
// Step 3: the two loader tools
type Ctx = { text: string; loaded: Set<string>; visible: Set<string>; log: string[] };
function loadSkill(c: Ctx, name: string) {
const s = skills.find((x) => x.name === name);
if (!s || c.loaded.has(name)) return;
c.loaded.add(name);
c.text += "\n" + s.body;
c.log.push(`load_skill(${name}) +${tok(s.body)} tok`);
}
function toolSearch(c: Ctx, query: string) {
const hits = tools.filter((t) => query.split(" ").some((w) => t.name.includes(w)));
for (const t of hits) { c.visible.add(t.name); c.text += "\n" + t.schema; }
c.log.push(`tool_search("${query}") -> ${hits.map((t) => t.name).join(", ")} +${hits.length * tok(hits[0]?.schema ?? "")} tok`);
}
Two tools do the disclosing.
load_skill reads one skill body into context, once.
tool_search finds matching tools and adds their schemas. Only visible tools can be called.
!Two levels of detail
The model decides what to load. The harness just keeps track of what's in context.
Load the chapter when you need it, not the whole manual.
5. Step 4: One Loop With Limits
// Step 4: one loop, with limits in the harness
type Limits = { maxTurns: number; approvedWrites: Set<string> };
function call(c: Ctx, lim: Limits, name: string, arg: string): string {
const t = tools.find((x) => x.name === name);
if (!t || !c.visible.has(name)) return `ERROR ${name} not loaded`;
if (t.write && !lim.approvedWrites.has(name)) return `GATE ${name} needs approval`;
return t.run(arg);
}
// A fake model: a plan of steps it would choose, one batch per turn.
const plan: Array<(c: Ctx, lim: Limits) => string | null> = [
(c) => { loadSkill(c, "refunds"); return null; },
(c) => { toolSearch(c, "order refund credit"); return null; },
(c, l) => call(c, l, "lookup_order", "1042"),
(c, l) => call(c, l, "issue_refund", "1042"),
];
function run(task: string, lim: Limits) {
const c: Ctx = { text: upfront() + "\n" + task, loaded: new Set(), visible: new Set(), log: [] };
let turn = 0;
for (const step of plan) {
if (++turn > lim.maxTurns) { c.log.push("STOP turn budget"); break; }
const out = step(c, lim);
if (out) c.log.push(out);
if (out?.startsWith("GATE")) break;
}
return { c, turn };
}
This is the shape Anthropic suggests. One model, one context window, an open-ended tool loop. The limits live in the harness: "turn and cost budgets, write gates."
My call function enforces two of them.
A tool must be loaded before it can run. No calling a schema you've never seen.
A write tool needs approval. Reads run freely. Refunds don't.
The fake model is just a list of steps. A real model would choose them each turn and revise its plan as results come in. Anthropic says that's the main change: "the model that writes the plan is also the one carrying it out."
!One loop, limits in the harness
6. Step 5: Run It
// Step 5: run it
console.log("tiny-single-loop demo (fake model, fake tools)\n");
console.log(`all skills + tools up front: ~${tok(everything())} tok`);
console.log(`names + descriptions only: ~${tok(upfront())} tok\n`);
const task = "Customer wants a refund for order 1042.";
for (const [label, lim] of [
["run 1 (no write approval)", { maxTurns: 6, approvedWrites: new Set<string>() }],
["run 2 (refund approved)", { maxTurns: 6, approvedWrites: new Set(["issue_refund"]) }],
["run 3 (turn budget 2)", { maxTurns: 2, approvedWrites: new Set(["issue_refund"]) }],
] as const) {
const { c } = run(task, lim);
console.log(label);
for (const l of c.log) console.log(" " + l);
console.log(` context at end: ~${tok(c.text)} tok, skills loaded: ${[...c.loaded].join(", ") || "none"}\n`);
}
Run it:
npm install
npx tsx loop.ts
Output:
tiny-single-loop demo (fake model, fake tools)
all skills + tools up front: ~1077 tok
names + descriptions only: ~55 tok
run 1 (no write approval)
load_skill(refunds) +250 tok
tool_search("order refund credit") -> lookup_order, issue_refund, issue_credit +180 tok
order 1042: $48.00, placed 12 days ago
GATE issue_refund needs approval
context at end: ~496 tok, skills loaded: refunds
run 2 (refund approved)
load_skill(refunds) +250 tok
tool_search("order refund credit") -> lookup_order, issue_refund, issue_credit +180 tok
order 1042: $48.00, placed 12 days ago
refunded order 1042
context at end: ~496 tok, skills loaded: refunds
run 3 (turn budget 2)
load_skill(refunds) +250 tok
tool_search("order refund credit") -> lookup_order, issue_refund, issue_credit +180 tok
STOP turn budget
context at end: ~496 tok, skills loaded: refunds
Read it top to bottom.
Putting every skill and tool up front costs about 1,077 tokens in this toy. Names and descriptions cost about 55.
Run 1 loads the refunds skill and finds three matching tools. It looks up the order. Then it hits the write gate on issue_refund and stops.
Run 2 is the same, with the refund approved. It goes through.
Run 3 has a turn budget of two. It stops before it touches the order.
In every run, shipping and billing never load. They cost nothing because nobody needed them.
The context ends around 496 tokens instead of starting at 1,077. These are toy numbers from toy bodies. The direction is the point, not the ratio.
7. Where It Breaks Down
This is a small model of the idea. It is not how Claude works, and it is not Anthropic's kit. The skills, tools, order, and token numbers are example inputs.
A few things it skips:
- Measuring. Anthropic's kit scores every change on the same eval before and after. I don't have an eval here. If you fold a subagent, measure first.
- Search quality. My tool_search matches substrings. A bad search hides the right tool, and the agent never knows it existed.
- Context still grows. Loading on demand delays bloat. A long session can still fill the window. Compaction still matters.
- Parallel work. Anthropic still recommends subagents for parallel, disposable work. One loop doesn't replace a thousand-file review.
- Conflicting instructions. If two skills give opposite rules, one context holds both. Separate agents can keep them apart.
- Real budgets. My turn budget counts steps. Real ones count cost and time too.
Fewer agents isn't the goal. Fewer lossy handoffs is.
8. The Bigger Idea
Task
↓
Up front: skill names + descriptions, loader tools
↓
Model loads a skill, searches for tools
↓
Harness checks: loaded? write approved? budget left?
↓
Tool runs, raw result returns to the same context
↓
Model revises the plan, repeats or answers
The model provides the plan.
The descriptions provide the map.
The skills provide the knowledge.
The tool search provides the hands.
The harness provides the limits.
The shared context provides the memory between steps.
For a while, the answer to a hard agent problem was another agent.
Now, at least for a lot of workloads, it might be a shorter prompt and a better index.
One loop that knows where to look beats five that each know a little.
---
Try Roster
I'm building Roster around this idea: AI employees with real responsibilities, tools, memory, schedules and computer access. One employee that keeps the whole picture beats a relay of handoffs.
If the same follow-ups, handoffs, and waiting loops keep eating your week, give them to an AI employee.
Try Roster →
Mentions
Single agent vs multi-agent: when subagents are worth it Single agent vs multi-agent is a trade-off between one shared context and several isolated ones. For many production setups in late 2026, Anthropic's Applied AI team now recommends defaulting to one agent loop with skills and tools loaded on demand, and keeping a subagent only when evals show it still beats the folded version — or when it truly needs its own context window, parallel runs, or permission isolation. That is the practical answer; the rest of this post is how to decide for your stack. On 22 October 2026 Anthropic published Building agents: When to fold subagents into your main agent loop, arguing that enterprise agents with routers, planners and a subagent per team often lose quality, voice and speed to handoffs and "Frankenprompt" system prompts. The same week they shipped the single-agent-loop-kit on GitHub (Apache 2.0; README: reference implementation, not maintained, not accepting contributions). THE DECODER summarised the piece on 25 October, including Anthropic's note that one customer saw roughly 2× faster runtime on a single-agent loop than on their multi-agent harness in an internal comparison. None of that means subagents are dead. It means the bar moved: newer models (Anthropic cites Opus 4.5 onward, plus Opus 5.5 and Fable 5.1) can carry more planning inside one loop, so a lot of harness code and org-chart architecture may be doing work the model no longer needs. What changed in the single agent vs multi-agent debate Multi-agent designs looked rational for a long time. Each team ships a specialist subagent; a central orchestrator routes intent; evals live next to each specialist. Conway's law, but for tokens. Anthropic's write-up lists what that buys you in pain: - Context loss at every handoff between agents. - Subagent sprawl — hundreds of overlapping agents with no shared owner. - Conflicting system prompts when every team adds a sentence. - Local evals that optimise subtasks but dilute end-to-end quality. - Latency from nested model loops; the ~2× runtime figure above is one datapoint from their customer comparison, not a guarantee for your workload. Their counter-pattern is a single agent loop: one model, one context window, batched tool calls per turn, turn and cost budgets in the harness, and the model revising its own plan as tool results arrive — instead of a planner agent handing a lossy summary to a worker agent. Progressive disclosure is the mechanism: short descriptions of skills and tools in context, full content only when the model selects them. Anthropic says that pattern let them cut Claude Code's system prompt for newer models by over 80%, partly by moving procedure into skills and actions into tools. A single agent with skills and MCP tools Skills and tools answer different questions. Anthropic's article is explicit: - Skills — how a team does work: steps, rules, tone, edge cases. That is what used to sit in a subagent's long system prompt. - Tools — what the agent can do: fetch live data, write with guardrails, call an API, or temporarily wrap a subagent you have not folded yet. MCP fits on the tool side when the same integrations must work across hosts (Claude, ChatGPT, Cursor, your product). The model still chooses tools through ordinary function calling; MCP standardises discovery and execution. I wrote the layer cake in MCP vs function calling; the short version is that MCP does not replace tool use — it packages tools for reuse. Anthropic also warns that tool choice degrades beyond roughly 30–50 tool definitions in the prompt at once. Mitigate with tool search, grouping tools by user intent, and preconditions inside the tool so the model gets a readable refusal. One open-ended loop, procedure in skills, side effects in tools, and a small central team on the system prompt plus shared end-to-end eval — domain teams ship skills and tools with their own small evals, vetted before merge. Without that ownership, you get skill sprawl instead of subagent sprawl. When a subagent still earns its place Anthropic keeps subagents on the table when: 1. Context bloat is measurable — the single loop's quality drops as history and tool output accumulate, and trimming or summarising is not enough. 2. True parallelism — several heavy tasks need fresh context windows at the same time, then discard them. 3. Tool or instruction conflict — one prompt cannot reliably pick among overlapping tools, or teams have written incompatible rules. They also use subagents for verification, parallel research paths, and modular permissioning in their own multi-agent research system. The guidance is not "never subagent"; it is "stop giving every team a subagent by default." Even when you keep one, the article prefers calling it as a tool from the main loop so the primary agent keeps the user thread. Full handoff is for when the specialist must talk to the user directly. Single agent vs multi-agent at a glance | | Single agent loop | Multi-agent (orchestrator + subagents) | | --- | --- | --- | | Context | One window; shared history across steps | Separate windows; summaries passed between agents | | Instructions | One system prompt + skills loaded on demand | Many prompts; risk of contradiction | | Latency | One nested loop; parallel tools per turn | Often nested loops per subagent call | | Parallelism | Parallel tool calls; sequential reasoning | Natural fit for parallel agents | | Ownership | Central team on prompt + E2E eval | Easy to mirror teams; hard to maintain voice | | Migration | Fold specialists into skills/tools incrementally | Already sunk cost in many prompts and evals | | Best when | Most customer-facing and ops agents | Deep research, parallel paths, strict isolation | Decision checklist: fold or keep? Use this before you add another subagent — or when Anthropic's migration story lands on your roadmap: - Does this work need its own context window? Deep research, long independent branches, or contexts you must discard after one task → subagent candidate. Everything else → try a skill first. - Is the work truly parallel? If tasks must run at the same time with separate token budgets, subagents (or separate loop invocations) still make sense. If work is sequential but owned by different teams, that is not automatically parallel. - Isolation or compliance handoff? Separate credentials, audit boundaries, or a verifier that must not see draft content → consider a dedicated loop or tool-gated subagent. - Otherwise, fold it. Turn the subagent prompt into a skill, wire APIs as tools (MCP where reuse matters), run the shared eval, and keep the subagent only if scores drop. Anthropic's support-desk example in the kit is instructive in the negative direction: folding one subagent lowered latency but broke a process that had been passing — the main agent answered shipping questions without calling the specialist. Their fix is boring and essential: eval tasks for every production chain and every rule that must not break, run more than once per task. How to migrate one subagent at a time You do not rewrite the fleet in a weekend. Anthropic's staged path: 1. Task-completion evals — shared end-to-end set plus per-skill sets; ten golden tasks beats zero. 2. Combine subagents that always run back-to-back on the same data. 3. Subagents as tools — baseline on the eval before rewriting. 4. Fold — prompt → skill, APIs → tools; compare scores; keep the subagent if the folded version loses. The single-agent-loop-kit chains eval build, prompt audit, hillclimb and cost-optimize skills. README: reference implementation, not maintained. Folding does not replace caps, idempotency or replay rules — see durable AI agents. For coding harnesses, Claude Code vs Codex is the parallel "one loop vs delegated queue" question. Designing an agent architecture and want the eval set, tool boundaries and cost caps settled before you ship? Costs and latency Multi-agent setups pay nested model rounds and lossy handoffs — extra latency and input tokens even when the final answer looks fine. A single loop still needs good skill and tool descriptions and tool search; it is not automatic savings. For build budgets see AI agent development cost; for token spend inside one loop, keeping Claude's token bill under control. FAQ What is the difference between a single agent and a multi-agent system? A single agent is one model in one context window running an open-ended tool loop: it loads skills and tools on demand and keeps intermediate results in the same thread. A multi-agent system adds subagents — separate loops with their own prompts, tools and context — usually coordinated by a router or orchestrator. Multi-agent setups can parallelise work and isolate permissions; they also add handoffs, latency and duplicated instructions unless each subagent earns its place. When should I use subagents? Anthropic's guidance (October 2026) keeps subagents when a single loop shows measurable degradation from context bloat, when several tasks must run in parallel with fresh context windows, or when one agent cannot reliably choose tools or follow conflicting instructions in one prompt. If none of those apply, prefer folding specialist prompts into skills and their API calls into tools in the main loop, then compare on the same eval. Are agent skills the same as MCP tools? No. Skills hold procedural knowledge — steps, rules and judgment calls that used to live in a subagent's system prompt — and load when the model needs them. MCP tools (or plain function tools) are how the agent acts: read live data, call APIs, enforce permissions, or invoke a subagent you have not folded yet. Anthropic recommends skills for how a team works and tools grouped by user intent for what the agent can do. How do I migrate from multi-agent to single agent without breaking production? Build or reuse a shared end-to-end eval, then change one subagent at a time: turn its prompt into a skill and its integrations into tools, run the eval before and after, and keep the subagent only if the folded version scores worse. Anthropic's single-agent-loop-kit chains Claude API skills for evals, prompt audit and hillclimbing; it is Apache 2.0 and labelled a reference implementation that is not maintained. --- I'm Joan Comadran, an AI engineer and full-stack developer in Barcelona (industrial engineering background). I write guides like this from vendor docs and shipped agent work — not from a fictional subagent migration on this site. If you want someone to draw the single-loop vs subagent line on a real product, that's what I do. --- Originally published on joancomadran.dev. I'm Joan, an AI engineer in Barcelona — work with me.
3/ The fix is progressive disclosure. The agent sees short tool/skill descriptions; full context loads only when needed. The planner and executor are the same model, so lossy hand-offs between agents disappear. Migration kit: anthropics/single-agent-loop-kit
サブエージェント、増やせば賢くなる？：公式キットで監査・比較と識者の見方 サブエージェントは、増やすほどエージェントを賢くするのか。この記事は、その考え方を揃えるための記事です。 サブエージェントは、自分のコンテキスト・ツール・指示を持つ別のエージェントです。Claude Code なら .claude/agents/ に置くあれです。 「畳む」は、担当を消さずに、その手順や道具をメインの1本へ入れることです。 進め方は2段です。まず、Anthropic の記事（2026-10-22）が挙げる「残す3つの条件」と、識者の見方を問いごとに並べます。 次に、Anthropic 公式のキット single-agent-loop-kit に付いている問い合わせ窓口（振り分け役＋6担当）で確かめます。監査スキルを当て、同じ19問を2つの版に解かせました。 結果を先に書くと、監査が「残す」と判定した担当は6つのうち1つだけでした。19問では、担当分け版だけが2問を落とし、どちらも注文と配送をまたぐ問いでした。ただし Anthropic の記事が試したサンプルでは、担当を1つ畳んだ後に、同じ注文と配送の間が壊れています。 サブエージェントを作る前にやることは1つ、3つの条件に当たるかを問うことです。この下に、監査の実際の出力、19問の内訳、頼み方、識者の原文があります。 ! この記事の内容は動画でも解説しています。担当分け版が到着日を落とした答えから、6担当の構成図の「注文と配送の継ぎ目」に赤が付くまで（7:05〜）を追えます。動画は約13分です。 問い：サブエージェントは、いつ分けるのか 「分けない」判断を正面から書いたのが、Anthropic の記事です（Diane Sarkis・2026-10-22）。 題は「Building agents: When to fold subagents into your main agent loop」。訳すと「サブエージェントを、メインのループへ畳むのはいつか」です。 記事の結びは、次の1文です。 Build a small end-to-end eval, fold in one subagent, and keep it as a subagent only if the folded version scores worse, then rinse and repeat. （小さな通しの評価を作り、1つ畳み、畳んだ版の点が下がった時だけサブエージェントとして残す。それを繰り返す） サブエージェントの作り方を広めてきた側が、残すのは点が下がった時だけ、と書いています。 起点の記事：減らすと、品質も費用も良くなることがある 記事の主張は、サブエージェントを減らし、必要なときだけ開くコンテキストとツールに寄せる、です。そうすると、品質を上げつつ費用と待ち時間を減らせることがある、と書いています。原文は "can improve quality while reducing cost and latency" です。 記事の対象は API で組むエージェントです。問いの立て方は Claude Code にも持ち込める、とこの記事では読んでいます。 背景として記事は、チームごと・問題の種類ごとにサブエージェントを作る企業が多い、と書きます。顧客事例では、1本のループのほうが実行時間が約2倍速かった例も報告しています。 では、いつ残すのか。記事の答えは3つの条件です。 記事の3つの条件。①は「重そう」では足りず、性能の落ちが測れたかどうかです どれにも当たらない担当は消しません。手順はスキル（必要なときだけ読み込む手順書）に、API を呼ぶ所はツールにして、メインの1本へ入れます。これが「畳む」です。 ツールが増えすぎる心配には、記事が答えています。定義が30〜50を超えると選び損ねが増えるので、使う人の意図ごとにまとめる、です。 分けると起きること：記事が挙げる失敗の型 記事が挙げる失敗から、3つに絞ります。 伝言ゲーム: 担当間では要約が渡るので、渡すたびに細部が落ちる（"each handoff degrading fidelity"） 組織図のコピー: チームの区切りが、そのまま担当の区切りになる（コンウェイの法則） 継ぎはぎのプロンプト: 各チームが決まりを1文ずつ足し、決まり同士がぶつかる 移し方：4つの行き先 記事の進め方は、先に小さな評価を作り、担当を1つずつ畳んで前後を比べる、です。評価は、決まった問いを解かせ、合格の条件で採点する一式です（10問から始めてよい）。 担当の行き先は4つです。 「残す」だけは3条件でなく、客と直接話すかどうかの物差しです 識者の見方：問いごとに並べる 派閥に分けると言い合いに見えるので、問いごとに並べます。 問い1：いつ分けるのが効くか 分けて勝った例はあります。Anthropic の調べ物の仕組み（2025年の報告）です。リードが並列でサブエージェントを走らせる構成が、社内の評価で単体の Claude Opus 4 を90.2%上回りました。代わりに、チャットの約15倍のトークンを使います。条件2の「並列で捨てる作業」そのものです。 Claude ブログ（Cara Phillips・2026-01-23）は、マルチエージェントが勝つ場面を3つに絞ります。コンテキストの汚れ、並列化、専門化です。その外では協調の費用が勝つのが普通で、同じ作業で3〜10倍のトークンを使う、と書いています。記事の3条件とほとんど重なります。 検証やレビューも、分けて効く所の1つです。 起点の記事が、検証を「効く所」と「分ける境界の好例」の2か所で挙げています Claude ブログも、検証役は作った経緯を知らずに外から試せる、と書いています。 ここからはこの記事の読みです。書いた本人の思い込みを持ち込まない、まっさらなコンテキストで見ること自体に価値があります。その意味で、検証やレビューは条件2の仲間に見えます。ただし同じブログは、賢いまとめ役なら別の検証役なしで見られることが増えた、とも書いています。 問い2：分けると何が壊れるか 先の調べ物の報告自身が、エージェント同士の依存が多い作業は今はマルチエージェントに向かない、と書いています。注文を調べてから配送を調べる、のように順に積み上げる作業です。 Cognition の Walden Yan は、2025-06-12 の記事でこう書いています。題は「Don't Build Multi-Agents」（マルチエージェントを作るな）です。 The decision-making ends up being too dispersed and context isn't able to be shared thoroughly enough between the agents. （判断があちこちに散らばり、エージェントの間で文脈を十分に共有できなくなる） 記事の「伝言ゲーム」と同じ所を指しています。 問い3：まずどちらから始めるか 後で使う公式キットの README は、まだサブエージェントが無いなら1本のループから始める、です。原文は "You have no subagents yet. Start with one loop."。試して要ると分かった時に、ツールとスキルを足せ、と続きます。 一方で、広く並列で調べる作業には、分けて勝った例があります（問い1）。 割れている所と、揃っている所 並べると、言い争いというより作業の形の話に見えます。広く並列で調べる作業は分けて勝った例があり、順に積み上げる作業は分けると壊れやすい。 揃っているのは、測って決める点です（この記事の整理です）。キットの README も「1本が必ず勝つとは仮定しない。測る」と書いています（"The kit does not assume a single loop always wins. It measures."）。 原文の抜粋（識者） Claude ブログ: "Outside these situations, the coordination costs typically exceed the benefits."（この場面の外では、協調の費用が利点を上回るのが普通だ） Claude ブログ: "Verification requires minimal context transfer by nature, so a verifier can blackbox-test a system without needing the full history of how it was built."（検証はもともと渡す文脈が少なくて済む。だから検証役は、作った経緯を全部知らなくても外から試せる） 公式キットで確かめる：仕分けて、比べる 材料：キットに付いている問い合わせ窓口 使ったのは Anthropic 公式の single-agent-loop-kit です（Apache-2.0・SHA c437962）。記事の付属品で、担当ごとに行き先を判定する監査のスキルが入っています。 README は自らを「参照用の実装。保守はしない」と書いています。本物のモデルで例を走らせたのは1人が1つのモデルで2回、とも書いています。 キットには、架空の家電ショップの問い合わせ窓口が例として付いています。振り分け役が1つと、担当が6つ。評価の19問と、どの担当がどの順に動いたかの記録（トレース）も同梱です。 保険の請求だけが、客と直接話す担当です 試したのは2つです。監査のスキルを Claude Code で2回走らせたこと。窓口を Claude Code の上で2つの版に組み直し、同じ19問を比べたことです。 監査の判定：6担当のうち「残す」は1つ 監査のスキルが実際に出した報告（check-in）の一部です。 1回目の監査の出力（英語のまま）。判定ごとに、根拠の数字とファイルの行が付きます 日本語にして表にすると、こうなります。 2回とも同じ判定でした。数字は、キット同梱の記録を監査が数えた値です 判定ごとの根拠は次のとおりです。 注文＋配送＝まとめる: 配送が動いた96件の記録すべてで、配送は注文の直後に動いていました。配送は、注文で見つけた追跡番号が要るからです 返品・アカウント＝畳む: 決まった手順と数本の API 呼び出しだけで、3条件のどれにも当たりません 不具合調査＝ツールとして呼ぶ: 1回に約3万1千トークン（中央値）読んで、返すのは5文。900行のログのうち、エラーの行は5行だけです。メインが読めば膨らむので、担当に読ませて結果だけ受け取る判定です。ただ、性能の落ちは測っていません。監査自身も「いちばん自信のない判定」と書き、ログを絞れる道具があれば畳むほうがよい、と添えています 保険の請求＝残す: 外部の保険会社が持つ担当で、客と何往復も話します。3条件ではなく、客と直接話すかどうかの物差しです 監査は、振り分け役のプロンプトにある決まりのぶつかりも見つけました。 届く時期と返品を同時に聞かれたら、どちらが先か決まりません。条件3の「指示の矛盾」の実例です 監査の後は必ず止まり、「Are these verdicts right?」（この判定で合ってる？）と聞いてきます。根拠の数字が出るので、人が直せます。 同じ19問で比べる：担当分け版だけが落とした2問 判定どおりに組み替えたら、本当に良くなるのか。答えを読む前に動画で見るなら、落ちた答えから継ぎ目に赤が付くまでの 7:05〜です → youtu.be 2つの版を Claude Code の上に組み直し、同じ19問を2回ずつ解かせました（Sonnet）。 版 組み方 1回目 2回目 判定どおり版 注文と配送をメインへ畳み、返品・アカウントはスキル、不具合調査と保険の請求は担当として呼ぶ 19/19 19/19 担当分け版 振り分け役＋6担当を .claude/agents/ に置く（手元のサブエージェントと同じ仕組み） 18/19 17/19 判定どおり版では、「ツールとして呼ぶ」の不具合調査を、メインが Claude Code のサブエージェントとして呼んで結果だけ受け取る形で組みました。「残す」の保険の請求は、客と直接話す代わりにメインが返事を中継する形です。 19問にはそれぞれ合格の条件があります。届く日が答えに入っているか、返品を本当に作ったか、などです。担当分け版が落としたのは次の2問でした。 1問目（t01）: 「注文5002の状況は？」 1回目は通り、2回目だけ落ちました。2回目の答えです。 Hi Ana! Order 5002 is a Vortex Blender, and it has shipped. Its tracking ID is TRK-77002. If you'd like delivery timing, I can check on that for you. （出荷済みで、追跡番号は TRK-77002。到着時期が知りたければ調べます） 正解に要る到着予定日（10月3日）が入っていません。記録に残っているのは呼んだ担当の数（この回は1つ）だけで、どの担当だったかは残っていません。注文と配送の継ぎ目で落ちたように見えますが、これは読みです。 2問目（t11）: 「5002が10月2日までに届かないなら、5001のケトルを返品したい」 2回とも落ちました。1回目の答えの抜粋です。 The blender from order 5002 will not arrive by October 2, and the kettle's return window may already be closed. … I haven't started a return, and I can't extend the window or make an exception. （ブレンダーは10月2日までに届かない。ケトルの返品期限は切れているかも。返品はまだ始めていない） 正解は、返品を作ることです。担当分け版は2回とも返品を作りませんでした。監査が「t11 がぶつかりに当たる」と指摘していた問いです。ただ、ぶつかりのせいだとまでは言えません。言えるのは、監査が指摘した問いで、2回とも返品を作らなかった、までです。 畳む途中でも壊れる：Anthropic の記事のサンプルでは では、1本にまとめれば壊れないのか。Anthropic の記事自身が、逆の例を書いています。記事の筆者たちがサンプルの窓口で試したとき、担当を1つ別の担当へ畳むと、待ち時間は下がりました。ただ、それまで通っていた処理が壊れました。 注文の検索はメインへ移り、配送はまだ別の担当でした。継ぎ目の位置が動いても、注文と配送の間は壊れえます 上の判定どおり版は、注文と配送を両方メインへ入れて、この継ぎ目ごと無くした形です。記事は、組み替えの前に、本番で続けて動く担当の連なりごとに問いを評価へ入れておけ、とも書いています。 そしてこの壊れ方は、2回に1回しか出ませんでした。上の t01 も、1回目は通っています。記事が「各問を2回以上走らせる」と書く理由が、そのまま出ています。 識者の問いに戻すと 落ちた2問は、どちらも注文と配送をまたぐ問いでした。問い2の「依存の多い作業は分けに向かない」が指す形です。 一方、Anthropic の記事のサンプルでは、1つ畳んだ後にも同じ間が壊れました。分けるか1本かより先に、継ぎ目の場所を知り、そこを評価で2回以上見る。この例から言えるのはそこまでです。 考え方を自分のエージェントへ：作る前の3つの問い 新しくサブエージェントを作る前に、次の3つを問います。 1本だとコンテキストが膨らんで、性能が落ちたと測れたか（「重そう」は数えない） 並列で動かして、終われば捨てる作業か（広く調べる・まっさらな目で検証する、など） 1本では、ツール選びや指示の矛盾が解けないか どれにも当たらなければ、スキルとツールにしてメインに入れます。客と直接話す担当だけは、会話ごと渡して残します。 すでに分けているなら、いつも続けて動く2担当を探します。そこが継ぎ目です。その継ぎ目をまたぐ問いを評価に入れ、2回以上走らせます。 手元で試す キットの監査を自分のリポに当てる README の手順は、キットを取ってきてスキルを置き、1文で頼むだけです。.claude/skills/ がまだ無いリポでは cp が止まるので、先に作っておきます（mkdir -p の行は README にはありません）。 git clone anthropics/single-agent-loop-kit mkdir -p <your repo>/.claude/skills cp -r single-agent-loop-kit/skill <your repo>/.claude/skills/single-agent-loop <your repo> は、自分のエージェントのリポのパスに置き換えます。 あとは、そのリポで Claude Code を開き、こう頼みます。 Run the single-agent-loop skill. README によると、スキルは監査の後、お金のかかる実行の前、基準を取った後、変更のたびに止まります。 キットは無料です。監査はコードを読むだけで、Claude Code の1セッション分です。評価を回すとモデルの料金がかかるので、回す前に毎回トークンの見積もりを出します（README の Cost の節）。 評価が無くても、約10問を一緒に下書きしてくれます。自分で用意するのは、本番の外で試しに動かす方法と、完了の条件を言える人です。 キットの例で、API キー無しの無料チェックもできます。要るのは Python 3.10 以上だけで、ほかに入れる物はありません（キットの RUNBOOK より）。 cd single-agent-loop-kit/examples/support-desk KIT_MODEL=fake python3 evals/run_eval.py --variant smoke 問いごとに1行ずつ19行流れ、最後の行がこうなれば通っています。代役のモデルなので点は付きません。 最後の2行（Python 3.14.4・2026-10-26） smoke: 19 tasks ran on the offline stand-in model, 0 harness errors. The plumbing works. The stand-in follows keyword rules, so nothing here is scored. Set KIT_MODEL to a real model id for scores. Results in … 監査を試した環境と頼み方 項目 内容 キット anthropics/single-agent-loop-kit・SHA c437962（2026-10-21 のコミット）・★211（2026-10-26 時点） 対象 キット付属の examples/support-desk（答え合わせのファイルと1本版の見本は外した） 環境 Claude Code 2.1.310 の非対話モード（claude -p）・Claude Opus 5.5・Python 3.14.4 回数 2回（1回あたり2分ほど）。2回とも同じ判定 試した日 2026-10-26 監査だけで止めるため、1文の代わりに次の文で頼みました。1文だけで頼んだときに同じ文面の報告が出るかは確かめていません。 Use the single-agent-loop skill in .claude/skills/single-agent-loop on this repo. The system to migrate is in app/. Traces are in traces/traces.jsonl. Stop at every check-in the skill describes. Run step 0, the audit, and check in with the verdicts. Do not run any eval (no paid or offline eval runs, no run_eval.py) and do not proceed past the audit check-in. Print the full check-in as your final answer. 19問の比較の組み方 キット本来の比べ方は、SDK で組んだ版を evals/run_eval.py で採点する形です（examples/support-desk/RUNBOOK.md）。上の数字はこの道では出していません。代わりに、窓口を Claude Code の上に組み替えました。 項目 担当分け版 判定どおり版 メイン 振り分け役（自分では答えない） 窓口役（注文と配送は自分で答える） 担当 .claude/agents/ に6担当 .claude/agents/ に不具合調査・保険の請求、.claude/skills/ に返品・アカウント 両版共通: キットの API は Bash から呼ぶコマンドに置き換えた。保険の請求は両版とも中継の形 環境: Claude Code 2.1.310 の非対話モード・Sonnet 5.5・2026-10-26〜27 採点: キットの19問の合格条件と採点処理をそのまま使った。1問ごとに新しいセッション この記事で言えないこと 比較は、キットの例1つを Claude Code の上に組み替えた小さな実験です（19問×2回）。キット本来の SDK 版の評価とは違います。「1本のほうが必ず強い」とは言えません 判定どおり版は、組み替えでプロンプトも書き直しています。振り分け役の決まりのぶつかりも残っていません。差が担当の数だけから来たとは言えません 担当分け版の不具合調査の3問は、比べるために組んだ仕掛けの側で長いログを読めない問題が出ました。読み方を直して解き直し、上の 18/19・17/19 はこの解き直しを含んだ値です。この3問は構成の差の根拠にしていません 使用量と速さは比べていません。Claude Code そのものが毎回読む分が大きく、版の差が見えないためです 監査の判定は、正解と照らしてはいません .claude/agents/ だけのリポにキットを当てる試しはしていません まとめ Anthropic の記事は、1つずつ畳み、点が下がった時だけ残せと書きました。残す条件は3つ（測れた膨らみ・並列で捨てる作業・解けない矛盾）です 識者の見方は、作業の形で分かれます。測って決める点は揃っています 公式キットの窓口では、「残す」は6担当中1つでした。19問では担当分け版だけが、注文と配送をまたぐ2問を落としました。Anthropic の記事のサンプルでは、1つ畳んだ後にも同じ間が壊れています この比較が引いた線は、継ぎ目をまたぐ問いを評価に入れ、2回以上走らせる、でした。どこで分けるかを決めるのは作る人です。あなたなら、どこで分けますか 動画で見たい方はこちら（落ちた答えから継ぎ目に赤が付くまで・7:05〜）→ youtu.be 再生リスト「Claude の記事を読む」の1本目です: youtube.com 参考リンク Diane Sarkis「Building agents: When to fold subagents into your main agent loop」（Anthropic・2026-10-22）: claude.com 同・日本語版: claude.com anthropics/single-agent-loop-kit（Apache-2.0）: anthropics/single-agent-loop-kit 同・examples/support-desk の RUNBOOK（キット本来の比べ方）: github.com/anthropics/single-agent-loop-kit/blob/… Anthropic「How we built our multi-agent research system」（2025-06-13）: anthropic.com Cara Phillips「Building multi-agent systems: When and how to use them」（Claude ブログ・2026-01-23）: claude.com Walden Yan「Don't Build Multi-Agents」（Cognition・2025-06-12）: cognition.com
guide: claude.com reference kit: anthropics/single-agent-loop-kit
Free migration kit: anthropics/single-agent-loop-kit
anthropic's guide on folding subagents into one loop: claude.com migration kit (measure, combine, fold): anthropics/single-agent-loop-kit
Anthropic のエージェント設計ガイド サブエージェントをメインのループに取り込む グラレコ !サブエージェントをメインのエージェントループに取り込む話の要点をまとめたグラレコ 上のグラレコは、この記事で扱う Anthropic の記事の要点を1枚にまとめたものです。サブエージェントが今も役に立つ場面、組織図のコピーになる問題、大きな組織で起きやすい失敗、必要なときだけ読み込む設計、1つのループの動き方、分けるなら何で分けるか、1体ずつ取り込む手順、チームごとの持ち物までを8つのブロックに並べています。下の帯は移行の流れです。細かい話は本文で1つずつ見ていくので、まずは全体の地図として眺めてみてください 🗺️ はじめに Anthropic は 2026年10月22日、Claude の公式サイトのリソースに「Building agents: When to fold subagents into your main agent loop」という記事を公開しました。著者は Diane Sarkis 氏で、カテゴリーは「Best practices」「Perspectives」、対象の製品は Claude Platform です。 この記事のテーマは、複数のサブエージェントで組んだエージェントを、どういうときに「1つのメインループ＋スキル＋ツール」の形に寄せるべきかです。Anthropic の Applied AI チームが企業のエージェント導入を支援する中で、ルーター（振り分け役）、プランナー（計画役）、領域ごとのサブエージェントをメインのループに取り込むことで良くなったケースが続いた、というのが記事の出発点になっています。 記事の主張を一言でまとめると、次のようになります。 > サブエージェントを減らし、そのぶんコンテキストとツールを必要になったときに段階的に読み込むようにすると、品質を上げつつ、コストと遅延を下げられることがある。 ただし、記事は「サブエージェントは不要になった」とは言っていません。今でも使うべき場面をはっきり挙げたうえで、「組織図をそのままエージェント構成にしてしまう」ことへの注意を促す内容です。あわせて、移行を手伝う single-agent-loop-kit（移行キット）も GitHub で公開されています。 この記事では、元記事の内容を日本語で整理し、移行キットの中身も補足しながら紹介します。 この記事でわかること 📌 - サブエージェントが今でも役に立つ3つの場面と、そうでない場面 - 大きな組織でエージェントを作るときに起きやすい5つの失敗 - 「必要なときに読み込む」設計が効く3つの理由 - 目指すべき「1つのエージェントループ」の動き方と、コンテキストの置き場所 - サブエージェントを段階的に減らす3つの方法と、評価の作り方 - 複数のチームが1つのエージェントに関わり続けるための役割分担 - 移行を手伝う Claude Code のコマンドと、移行キットの使い方 想定読者は、Claude Platform（Claude API）や Claude Agent SDK などで、複数のサブエージェントを組み合わせたエージェントを作っている、または設計を検討している開発者の方です。 サブエージェントとは、そして今でも使うべき場面 🤝 サブエージェントのおさらい 元記事では、サブエージェントを「独自のコンテキストウィンドウ・ツール・指示を持ち、取りまとめ役（コーディネーター）によって指揮されるエージェント」と定義しています。エージェント設計の中心的な部品で、元記事によると、次のような用途で効果を発揮します。 - 検証（別の目で結果を確かめる） - 並列作業（複数の調べものを同時に進める） - 権限の分離（部品ごとに使えるツールを分ける） Anthropic 自身も、Claude Platform で作る多くのエージェントでサブエージェントを使っていて、例としてマルチエージェントのリサーチシステムが挙げられています。 それでも「取り込んだ方が良かった」ケースが増えている 一方で、企業向けのエージェントでは、ルーター・プランナー・領域ごとのサブエージェントをメインのループに取り込んだ方が良くなるパターンが見えてきた、と元記事は書いています。複数の企業導入での比較では、スキルを持つ単一のエージェントが、「1つのプロンプトに何でも詰め込む設計」と「サブエージェント設計」の両方を品質で上回ることが多く、タスクあたりのコストと遅延も低いことが多かったそうです。 具体例として挙げられているのは、ある企業の顧客向けエージェントです。中に十数個の専門サブエージェントがあり、そのせいでブランドに沿った一貫した体験を保つのが難しく、遅延も増えてユーザー体験を損ねていました。 よく見かける「5層構造」 元記事には、提案されるエージェント設計によく見られる「お決まりの流れ」も紹介されています。次の図は、元記事の図をもとに、その構造を書き起こしたものです。 graph TD R["リクエスト"] --> O["マルチエージェントの司令塔"] O --> IC["意図の分類"] IC --> P["固定の多段推論パイプライン<br>ステップ1 → 2 → 3 → 4 → 5"] P --> U1["ユーザー区分 A"] P --> U2["ユーザー区分 B"] P --> U3["ユーザー区分 C"] U1 --> B1["推薦の分岐 A"] U2 --> B2["推薦の分岐 B"] U3 --> B3["推薦の分岐 C"] B1 --> ANS["回答"] B2 --> ANS B3 --> ANS 意図の分類器、固定の多段推論パイプライン、ユーザー区分ごとの振り分け、推薦の分岐、そして一番上にマルチエージェントの司令塔という、モデルの周りに5層の構造を積み上げた形です。 こうした設計に対して寄せられるフィードバックは、「この構造の大半は、もうモデルが手伝ってもらう必要のない仕事をしていた」というものが多いそうです。代わりに勧められているのが、次のシンプルな形です。 graph TD R["リクエスト"] --> M["モデル"] SP["明確なシステムプロンプト 1つ"] --> M M -->|"ツール呼び出し"| T["薄いデータツール 4〜5個"] T -->|"結果"| M M --> G["確かな出力ガードレール"] G --> ANS["回答"] style M fill:#ffe0b2,stroke:#e65100,stroke-width:2px 2つの図を見比べると、層の数がまったく違います。筆者の見方では、上の5層構造は分類や分岐をあらかじめ構造として決めていて、下の1ループはその判断をモデルに任せている、という違いです。元記事は「明確なシステムプロンプト1つ、薄いデータツール4〜5個、確かな出力ガードレールで、ユースケースの大半をカバーできる」とまとめています。 サブエージェントを使うべき3つの場面 誤解のないように、元記事はサブエージェントが今でも必要な場面を明記しています。研究の最前線でも、サブエージェントはまだ居場所がある、と書かれています。 | 場面 | 具体的には | | --- | --- | | コンテキストの肥大化 | 1つのエージェントループで、コンテキストが膨らみすぎて測定できるほどの性能低下が起きている | | 新しいコンテキストでの並列作業 | 複数のタスクを並列に進める必要があり、それぞれ新しいコンテキストで取り組み、終わったら捨ててよい | | ツール選択の難しさ・指示の衝突 | 1つのエージェントが適切なツールを選べない、またはシステムプロンプトの中に矛盾する指示がある | どれも「実際に問題や必要性が見えている」ことが前提になっている点がポイントです。特に1つ目は「測定できるほどの」と明記されています。「なんとなく分けた方がきれいそう」は、この3つのどれにも当てはまりません 🙂 組織図のコピーになっていないか 元記事がもう1つ指摘しているのが、エージェント構成が組織図のコピーになってしまう問題です。 > 企業がチームや問題の種類ごとに専用のサブエージェントを持たせ、エージェントのアーキテクチャが組織図のコピーになっている例を、あまりにも頻繁に目にします（コンウェイの法則が働いている状態です）。 コンウェイの法則は、「システムの構造は、それを作った組織のコミュニケーション構造に似る」という経験則です。チームごとにサブエージェントを作ると、技術的な理由ではなく組織上の理由で境界が引かれてしまいます。 大きな組織で起きやすい5つの失敗 ⚠️ 元記事は、大きな組織がエージェントを作るときによく起きる流れを、次のように説明しています。 1. 会社としては、複数の製品や機能を1つの顧客向け窓口にまとめたい 2. それぞれの機能は別々のチームが持っているので、まず各チームに自分たちのエージェントを作ってもらう 3. その上に、中央のプラットフォームチームが司令塔を作る（司令塔＋サブエージェント型、または各エージェントを MCP ツールとして公開する型） graph TD C["顧客向けの1つの窓口"] --> ORC["中央チームの司令塔"] ORC --> A1["チームA の<br>エージェント"] ORC --> A2["チームB の<br>エージェント"] ORC --> A3["チームC の<br>エージェント"] ORC --> A4["チームD の<br>エージェント"] A1 -.-> X["チームごとに<br>プロンプト・評価・担当者がバラバラ"] A2 -.-> X A3 -.-> X A4 -.-> X style X fill:#ffcdd2,stroke:#c62828 一見すると一番シンプルな解決策に見えますが、元記事によると、すぐに次の5つの複雑さが生まれます。 | 失敗 | 何が起きるか | | --- | --- | | コンテキスト管理 | エージェント間でどのコンテキストをやり取りするかを決める必要があり、やり取りの中で細部が抜け落ちやすい | | サブエージェントの乱立 | 各チームが自分のサブエージェントを出すので、重複した数百のサブエージェントが、統一された基準も特定の担当者もないまま並ぶ | | つぎはぎプロンプト（元記事では "The Frankenprompt"） | 各チームがシステムプロンプトに1文ずつ足していくので、ルールが矛盾し、口調もそろわなくなる | | 審査されない、局所的すぎる評価 | 各チームが自分のサブタスクに最適化しすぎた評価を足す。全体を持つ人も保守する人もおらず、経営層は薄められた局所的なスコアをもとに判断することになる | | 遅延 | マルチエージェント構成の複雑さが遅延を増やす。ある顧客では、マルチエージェント構成と単一のエージェントループを比べたところ、後者の方がおよそ2倍速く動いた | この中で、地味に効いてくるのが「つぎはぎプロンプト」と「局所的な評価」だと思います。どちらも1つひとつは善意の追加なのに、積み重なると「誰も全体を説明できない」状態になってしまいます（チームが多い組織ほど、これは起きやすいはずです）。 「必要なときに読み込む」エージェントループ 📚 段階的な開示とは ここまで見てきた司令塔＋サブエージェント型は、チームをまたいで作られた専門家をまとめる方法としては妥当です。ただ元記事は、多くの場合それより効果的になりうる方法として、次の2つを挙げています。 - スキルでコンテキストを段階的に開示する - ツール検索でツールを段階的に開示する 言い換えると、エージェントにはまずスキルとツールの短い説明文だけを見せておき、本文やツールの定義は必要になったときだけ読み込ませる、という設計です。次の図は、返品の問い合わせを例にした筆者による例です（元記事にはない例です）。 sequenceDiagram participant U as ユーザー participant M as メインのエージェント participant S as スキル置き場 participant T as ツール検索 Note over M: システムプロンプトには<br>スキルとツールの短い説明だけ U->>M: 返品したいのですが… M->>S: 「返品」スキルの本文を読み込む S-->>M: 返品の手順・ルール・判断基準 M->>T: 返品に使うツールを探す T-->>M: 注文検索・返品可否チェック・返品作成の定義 M->>U: 手順に沿って回答・処理 この図のポイントは、返品と関係のない領域のスキルやツールは、最後まで一度も読み込まれないことです。システムプロンプトを短く保ったまま、エージェントが扱える領域を広げられます。 この設計が理にかなう3つの理由 元記事は、この方法が理にかなっている理由を3つ挙げています。 ① 共有されたコンテキストが、より良い答えを生む 🧠 長く動くエージェントでは、いくつものタスクのコンテキストがメインのコンテキストウィンドウに載っていてほしい、と元記事は書いています。それまでの各ステップの結果を見てきたエージェントは、それらを結びつけられます。サブエージェントから返ってくる要約の寄せ集めより、豊かな出力と良い洞察につながります。コンテキストウィンドウの数が減り、情報が抜け落ちる引き継ぎも減ります。 ② 段階的な開示が、コンテキストの肥大化を防ぐ 📉 段階的な開示を使えば、すべてのコンテキストを1つの長いシステムプロンプトに最初から詰め込まなくても、幅広いタスクをこなす単一のエージェントを作れます。元記事は「これで、チームがこれまで仕事をサブエージェントに分けていた一番の理由がなくなる」と書いています。実際、Anthropic は、より高性能なモデル向けの Claude Code のシステムプロンプトを 80% 以上削減していて、その中にはスキルとツールの段階的な開示に関係する削減も含まれていたそうです。 ③ モデルの能力が上がっている 🚀 元記事によると、Opus 4.5 以降、モデルはほとんどのチームが予想していたよりもはるかに多くのことを1つのループで管理できるようになりました。Opus 5.5 と Fable 5.1 では思考（thinking）をオフにできず、最近のモデルはますます、作業しながら進捗を説明し、自分の仕事を確かめるようになっているため、ハーネス（モデルを動かす周辺のコード）の一部の要素は不要になっています。 新しいモデルが出るたびに、判断をハーネスからモデル自身に移せる範囲が広がります。さらに、シンプルなループは次のモデルへの移行も楽です。元記事には「私たちが手伝った移行では、硬直したマルチエージェント構造こそが、新しいモデルにもっと仕事を任せる妨げになっていたことが多かった」と書かれています。 単一ループには規律が要る ただし、単一ループは「何でも1つに詰め込めばよい」という話ではありません。元記事は、次のような規律が必要だと書いています。 - 丁寧に管理されたシステムプロンプト - 適切なタイミングで呼び出されるスキルとツールの説明文 - コンテキストウィンドウ、記憶、メモ取りの意図的な扱い そして、1つの中央チームが、エンドツーエンドの品質とシステムプロンプトを持つべきだとしています。中央チームは、新しいツールや評価をリリース前にすべて審査します。このチームを小さく保つことで、改善のサイクルを速く回せ、大きな組織での調整コストも下げられるそうです。 分けるなら「問題の種類」ではなく「コンテキスト」で ✂️ それでもマルチエージェントにする場合について、元記事は2つのアドバイスをしています。 1. うまくいきそうな一番シンプルなパターンから始める（生成役＋検証役、司令塔＋サブエージェントなど） 2. 境界は「コンテキスト」で分ける。各サブエージェントには、システムの他の部分からほとんど何も必要としない仕事を渡し、コンパクトな結果を返してもらう 良い候補として挙げられているのは、独立した調査の筋、きれいなインターフェースで分かれた別々のコンポーネント、中身を知らなくてよい検証（ブラックボックス検証）です。 逆に、問題の種類で分けると「伝言ゲーム」になる、と元記事は警告しています。引き継ぐたびに情報の正確さが落ちていくからです。元記事の図にある例を、Mermaid で描き直すと次のようになります。まずは問題の種類で分けた場合です。 graph LR A1["エージェント1<br>機能を書く"] -->|"引き継ぎ"| A2["エージェント2<br>テストを書く"] A2 -->|"引き継ぎ"| A3["エージェント3<br>コードをレビュー"] style A2 fill:#ffcdd2,stroke:#c62828 引き継ぐたびにコンテキストが失われ、テストを書くエージェントは、なぜその実装にしたのかを知りません。次に、コンテキストで分けた場合です。 graph LR ONE["1つのエージェント<br>機能とテストを書く<br>（コンテキストを持っているから）"] --> V["検証役<br>テストを実行する"] style ONE fill:#ffe0b2,stroke:#e65100,stroke-width:2px テストを実行して結果を報告するだけの検証役なら、実装のコンテキストは要りません。ここで分けても、伝言ゲームにはならないわけです。 「誰が担当しているか」ではなく「その仕事に、どこまでのコンテキストが必要か」で境界を引く、という考え方は、エージェント以外の設計にもそのまま使える話だと思います。 目指すべき「1つのエージェントループ」の設計 🔁 ループの動き方 多くのチームは、すでに司令塔と専門エージェントの組み合わせを本番で動かしています。元記事は、そこから目指していく単一ループの設計を、次のように説明しています。 - 1つのモデルと1つのコンテキストウィンドウで、終わりの決まっていないツールループを回す。上限（ターン数とコストの予算、書き込み前の承認ゲート）はハーネス側で設定する - 毎ターン、モデルはツール呼び出しをまとめて出す。ハーネスはそれらを並列に実行し、生の結果を同じモデルに返す。モデルは次の一手（次のまとまり、ユーザーへの質問、または回答）を決める - ループは、モデルが回答するか、予算に達したら止まる。回答の後に、任意でゴールや検証役のチェックを走らせられる - モデルは最初のターンに計画をコンテキストに書き、結果が届くたびに改訂する flowchart TD START["ユーザーの依頼"] --> PLAN["モデルが計画を<br>コンテキストに書く"] PLAN --> BATCH["ツール呼び出しを<br>まとめて出す"] BATCH --> RUN["ハーネスが並列に実行<br>（書き込みは承認ゲートを通す）"] RUN --> RES["生の結果を<br>同じモデルに返す"] RES --> DEC{"モデルが次を決める"} DEC -->|"もっと調べる"| REV["計画を改訂"] REV --> BATCH DEC -->|"確認が必要"| ASK["ユーザーに質問"] DEC -->|"答えられる"| ANS["回答"] RES --> BUD{"予算に達した？"} BUD -->|"はい"| STOP["停止"] ANS --> VER["（任意）ゴール・検証役のチェック"] 元記事は、司令塔＋専門エージェント型からの一番大きな変化は最後の点だと書いています。計画を書くモデルと、それを実行するモデルが同じなので、ターンの途中でも計画を変えられるのです。逆に言えば、司令塔が計画を立てて専門家が実行する構成では、実行中にわかったことを計画に反映するのに、引き継ぎの往復が必要になる、ということです（この1文は筆者の補足です）。 移行キットに含まれる参照実装（reference_loop/loop.py）は、このループを読みやすく書いたものです。コードの Budget クラスにある既定の予算は、次のようになっています。 @dataclass class Budget: max_turns: int = 25 max_tokens: int = 400_000 # input plus output, summed over one call to run(), subagents included max_batch: int = 16 # tool calls run from one model turn; the rest get an error result ターン数、トークン数（サブエージェントが使った分も含む）、1ターンで実行するツール呼び出しの数に上限を設けています。上限はハーネス側で設定する、という元記事の考え方が、そのままコードになっています（loop.py の冒頭には「上限はプロンプトではなくハーネスに置く」とあります）。参照実装は「フレームワークではなく参照用。自分のハーネスに足りない部分をコピーして使ってほしい」と位置づけられています。 コンテキストはどこに置くか 単一ループでも、コンテキストはもちろん読み込まれます。違うのは、それをエージェント自身が管理することです。元記事が示す置き場所を表にまとめると、次のようになります。右端の列は、1行目を除いて筆者の補足です（元記事が理由を書いているのは1行目だけです）。 | 何を | どこに置くか | 補足（1行目のみ元記事） | | --- | --- | --- | | ルールのカタログから計画を書き換えるコード | 不要になる | 各ステップをモデルが決めるから | | 手順の順序や、その領域のやり方 | スキル | 必要なときに読み込めばよい | | ハードな制限（検証、承認ゲート） | ツール | ツールの中なら確実に守らせられる | | 会話の途中で必要になるもの（記憶の参照など） | ツール | 必要になったときにモデルが呼べる | | 安くて、ほぼ常に関係するもの（例：エンティティの特定。顧客や商品が誰・何なのかを確定する処理） | コード | ほぼ毎回必要なら、コードで用意した方が安い | | 機械的な処理（ペイロードの組み立て、ストリームの解析、確認の質問からの再開） | コード（ループが呼ぶツールの中） | 判断が要らない部分はコードの方が確実 | 筆者なりにまとめると、判断が要るものはモデルとスキルへ、確実に守らせたいものはツールへ、判断の要らない機械的なものはコードへ、という分け方です。 元記事は、この単一ループの設計が、多くのチームが目指している最終形、つまりユーザーの大きな目標を理解して、代わりに行動してくれるエージェントにもつながると書いています。エージェントが学んだことを、すべて1つのコンテキストにとどめておけるからです。 移行の第一歩：タスク完了の評価を作る 🎯 ここからは、マルチエージェント構成から単一ループへ、段階的に移っていく方法です。最初の一歩は、評価セットを作ることです。 評価の持ち方 元記事でうまくいったとされている評価の構造は、次の2層です。 graph TD CT["中央チーム"] --> E2E["共有のエンドツーエンド評価セット<br>（全体の品質を見る）"] T1["チームA"] --> S1["スキルA と一緒に出す<br>小さな評価セット"] T2["チームB"] --> S2["スキルB と一緒に出す<br>小さな評価セット"] T3["チームC"] --> S3["スキルC と一緒に出す<br>小さな評価セット"] E2E --> J["取り込むかどうかの判断"] S1 --> J S2 --> J S3 --> J 中央チームが持つ共有のエンドツーエンド評価セットと、各チームが自分のスキルと一緒に出す小さな評価セットの組み合わせです。元記事は「正解付きの例が10件あれば、始めるには十分」と書いています。最初から完璧な評価を作ろうとしなくてよい、というのは心強い話です。 何を測るか 測る対象は、移行の段階によって変わります。 | 段階 | 測るもの | | --- | --- | | 最初の出発点 | エージェントの最終メッセージを、採点基準に沿って採点する | | 司令塔が残っている間 | （最終メッセージの採点に加えて）振り分けの正確さ（正しいサブエージェントを選んだか） | | サブエージェントを取り込んだ後 | 振り分けの代わりに、正しいスキルを読み込んだか、正しいツールを呼んだか | | 長期的に目指すもの | タスク完了の評価（アーキテクチャを比べるときに一番大事） | 社内のシステムを再現しにくい環境や、ユーザーとのやり取りをシミュレーションしにくい環境では、評価を作るのは簡単ではありません。元記事では、Anthropic 社内でうまくいった方法として、重要なイベントにタイムスタンプを記録しておき、後で再生して狙いを絞った評価として使う方法が紹介されています。 サブエージェントを減らす3つの方法 🧩 単一ループに近づくには、サブエージェントをツールやスキルに取り込んでいきます。元記事が挙げる方法は3つです。元記事の図をもとに整理すると、次のようになります。 graph TD START["今のサブエージェント"] --> M1["① 統合する<br>コンテキストを共有するものを<br>まとめて数を減らす"] START --> M2["② ツールとして呼ぶ<br>メインのエージェントが呼び出し<br>会話は手放さない"] START --> M3["③ スキルとツールに取り込む<br>プロンプトはスキルに<br>API 呼び出しはツールに"] style M3 fill:#ffe0b2,stroke:#e65100,stroke-width:2px ① 領域ごとのエージェントを統合する 最初の統合の前に、小さなエンドツーエンド評価を作っておきます。そのうえで、コンテキストを共有しているものから、利用の多いサブエージェントを優先してまとめていきます。 統合の候補になるのは、次のような専門エージェントです。 - お互いの出力を連鎖して使っている - 同じデータを触っている - 一緒に呼ばれることが多い 元記事の例では、本番のトラフィックのかなりの割合が「ある専門家の後に、別の専門家」という流れになっているなら、その2つは強く結びついたペアで、1つの領域エージェントにまとめる候補になる、とされています。 ② サブエージェントをツールとして呼ぶ 先ほどの「サブエージェントを使うべき3つの場面」のどれかに当てはまり、サブエージェントを残す場合は、メインのエージェントがサブエージェントをツールとして呼ぶ形にすると効果的な場合があります。こうすると、メインのエージェントがユーザーとの会話を持ち続けられます。 元記事は、サブエージェントが会話を丸ごと引き継ぐ完全な引き継ぎを勧めるのは、そのサブエージェントがユーザーと直接話す必要があるときだけだとしています。それ以外は、メインループのスキル＋ツールにできるからです。 ツールとして呼ぶ形には、次のような利点があります。 - サブエージェントの共通の応答スキーマを定義できる - 結論を、メインのエージェントが実データと照らし合わせて確かめられる - 最後のまとめのステップへの入力を絞れる - サブエージェントを書き直す必要がないので、最初の一歩として取り組みやすい - 取り込むかどうかを決める前に、タスク完了評価の基準値が取れる 一方で、次の失敗はまだ残ります。 - 専門家ごとに、プロンプト・コンテキスト・担当チーム・評価がバラバラなまま - 呼び出すたびに、情報が抜け落ちた要約が返ってくる - 呼び出しのたびにモデルのループが入れ子になり、遅延が増える ③ スキルとツールに取り込む 最後が本命の方法です。サブエージェントを1体ずつメインのエージェントに取り込みます。 - 各サブエージェントのプロンプトはスキルにする - 各サブエージェントの API 呼び出しは MCP ツールにする - そのサブエージェントがある場合とない場合で、評価の成績を比べる - どちらを残すかを決める flowchart TD E["小さなエンドツーエンド評価を作る"] --> F["サブエージェントを1体だけ<br>スキル＋ツールに取り込む"] F --> C["取り込む前と後で<br>評価を比べる"] C --> Q{"取り込んだ版の<br>成績が悪い？"} Q -->|"いいえ"| K1["取り込んだ版を残す"] Q -->|"はい"| K2["サブエージェントとして残す"] K1 --> N["次の1体へ"] K2 --> N N --> F 元記事の結びにある「小さなエンドツーエンド評価を作り、サブエージェントを1体取り込み、取り込んだ版の成績が悪い場合だけサブエージェントとして残す。それを繰り返す」という手順を、そのまま図にしたものです。 比べるときの落とし穴：最終スコアだけを見ない 比べるときに大事なのは、最終スコアだけを見ず、どのタスクの結果がひっくり返ったかを見ることです。元記事には、サンプルのサポートエージェントで試したときの例が載っています。 > 1つのサブエージェントを別のサブエージェントに取り込んだところ、遅延は下がりましたが、それまで通っていた処理が壊れました。メインのエージェントが注文検索ツールを持っていて、配送の専門家に配達日を聞かずに、自分で答えてしまったのです。 平均スコアだけを見ていると、こうした「1つの処理が静かに壊れる」ことを見落としかねません。そこで元記事は、変更の前に次の2点を確認するよう勧めています。 - 評価に、本番で一緒に動くエージェントの連鎖ごとのタスクと、エージェントが破ってはいけないルールごとのタスクがあること - 各タスクを複数回実行すること（この例の壊れ方は、2回に1回しか現れなかったそうです） LLM の出力には揺らぎがあるので、1回の実行で「大丈夫だった」と判断するのは危ない、ということです。この話は、エージェントの評価全般に通じる大事な注意だと思います 🔍 複数のチームが1つのエージェントに関わり続ける方法 👥 単一ループにすると、「各チームの居場所がなくなるのでは」と心配になるかもしれません。元記事の答えは、各チームの持ち物を「エージェント」から「スキルとツール」に移すというものです。 領域ごとの知識や判断は、ナレッジベース、スキル、MCP ツールから取り出せます。各チームはスキルとツールを持ち、1つの小さな中央チームがシステムプロンプトとエンドツーエンドの品質を持ちます。中央チームは、新しいスキル・ツール・評価をリリース前に審査します。 graph TD CT["小さな中央チーム"] --> SYS["システムプロンプト"] CT --> Q["エンドツーエンドの品質<br>（新しいスキル・ツール・評価を審査）"] TA["領域チーム"] --> SK["スキル<br>（仕事のやり方）"] TA --> TL["MCP ツール<br>（アクション・ライブデータ）"] TA --> EV["スキルごとの評価"] SK --> AG["1つのエージェントループ"] TL --> AG KB["ナレッジベース<br>（ときどき必要な参照資料）"] --> AG SYS --> AG 3つの部品の使い分け 元記事では、領域の知識や判断を取り出す先として、3つの部品を挙げています。各チームの持ち物として元記事が明示しているのは、このうちスキルとツールです。 | 部品 | 向いているもの | 設計のポイント | | --- | --- | --- | | MCP ツール 🔧 | アクションを起こす、システムからライブデータを読む、決まった形の結果を返す | ユーザーの意図ごとにまとめる（API ごとに1つではない）。ツール検索で遅延読み込みする。前提条件と権限チェックはツールの中で行う | | スキル 📘 | チームの仕事のやり方（以前は専門サブエージェントのプロンプトに入っていた手順・ルール・判断） | チームごとの担当責任者（DRI）が持つ。よく作られていて、他と重ならず、適切な評価と一緒に出す | | ナレッジベース 📚 | エージェントがときどきしか必要としない参照資料（ポリシー、指標の定義、製品仕様） | モデルが呼ぶ検索ツールの裏に置くか、スキルの中に参照ファイルとして入れる。コードで取ってきてプロンプトに貼るのは避ける | MCP ツールの設計で気をつけること ツールについては、元記事に具体的な数字があります。 > システムプロンプトのツール定義が 30〜50 個を超えると、ツールの選択がうまくいかなくなる傾向があります。 そのため、API ごとに1つのツールを作るのではなく、ユーザーの意図ごとにまとめることが勧められています。あわせて、ツール検索を使った遅延読み込みも推奨されています。ツールは、移行中にサブエージェントを呼び続けるための手段としても使えます。 前提条件の扱い方も参考になります。元記事の例では、「Y の処理に X の出力が必要」という場合、Y のツールが X の出力の有無をチェックし、なければモデルが次にどう動けばよいかわかる指示を返します。ハードな前提条件はできるだけ減らし、残る前提条件はツールの中に入れる、という方針です。 ユーザーごとの権限も同じ考え方で扱えます。 sequenceDiagram participant M as エージェントループ participant T as ツール M->>T: 注文の詳細を取得（呼び出したユーザーの情報つき） T->>T: このユーザーが見てよいかを確認 alt 権限あり T-->>M: 注文の詳細 else 権限なし T-->>M: 「このユーザーはこの注文を閲覧できません」 Note over M: モデルが読める平易な拒否を受けて<br>ユーザーに説明する end 各ツールが、呼び出したユーザーに何が見えて何ができるかを確認し、モデルが読める平易な拒否を返します。こうすると、権限レベルごとに別のエージェントを用意しなくても、1つのループで権限の違うユーザーに対応できます。 スキルの増えすぎを防ぐ スキルについて、元記事は「スキルの保守は、スキルを書く人たちに返す」という方針を取っています。重い作業は、ほかのスキルを作成・テスト・整理するスキルを使って Claude に任せられます。 スキルの乱立を防ぐには、チームごとの担当責任者（DRI）が自分たちのスキルを持ち、よく作られていて、他と重ならず、適切な評価と一緒に出されるようにします。そのための道具として、元記事では次の2つのコマンドが紹介されています。 - /skill-creator: 最初からきちんとした形の新しいスキルを書ける。既存のスキルを監査して、削る・重複をなくす・構成し直すこともできる - /skill-doctor: ライブラリの各スキルにどれだけコストがかかり、実際にどれくらい使われているかを確認し、使われていないスキルを削除できる なお、移行キットの README によると、/skill-creator はプラグインで、/plugin install skill-creator@claude-plugins-official でインストールします。 移行を加速するツール 🛠️ 元記事では、ここまでの作業の大半を手伝う Claude API スキルも紹介されています。Claude Code のコマンドとして使えるものです。 | コマンド | 何をするか | 移行での使いどころ | | --- | --- | --- | | /claude-api build-eval | 評価セットを作る | 中央チームが持つ最初のエンドツーエンド評価や、各チームがスキルと一緒に出す小さな評価を作る | | /claude-api prompt-audit | プロンプト・スキル・ツールの説明文から、古いモデル向けに書かれた指示を見つけ、修正案を差分で示す | 以前のモデルのために足され、今ではエージェントを遅く・硬くしているルールを探す。各チームの担当者が自分のスキルにも使える | | /claude-api hillclimb | 既存の評価をもとに、アプリの改善を繰り返し重ねる | 「取り込んだ版」と「残した版」の比較に使う。スキル＋ツールに取り込んだ後、その説明文の改善を重ね、サブエージェント版に並ぶか上回るかを見る。システムプロンプトにも使える | | /claude-api cost-optimize | 呼び出しの内訳を調べ、プロンプトキャッシュ、不要な入出力トークンの削減、effort、モデル選択などから、1つずつ節約案を出す | ある設計のコストと遅延を下げる（移行キットでは、設計が固まった後に使うとしている） | hillclimb について、移行キットの手順書では、取り込んだ版がサブエージェント版に及ばなかったとき、すぐにあきらめずに説明文の改善を重ねてから判断するために使う、という位置づけになっています。この使い方は覚えておくとよさそうです。 移行キット single-agent-loop-kit の中身 🧰 元記事の冒頭と末尾で紹介されている移行キットは、GitHub の anthropics/single-agent-loop-kit で公開されています（Apache-2.0）。ここからは、元記事には書かれていない、キットの README と手順書の内容を補足します。 > 📝 README には「参照実装であり、メンテナンスされておらず、コントリビューションも受け付けていない」と明記されています。Issue やプルリクエストも見られていないので、フォークして自分のシステムに合わせて使う前提のものです。 キットの考え方 キットの README は、「単一ループが常に勝つとは仮定しない。測る」と書いています。すべての変更を、同じ評価で前後比較し、置き換え先が持ちこたえると数字が示したときだけサブエージェントを外します。手順は大きく3段階です。 1. 測る: 既存の評価を探し、足りない部分を補い、今のシステムの点数を取る。評価がなければ、一緒に作る 2. 統合する: いつも一緒に動くサブエージェントをまとめる 3. 取り込む: 残ったサブエージェントを1体ずつスキルとツールに変えて比べる。独自のコンテキストに値するものは残し、ツールとして呼ぶ その後は、1つの小さなチームがシステムプロンプトと共有の評価を持ち、各領域チームがスキルを持つ形で維持していきます。 4種類の判定 キットの監査ステップでは、各サブエージェントに次のどれかの判定を付けます。 | 判定 | どんなときに付けるか | | --- | --- | | fold（取り込む） | 既定の判定。サブエージェントがプロンプト（手順・領域の知識）と API 呼び出しの組み合わせで、別のコンテキストを必要としない。スキル・ツールまたはその両方になる | | merge:<相手>（統合する） | 2つのサブエージェントが、お互いの出力を連鎖して使う、同じデータを読む、大半のトレースで一緒に動く | | as-tool（ツールとして呼ぶ） | 独自のコンテキストを持つべきで、仕事が1回の区切られた呼び出しに収まる。メインのエージェントが構造化された結果を受け取り、会話を持ち続ける | | keep（そのまま残す） | ユーザーとの会話を自分で持つ必要がある、または他社のもので変更できない。まれ | 判断に迷いやすいのが、「独自のコンテキストに値するか」です。キットの手順書は、次の3つのどれかが当てはまることを条件にしています。 - コンテキスト: メインのエージェントが後で必要とするよりはるかに多くを読む（ログ、長い文書、大きな検索結果など）。目安として、1回の呼び出しで数万トークンなら該当し、数千トークンなら該当しない。ただし、ツールが返す量を減らせる（絞り込み・検索・ページ分割）なら、より良いツールを作って fold にする方がよいことが多い - 並列・独立した作業: 複数の新しいコンテキストで別々に調べる、または作り方を見ずに他の仕事を確かめる - スキルでは解決できないツール過多や衝突: すべて読み込んだ状態で、メインのエージェントが測定できるほど間違ったツールを選ぶ、または指示が本当に矛盾している 逆に、別のコンテキストに値しない理由として、次のものが挙げられています。 - 社内の別のチームが持っている（持ち物はスキルとその評価に移す） - 独自のペルソナや口調がある（1つのエージェントは1つの口調であるべき） - プロンプトが長い（スキルの本文は必要なときだけ読み込まれる） - ツールが多い（ツール検索で、ツール定義を必要なときに読み込める） - 手順が決まっている（決まった手順はワークフロー、つまり普通のコードで書ける） キットの判定条件を、筆者が流れ図にまとめると次のようになります（キット自体に流れ図や判定の順番があるわけではありません。また、監査ではルーター自身に main という判定が付き、これが単一ループの本体になります）。 flowchart TD S["サブエージェント"] --> Q1{"ユーザーと直接<br>やり取りが必要？<br>または他社のもの？"} Q1 -->|"はい"| KEEP["keep<br>（まれ）"] Q1 -->|"いいえ"| Q2{"独自のコンテキストに<br>値する？<br>（大量の読み込み・<br>並列や独立した検証・<br>解決できない衝突）"} Q2 -->|"はい"| AST["as-tool<br>ツールとして呼ぶ"] Q2 -->|"いいえ"| Q3{"他のサブエージェントと<br>いつも一緒に動く？"} Q3 -->|"はい"| MRG["merge<br>統合してから取り込む"] Q3 -->|"いいえ"| FOLD["fold<br>スキル＋ツールに取り込む"] style FOLD fill:#ffe0b2,stroke:#e65100,stroke-width:2px 「別チームが持っているから」「口調が違うから」という理由で残したくなる気持ちはわかりますが、キットははっきり「それは理由にならない」としています。冒頭の「組織図のコピー」の話と、ここでつながってきます。 使い方 自分のシステムに使う場合、README の手順は次の通りです。 git clone https://github.com/anthropics/single-agent-loop-kit cp -r single-agent-loop-kit/skill <your repo>/.claude/skills/single-agent-loop あとはエージェントのリポジトリで Claude Code を開き、「Run the single-agent-loop skill.」と頼みます。スキルはまず監査を行い、各サブエージェントの判定（fold / merge / as-tool / keep）を示して止まります。間違っている判定を直したら、計画に沿って1つずつ変更を進め、変更ごとに評価を実行して比較し、残すかどうかは人が決めます。 キットは、毎回同じ4か所で止まって確認を求めるように作られています。変更前の点数を測ること自体が最初の有料の実行になるので、確認②はその前に来ます。 flowchart LR A["監査"] --> C1["確認①<br>判定は合っている？"] C1 --> C2["確認②<br>有料の実行前<br>（トークン見積もり付き）"] C2 --> B["変更前の点数を測る"] B --> C3["確認③<br>変更前の点数が出た後"] C3 --> CH["変更を1つ"] CH --> C4["確認④<br>残す・直す・戻す？"] C4 --> CH 評価がまだない場合でも始められます。その場合、スキルは本番の外でテスト用のリクエストを安全に流す方法と、いくつかの実際のリクエストを求め、10件ほどのタスクを下書きして、それぞれの「完了」の定義を人に直してもらってから実行します。 まずは10分で試せるサンプル キットには、examples/support-desk という小さなサンプルが入っています。架空の小売店「Tamberwick Home」のサポートデスクで、ルーター＋6つのサブエージェント（account、claims、diagnostics、orders、returns、shipping）で構成されています。各サブエージェントには、あらかじめ「正しい判定」が決められています。 最初は、API キーもコストもかからない無料のチェックから始められます。 cd single-agent-loop-kit/examples/support-desk KIT_MODEL=fake python3 evals/run_eval.py --variant smoke オフラインの代役モデルで19件のタスクが流れ、配管が正しく動くかを確認できます（代役はキーワードのルールで動くだけなので、このときの結果は採点されません）。実際のモデルでの監査と取り込みは、RUNBOOK.md の手順で進めます。 > 📝 キットの example-run/ には、実際のモデルで動かした2回分の記録があります。1回目は 2026年10月8日に claude-opus-5 で実行したもの（監査、12件のタスクで測った変更前の点数、returns サブエージェントの取り込み）、2回目はその翌日に17件のタスクで diagnostics をツールとして呼ぶ形に変えたもの（example-run/as-tool/）です。README によると、測定結果とそこから導いた結論は解説（README と PLAN.md）からは削除されていますが、記録（採点結果とトレース）はそのまま残っていて、比較結果は付属のスクリプトでそこから表示します。また、繰り返し2回では少ない、と記録自身が注意しています。 まとめ 🌱 元記事の主張は、「サブエージェントはもう要らない」ではなく、「サブエージェントの数は、組織図ではなく測定で決める」というものです。 コンテキストの肥大化、新しいコンテキストでの並列作業、ツール選択の難しさや指示の衝突。この3つに当てはまる場面では、今でもサブエージェントが活躍します。一方で、「チームが違うから」「担当領域が違うから」という理由で分けたサブエージェントは、つぎはぎのプロンプト、局所的な評価、伝言ゲームによる情報の抜け落ち、遅延の増加を招きやすくなります。モデルの能力が上がり、スキルとツール検索で必要なときだけコンテキストを読み込めるようになった今、より多くのサブエージェントを、1つのループの中のスキルとツールに置き換えられるようになっている、というのが元記事の見立てです。 この記事で一番持ち帰りたいのは、元記事の結びにある次の原則です。 > 測る。一度に1つだけ変える。持ちこたえたものを残す。 一度にすべてを作り替える必要はありません。正解付きの例を10件ほど集めて小さなエンドツーエンド評価を作り、利用の多いサブエージェントを1体だけスキルとツールに取り込み、複数回実行して、どのタスクの結果が変わったかを見る。成績が悪ければサブエージェントとして残し、問題なければ次の1体に進む。今のエージェントにサブエージェントがいくつもあるなら、まずは移行キットのサンプルで無料のチェックを流して、流れをつかむところから始めてみてください 🙌 参考 - Building agents: When to fold subagents into your main agent loop — Anthropic（Diane Sarkis、2026年10月22日）。この記事の元記事 - anthropics/single-agent-loop-kit — 元記事の移行キット（Apache-2.0、参照実装） - How we built our multi-agent research system — Anthropic。サブエージェントを使う例として元記事が参照 - Building multi-agent systems: When and how to use them — 元記事が参照するマルチエージェントの使いどころの記事 - Building agents with Skills: Equipping agents for specialized work — 元記事が参照するスキルの記事 - Tool search tool — Claude Platform ドキュメント。ツールの遅延読み込み - Task budgets — Claude Platform ドキュメント。ループの予算 - The new rules of context engineering for Claude 5 generation models — Claude Code のシステムプロンプト削減の出典として元記事が参照
Anthropic Says Fold Your Subagents. Let's Build a Tiny Single Agent Loop in TypeScript. --- title: "Anthropic Says Fold Your Subagents. Let's Build a Tiny Single Agent Loop in TypeScript." published: true description: "Anthropic now suggests one agent loop that loads skills and tools on demand instead of a fleet of subagents. Build a tiny TypeScript version with a turn budget and a write gate. No API key." tags: ai, typescript, agents, llm cover_image: bhjr.dev --- A lot of agent systems look like org charts. There's a router at the top. Under it, a refunds agent. A shipping agent. A billing agent. Each one has its own prompt, its own tools, and its own context window. It feels organized. It also means every handoff is a summary of a summary. Every handoff loses something. This week, Anthropic published Building agents: When to fold subagents into your main agent loop. The opening line is the whole argument: "using fewer subagents in favor of progressively disclosed context and tools can improve quality while reducing cost and latency." The idea is simple. The agent sees short descriptions of skills and tools up front. The full versions load only when needed. Anthropic gives three reasons. Shared context produces better answers. Progressive disclosure prevents context bloat. And models are more capable now, starting with Opus 4.5. One detail stood out. Anthropic says it cut Claude Code's system prompt for more advanced models by over 80%, including cuts from progressively disclosing skills and tools. It also shipped a migration kit. The kit "does not assume a single loop always wins. It measures." That distinction matters. This isn't "subagents are bad." Anthropic still lists cases for them: measurable context bloat, parallel disposable work, and conflicting tools or instructions. It's "stop splitting work just because the prompt got long." I've built the other side of this before. My fan-out budget post was about limiting a thousand subagents. This one is about not needing most of them. So let's build a tiny version. By the end, you'll run one command: npx tsx loop.ts And watch one loop handle a refund by loading only what it needs, then stop at a write gate. The full code is on GitHub. Table of Contents 1. [The Problem With Org Chart Agents](#1-the-problem-with-org-chart-agents) 2. [Step 1: A Catalog With Two Levels](#2-step-1-a-catalog-with-two-levels) 3. [Step 2: What the Model Sees Up Front](#3-step-2-what-the-model-sees-up-front) 4. [Step 3: The Loader Tools](#4-step-3-the-loader-tools) 5. [Step 4: One Loop With Limits](#5-step-4-one-loop-with-limits) 6. [Step 5: Run It](#6-step-5-run-it) 7. [Where It Breaks Down](#7-where-it-breaks-down) 8. [The Bigger Idea](#8-the-bigger-idea) 1. The Problem With Org Chart Agents Here's the usual shape: Router ├→ refunds agent (own prompt, own tools, own context) ├→ shipping agent (own prompt, own tools, own context) └→ billing agent (own prompt, own tools, own context) A customer writes: "My package never came. Can I get a refund?" That's shipping and refunds. The router picks one. Or both, and then something has to merge two summaries. The shipping agent knows the package is lost. The refunds agent only knows what the summary said. Teams split agents like this for a good reason. Putting every policy and every tool schema into one prompt makes it huge. Progressive disclosure removes that reason. The prompt doesn't have to be long if it only holds the table of contents. 2. Step 1: A Catalog With Two Levels // tiny-single-loop: one agent, one context, skills and tools loaded on demand. // Small model of the pattern Anthropic describes, not Claude's implementation. // Fake model, fake tools, rough token estimate (chars / 4). No API key. No network. type Skill = { name: string; description: string; body: string }; type Tool = { name: string; description: string; schema: string; write: boolean; run: (a: string) => string }; // Step 1: a catalog with two levels of detail const skills: Skill[] = [ { name: "refunds", description: "Refund or partially refund a customer order.", body: "Refund policy: full refund within 30 days. After 30 days, store credit only. ".repeat(12) + "Steps: look up the order, check the date, then issue_refund or issue_credit." }, { name: "shipping", description: "Track, reroute, or reship a package.", body: "Carrier rules, address change cutoffs, reship limits. ".repeat(20) }, { name: "billing", description: "Explain charges, invoices, and failed payments.", body: "Invoice formats, proration rules, retry schedules. ".repeat(20) }, ]; const tools: Tool[] = [ { name: "lookup_order", description: "Get an order by id.", schema: "{ id: string }".padEnd(240), write: false, run: (id) => `order ${id}: $48.00, placed 12 days ago` }, { name: "issue_refund", description: "Refund an order to the original payment.", schema: "{ id: string, amount: number }".padEnd(240), write: true, run: (id) => `refunded order ${id}` }, { name: "issue_credit", description: "Give store credit.", schema: "{ id: string, amount: number }".padEnd(240), write: true, run: (id) => `credited order ${id}` }, { name: "track_package", description: "Carrier tracking.", schema: "{ id: string }".padEnd(240), write: false, run: () => "" }, { name: "reroute_package", description: "Change delivery address.", schema: "{ id: string, address: string }".padEnd(240), write: true, run: () => "" }, ]; const tok = (s: string) => Math.ceil(s.length / 4); Each skill has a one-line description and a long body. Each tool has a one-line description and a full schema. The descriptions are cheap. The bodies and schemas are not. This mirrors Anthropic's Agent Skills format. A SKILL.md starts with a name and description. The body loads only when the skill is relevant. My bodies are repeated filler so the token math is visible. Real ones would be real policy. Hopefully less repetitive. Probably not. 3. Step 2: What the Model Sees Up Front // Step 2: what the model sees up front function upfront(): string { return skills.map((s) => `skill ${s.name}: ${s.description}`).join("\n") + "\ntools: load_skill(name), tool_search(query)"; } function everything(): string { return skills.map((s) => s.body).join("\n") + tools.map((t) => t.schema).join("\n"); } Two views of the same catalog. upfront() is names, descriptions, and two loader tools. everything() is what you'd paste into a giant system prompt. The token estimate is rough: characters divided by four. Good enough to compare. Not good enough to bill. 4. Step 3: The Loader Tools // Step 3: the two loader tools type Ctx = { text: string; loaded: Set<string>; visible: Set<string>; log: string[] }; function loadSkill(c: Ctx, name: string) { const s = skills.find((x) => x.name === name); if (!s || c.loaded.has(name)) return; c.loaded.add(name); c.text += "\n" + s.body; c.log.push(`load_skill(${name}) +${tok(s.body)} tok`); } function toolSearch(c: Ctx, query: string) { const hits = tools.filter((t) => query.split(" ").some((w) => t.name.includes(w))); for (const t of hits) { c.visible.add(t.name); c.text += "\n" + t.schema; } c.log.push(`tool_search("${query}") -> ${hits.map((t) => t.name).join(", ")} +${hits.length * tok(hits[0]?.schema ?? "")} tok`); } Two tools do the disclosing. load_skill reads one skill body into context, once. tool_search finds matching tools and adds their schemas. Only visible tools can be called. !Two levels of detail The model decides what to load. The harness just keeps track of what's in context. Load the chapter when you need it, not the whole manual. 5. Step 4: One Loop With Limits // Step 4: one loop, with limits in the harness type Limits = { maxTurns: number; approvedWrites: Set<string> }; function call(c: Ctx, lim: Limits, name: string, arg: string): string { const t = tools.find((x) => x.name === name); if (!t || !c.visible.has(name)) return `ERROR ${name} not loaded`; if (t.write && !lim.approvedWrites.has(name)) return `GATE ${name} needs approval`; return t.run(arg); } // A fake model: a plan of steps it would choose, one batch per turn. const plan: Array<(c: Ctx, lim: Limits) => string | null> = [ (c) => { loadSkill(c, "refunds"); return null; }, (c) => { toolSearch(c, "order refund credit"); return null; }, (c, l) => call(c, l, "lookup_order", "1042"), (c, l) => call(c, l, "issue_refund", "1042"), ]; function run(task: string, lim: Limits) { const c: Ctx = { text: upfront() + "\n" + task, loaded: new Set(), visible: new Set(), log: [] }; let turn = 0; for (const step of plan) { if (++turn > lim.maxTurns) { c.log.push("STOP turn budget"); break; } const out = step(c, lim); if (out) c.log.push(out); if (out?.startsWith("GATE")) break; } return { c, turn }; } This is the shape Anthropic suggests. One model, one context window, an open-ended tool loop. The limits live in the harness: "turn and cost budgets, write gates." My call function enforces two of them. A tool must be loaded before it can run. No calling a schema you've never seen. A write tool needs approval. Reads run freely. Refunds don't. The fake model is just a list of steps. A real model would choose them each turn and revise its plan as results come in. Anthropic says that's the main change: "the model that writes the plan is also the one carrying it out." !One loop, limits in the harness 6. Step 5: Run It // Step 5: run it console.log("tiny-single-loop demo (fake model, fake tools)\n"); console.log(`all skills + tools up front: ~${tok(everything())} tok`); console.log(`names + descriptions only: ~${tok(upfront())} tok\n`); const task = "Customer wants a refund for order 1042."; for (const [label, lim] of [ ["run 1 (no write approval)", { maxTurns: 6, approvedWrites: new Set<string>() }], ["run 2 (refund approved)", { maxTurns: 6, approvedWrites: new Set(["issue_refund"]) }], ["run 3 (turn budget 2)", { maxTurns: 2, approvedWrites: new Set(["issue_refund"]) }], ] as const) { const { c } = run(task, lim); console.log(label); for (const l of c.log) console.log(" " + l); console.log(` context at end: ~${tok(c.text)} tok, skills loaded: ${[...c.loaded].join(", ") || "none"}\n`); } Run it: npm install npx tsx loop.ts Output: tiny-single-loop demo (fake model, fake tools) all skills + tools up front: ~1077 tok names + descriptions only: ~55 tok run 1 (no write approval) load_skill(refunds) +250 tok tool_search("order refund credit") -> lookup_order, issue_refund, issue_credit +180 tok order 1042: $48.00, placed 12 days ago GATE issue_refund needs approval context at end: ~496 tok, skills loaded: refunds run 2 (refund approved) load_skill(refunds) +250 tok tool_search("order refund credit") -> lookup_order, issue_refund, issue_credit +180 tok order 1042: $48.00, placed 12 days ago refunded order 1042 context at end: ~496 tok, skills loaded: refunds run 3 (turn budget 2) load_skill(refunds) +250 tok tool_search("order refund credit") -> lookup_order, issue_refund, issue_credit +180 tok STOP turn budget context at end: ~496 tok, skills loaded: refunds Read it top to bottom. Putting every skill and tool up front costs about 1,077 tokens in this toy. Names and descriptions cost about 55. Run 1 loads the refunds skill and finds three matching tools. It looks up the order. Then it hits the write gate on issue_refund and stops. Run 2 is the same, with the refund approved. It goes through. Run 3 has a turn budget of two. It stops before it touches the order. In every run, shipping and billing never load. They cost nothing because nobody needed them. The context ends around 496 tokens instead of starting at 1,077. These are toy numbers from toy bodies. The direction is the point, not the ratio. 7. Where It Breaks Down This is a small model of the idea. It is not how Claude works, and it is not Anthropic's kit. The skills, tools, order, and token numbers are example inputs. A few things it skips: - Measuring. Anthropic's kit scores every change on the same eval before and after. I don't have an eval here. If you fold a subagent, measure first. - Search quality. My tool_search matches substrings. A bad search hides the right tool, and the agent never knows it existed. - Context still grows. Loading on demand delays bloat. A long session can still fill the window. Compaction still matters. - Parallel work. Anthropic still recommends subagents for parallel, disposable work. One loop doesn't replace a thousand-file review. - Conflicting instructions. If two skills give opposite rules, one context holds both. Separate agents can keep them apart. - Real budgets. My turn budget counts steps. Real ones count cost and time too. Fewer agents isn't the goal. Fewer lossy handoffs is. 8. The Bigger Idea Task ↓ Up front: skill names + descriptions, loader tools ↓ Model loads a skill, searches for tools ↓ Harness checks: loaded? write approved? budget left? ↓ Tool runs, raw result returns to the same context ↓ Model revises the plan, repeats or answers The model provides the plan. The descriptions provide the map. The skills provide the knowledge. The tool search provides the hands. The harness provides the limits. The shared context provides the memory between steps. For a while, the answer to a hard agent problem was another agent. Now, at least for a lot of workloads, it might be a shorter prompt and a better index. One loop that knows where to look beats five that each know a little. --- Try Roster I'm building Roster around this idea: AI employees with real responsibilities, tools, memory, schedules and computer access. One employee that keeps the whole picture beats a relay of handoffs. If the same follow-ups, handoffs, and waiting loops keep eating your week, give them to an AI employee. Try Roster →
Sources: - Anthropic, "When to fold subagents into your main agent loop" (Oct 22): claude.com - Migration kit with a demo you can run on a mock system (Apache-2.0): anthropics/single-agent-loop-kit
Single agent loop kit: Anthropic khuyên bớt sub-agent | PaperEngineer #shorts Một agent chạy nhanh gần gấp đôi cả đội sub-agent: Anthropic chỉ cách gộp sub-agent và khi nào nên giữ chúng. anthropics/single-agent-loop-kit: anthropics/single-agent-loop-kit Bài gốc của Anthropic: claude.com Tác giả: Anthropic (github.com/anthropics) Giấy phép: Apache-2.0 Ảnh chụp màn hình repo dùng để giới thiệu dự án; bản quyền thuộc về tác giả. #github #AI #lapTrinh #opensource Giọng đọc: pnnbao-ump/VieNeu-TTS-v3-Turbo (vieneu 3.8.3, CPU ONNX) (giấy phép Apache-2.0) huggingface.co Nhạc nền: ACE-Step 1.5 (acestep-v15-turbo) (giấy phép MIT) ace-step/ACE-Step-1.5 Theo dõi kênh Kỹ sư giấy để cập nhật kiến thức công nghệ hay mỗi ngày. [en-US] Single-agent loop kit: Anthropic advises using fewer sub-agents | PaperEngineer #shorts An agent runs nearly twice as fast as an entire team of sub-agents: Anthropic shows how to fold sub-agents and when to keep them. anthropics/single-agent-loop-kit: anthropics/single-agent-loop-kit Anthropic's original article: claude.com Author: Anthropic (github.com/anthropics) License: Apache-2.0 Screenshot of the repo used to showcase the project; copyright belongs to the author. #github #AI #programming #opensource Voiceover: pnnbao-ump/VieNeu-TTS-v3-Turbo (vieneu 3.8.3, CPU ONNX) (Apache-2.0 license) huggingface.co Background music: ACE-Step 1.5 (acestep-v15-turbo) (MIT license) ace-step/ACE-Step-1.5 Follow the Paper Engineer channel for daily updates on useful technology knowledge.