06-reference

Building agents: When to fold subagents into your main agent loop

2026-11-17·reference·source: https://claude.com/resources/articles/building-agents-when-to-fold-subagents-into-your-main-agent-loop·by Diane Sarkis (Anthropic, Applied AI)
subagentsagent-architecturesingle-agentskillsprogressive-disclosureevalscontext-engineering

⚠️ Sponsorship

Anthropic writing about how to build on Anthropic products. The thesis (fewer subagents, more skills and tool search) happens to route customers toward Claude skills, Managed Agents and Anthropic's own migration tooling, and the closing CTAs go to pricing and sales. The evidence is anecdotal: unnamed enterprise deployments, one "~2x faster" customer, and one support-agent regression seen in one of two runs. No benchmark dataset backs the "a single agent with skills often beat both alternatives" claim. Take the design heuristics seriously. The "it usually wins" claim is unproven.

Why this is in the vault

It is the vendor's current position on the exact design choice Ray makes all day: when to spawn a subagent versus keep work in the main loop. It also gives an eval-gated procedure for folding subagents back in, which Ray has never run on its own setup.

The mental model

Split by context, not by problem type. A subagent should exist because the work needs a fresh, discardable context window, parallelism, verification independence or separate permissions. It should not exist because an org chart or a task taxonomy has a box for it. Everything else belongs in one loop, with procedure carried by skills and hard limits enforced inside tools.

Summary (author's terms)

Mapping against Ray Data Co

Ray is already a single main loop that spawns subagents when needed (the same reading as [[2026-05-03-alphasignal-single-vs-multi-agent-systems]]), so most of this article confirms the current setup. The useful part is a test: for each subagent, does the split exist for context or independence, or only because the work has a separate label? Results by surface:

Where the split is justified (keep):

Where the article says fold back, or at least test folding:

  1. Hard rule 4 ignores what the extract loses. The article's main argument is that a summary handed back by a subagent loses things the main loop would have used. Hard rule 4 applies the same 5KB cutoff (about 1.2K tokens) whether Ray needs a fact from an artifact or has to reason over it: a founder's own draft, a spec, code he's about to change. For the second kind, the extract is the telephone game. A possible fix: scope the rule to "artifacts you only need an extract from" and allow direct reads when the artifact itself is the subject of the work. This is a hard rule, so changing it is the founder's decision. Ray has no measurement showing either version is better.
  2. station-critic runs one subagent per critic axis. Every axis reads the same artifact and runs on every pass. That matches the article's merge criteria ("touch the same data", "usually called together"). The skill justifies the split as protection against one axis copying another's diagnosis, a claim nobody has measured. Recommended test, following the article's procedure: on the golden set, compare one critic subagent that receives all the axes (still fresh-eyes, still separate from the producer) against the per-axis fan-out, then check which verdicts flip, with at least 2 runs each. Keep the fan-out only if the merged critic scores worse.
  3. Where the newsletter mapping gets written. The process-newsletter skill says the mapping to RDCO is the value, and that judgment needs vault context the subagent doesn't have. Verified 2026-11-17: the skill dispatches general-purpose subagents (process-newsletter SKILL.md:33), not the cheap fanout agent, so the model tier is fine. The open question is context: the subagent writes the mapping without the vault context the parent has. The article's pattern suggests a split: the subagent extracts and the parent maps, or the mapping is checked against the vault before filing. This needs testing before anyone changes it.

Brigade stations (spec → tests → code → critic). On its face this is splitting by problem type, which the article warns against. The spec → tests split exists for test independence ([[2026-05-12-rdco-pipeline-rlhf-shaped]], plan → tests → impl), and that is a verification reason, so it holds. The risk is the station-critic fan-out (point 2), not the four-station chain.

What Ray lacks to run any of this. The article's whole procedure depends on an end-to-end golden eval set with a single owner. Ray has per-note checks (the audit's I-checks, /self-review) and per-artifact critics, but no ~10-example end-to-end set that could show whether folding a subagent helped or hurt. Until that exists, every change above is a guess.

Already at parity: deferred MCP tools behind ToolSearch (the article's 30-50 definitions ceiling) and skills as progressive disclosure, with about 61 local skills loaded by description. Ray already follows the article's "procedure in skills, hard gates in tools/permissions" split (e.g. [[2026-11-13-building-always-on-agents]] write gates, auto-mode classifier).

Open questions

Related