Claude Agent SDK Added a Workflow Tool. When Do Subagents Stop Being Enough?

What a subagent does, and where it stops

A subagent is a worker Claude spawns mid-conversation. You define it with a description, a prompt, and optionally restricted tools and a different model; Claude decides when a subtask matches that description and sends it off. The benefit is context isolation: a subagent can read fifty files and burn forty thousand tokens doing it, and none of that shows up in the lead agent's history. Only the subagent's final message returns to the parent.

That model works turn by turn. Claude decides what to spawn next, waits for the result, and decides again. The official subagents documentation is explicit about where this stops paying off: subagents work well for a few delegated tasks per turn. Push past that and two problems show up at once. The lead agent's context fills with intermediate results even though each subagent's own work stays isolated, and the lead agent itself becomes the bottleneck for deciding what to do next, turn after turn, for a job that has no natural turn structure.

Sources: Subagents in the SDK - Claude Code Docs.

What changes when you move to the Workflow tool

A dynamic workflow is a JavaScript script that orchestrates many subagents at once. Instead of Claude deciding turn by turn, Claude writes the script up front, and a separate runtime executes it in the background while the session stays responsive. The script calls agent() to spawn one subagent, parallel() to run several at once and wait for all of them, and pipeline() to run one per item in a list, with phase() grouping stages for a progress view.

The structural difference is where results live. In a subagent pattern, every result that returns goes into Claude's context window. In a workflow, intermediate results stay in script variables instead of landing in Claude's context, so Claude's context holds only the final answer. The official documentation frames the choice directly: with subagents, Claude is the orchestrator deciding turn by turn what to spawn next, while a workflow script holds the loop, the branching, and the intermediate results itself.

This is a TypeScript Agent SDK feature, available from v0.3.149 onward. You enable it by including Workflow in allowedTools, which lets the SDK auto-approve workflow runs the way it would any other allow-listed tool call. Every run writes its script to a file under the session's directory, and Claude can only start a workflow from a script file the session is already allowed to read.

Sources: Orchestrate subagents at scale with dynamic workflows - Claude Code Docs, Subagents in the SDK - Claude Code Docs.

A worked example: checking forty vendor contracts against a policy list

Illustrative scenario: a small team's compliance bot needs to check forty vendor contracts against a twelve-point policy checklist, flag exceptions, and produce one summary. Doing this with subagents means Claude spawns a reviewer, waits for the result, logs it, and spawns the next one, forty times, with every result accumulating in the lead agent's context. That's workable at four or five contracts. At forty, the lead agent is tracking state it doesn't need to see in full and burning context on intermediate detail.

A workflow script instead fans the job out with parallel(), one reviewer thunk per contract, each returning a structured object of flagged clauses. The script collects all forty results into a plain array, filters for exceptions, and only passes the filtered list and a count back to Claude for the final summary. The official cookbook example for this pattern is a fact-check task: verifying many independent claims against source documents, which it describes as needing more agents than one conversation can coordinate, with the workflow spawning parallel verifier and skeptic subagents and the runtime executing the script in the background.

The cookbook's own comparison table makes the scale difference concrete: a single agent or a set of subagents handles a few delegated tasks per turn, while a dynamic workflow handles dozens to hundreds of agents per run, with intermediate results sitting in script variables rather than any agent's context window.

Sources: Orchestrate subagents at scale with dynamic workflows.

Where this breaks, and the caps that matter

Workflows aren't free orchestration. The cookbook's own cost note says workflows spawn many subagents, so they use meaningfully more tokens than a single-agent session, and that a failed stage with a retry adds more. A forty-contract run that looks cheap on paper can get expensive fast if one reviewer stage keeps failing and retrying.

There are hard caps for a reason. By default a run allows up to sixteen concurrent agents, adjustable from one to 256 with an environment variable, and caps out at a thousand agents total per run. If your bot's task genuinely needs more fan-out than that, the Workflow tool isn't the right shape for it as released. If a script references a scriptPath the session isn't allowed to read, Claude Code rejects the call with an error rather than silently falling back to something else.

The practical troubleshooting advice from Anthropic's own documentation, for a workflow that's spawning too many subagents or running up an unexpected bill, is to set a budget cap directly, lower the subagent concurrency limit, and set the subagent spawn depth to 1 if you don't want nesting at all. None of these are workflow-specific settings bolted on after the fact; they're the same budget and concurrency controls that govern ordinary subagent use, applied to a script that can spawn far more of them per run than a human would type by hand.

Sources: Orchestrate subagents at scale with dynamic workflows, Subagents in the SDK - Claude Code Docs.

The decision: subagent or workflow

Stay with subagents when the job fits inside a handful of delegated tasks per turn and you want Claude's judgment in the loop between them — deciding whether a result changes what happens next is exactly what turn-by-turn delegation is for. Step up to the Workflow tool when the job needs dozens to hundreds of independent units of work, when the connecting logic is mechanical enough to write as plain code (filter, loop, verify, merge), and when you want that orchestration saved as a script you or your team can read and rerun rather than re-derived by Claude each time.

Before turning a workflow loose on a recurring job, set a budget cap and a concurrency limit explicitly rather than relying on the defaults, and confirm the script's file permissions line up with what the session is actually allowed to read. The Workflow tool is TypeScript-only at this point, so a bot built on the Python Agent SDK doesn't get this option yet and should keep structuring large fan-out jobs as batched subagent calls or an external task queue instead.

Sources: Subagents in the SDK - Claude Code Docs, Orchestrate subagents at scale with dynamic workflows.