Claude Agent SDK Guide: Dynamic Multi-Agent Workflows

InYourLeague Research · 2026-08-30

Answer in brief

claude-agent-sdk can start a JavaScript dynamic workflow that coordinates clean-context subagents through parallel fan-out, dependent pipeline stages, model routing, and code-enforced verification. Completion evidence should connect the generated script and runtime progress to collected stage outputs, verification results, and explicit acceptance criteria.

Key facts at a glance

Failure modes and verification

FAQ

When should I choose a dynamic workflow instead of one agent?

Choose it when the task is difficult to coordinate in one conversation, contains many independently processed items, requires verification to be enforced by code, or produces orchestration worth saving and rerunning. The tradeoff is substantially higher token use.

Are subagents fully isolated from one another?

Each subagent starts with a clean context and receives only its script-supplied prompt. However, it works in the session’s working directory and follows the configured tool allowlist, so the documented isolation is contextual rather than evidence of a separate filesystem for every agent.

Can one workflow combine parallel and pipeline stages?

Yes. A JavaScript orchestration script can run independent subagents concurrently, retain their outputs in variables, and pass selected results into later filtering, judgment, synthesis, or adversarial-verification stages.

How are models assigned to subagents?

Subagents use the session model by default. A workflow can route an individual stage differently through its prompt, and CLAUDE_CODE_SUBAGENT_MODEL can override the model for every subagent in the run. The supplied evidence does not provide a comprehensive supported-model catalog.

What evidence shows that a workflow completed correctly?

Review the generated script, runtime progress, item-level and stage-level outputs, verification results, failures, and the final comparison with explicit acceptance criteria. A launch event alone does not prove that every intended item and mandatory verification stage produced a result.

Sources and freshness

• Official source
• Official source
• Last verified: 2026-08-30

Extended guide

Direct answer

Use claude-agent-sdk dynamic workflows when a task has many independent items, is difficult to coordinate within one conversation, or must execute verification by construction. Claude writes a JavaScript orchestration script and passes it to the Workflow tool. The runtime executes that script in the background, while a Python application can initiate the workflow through the Agent SDK and stream its progress. The official dynamic-workflow cookbook demonstrates this approach with parallel verifier and skeptic subagents.

Execution and isolation

Each subagent is a full Claude Code agent that starts with a clean context and receives only the prompt supplied by the script. It still works in the session’s working directory and follows the configured tool allowlist. The documented boundary is therefore context isolation; the supplied evidence does not describe a separate filesystem for every subagent.

The script holds outputs in variables and connects work with ordinary JavaScript logic such as filtering, loops, and verification passes. This supports three useful structures:

• Parallel fan-out assigns independent items to concurrent subagents.
• A pipeline passes earlier results into later extraction, judgment, filtering, or synthesis stages.
• Adversarial verification sends findings to verifier or skeptic agents instead of leaving review optional.

The runtime can keep up to 16 agents active concurrently, although limited CPU capacity may reduce that number. A workflow run is capped at 1,000 agents. Work beyond the active concurrency limit is queued until a slot becomes available.

Recommended implementation sequence

1. Define the input set, expected outputs, and acceptance criteria. Separate independent items from stages that depend on earlier results.
2. Request a JavaScript orchestration script that is easy for a person to inspect. Make fan-out, result collection, filtering, dependent stages, and mandatory verification explicit in the code.
3. Start the workflow from Python with query() and ClaudeAgentOptions. The cookbook specifies Python 3.11 or later, Claude Code CLI v2.1.154 or later, and claude-agent-sdk 0.2.90 or later, which bundles a compatible CLI.
4. Stream progress and retain the script and relevant outputs. The script can be read, edited, saved, and rerun, making the orchestration itself reviewable and reusable.
5. Reconcile the final output with the original input inventory and acceptance criteria. For fact-checking, verify that every claim was processed and that verifier or skeptic stages produced actual results.

Model routing

Subagents use the session model by default. The workflow can route a particular stage to another model, allowing mechanical extraction and difficult judgment to use different routing strategies. Routing can be steered through the prompt, while CLAUDE_CODE_SUBAGENT_MODEL overrides the model for all subagents in the run. The supplied evidence explains these routing mechanisms but does not provide a comprehensive supported-model catalog, so it should not be used by itself to select or certify a particular model ID.

Completion-evidence checklist

• The generated JavaScript script is available for inspection.
• Every planned input is accounted for in executed, queued, or explicitly failed work.
• Required pipeline and verification stages are encoded in the script.
• Runtime progress and stage outputs were collected.
• Verification stages produced results rather than merely being requested.
• Final outputs were compared with explicit acceptance criteria.
• Token cost was reviewed because many subagents can use substantially more tokens than one agent.

A launch event proves only that execution began. Strong completion evidence connects the inspectable plan to runtime records and final results. Dynamic workflows are most appropriate when consistent processing, enforced verification, or reusable orchestration justifies their additional token cost.

Model availability note: The official source does not specify a selectable model ID.