Claude Dynamic Workflows Tutorial: Run Up to 1,000 Agents on Anthropic's Managed Platform

Introduction

On October 9, 2026, Anthropic put dynamic workflows for Claude Managed Agents into public beta. The feature lets an agent write its own orchestration program: a lead agent splits a large job into phases, runs agents in parallel, and merges their results while the server executes everything in the background. This tutorial walks through enabling dynamic workflows, telling the agent when to start a run, tracking a run through the session event stream, and keeping token costs under control. It is aimed at developers using the Claude Platform API who want multi-agent orchestration without running infrastructure themselves.

Quick answer

Set your agent’s multiagent.type to multiagent_20261001 and send the managed-agents-2026-04-01 beta header. Describe in the system prompt when to start a run. The agent then launches server-side workflow runs on its own, and you follow them through workflow_run.* events.

Evidence

Dynamic workflows are Anthropic’s own term for what the platform release notes define in one line: “A workflow is a program that runs many agents in phases and combines their results.” The announcement came from Anthropic’s Claude Platform release notes on October 9, 2026, confirmed the same day by the @ClaudeDevs launch thread and independent coverage.

Anthropic’s headline evidence is a single internal benchmark, and it is worth reading with the vendor’s name attached. As reported by multiple outlets from the launch thread: Anthropic planted 70 bugs in a 116,000-line codebase. Across three runs, a single agent found 14, 15, and 27 bugs, while a dynamic workflow found 66 bugs in each of its three runs. That is 94.3% recall with zero run-to-run variance, against a single agent whose results swung almost twofold. Anthropic has not disclosed which model powered the test or any token figures, so this is a test of structure, not of any model.

The scale numbers come from Anthropic’s workflow runs documentation. A run can start up to 1,000 agents over its lifetime, with up to 64 agents working at once as a target rather than a guarantee. The default run lifetime is 24 hours, and a session holds up to 10 open runs by default. The 1,000-agent cap counts agents started, and because the server can rerun a failed agent on a new thread, a run can exceed 1,000 threads before the cap ends it with a thread limit error.

Anthropic’s own cost warning is the quotation to take seriously: “Dynamic workflows are powerful and can use a lot of tokens, so we suggest starting with a scoped task.” The pricing mechanics: a run has no price of its own. Every agent’s tokens bill at its model’s list rates, Managed Agents adds session runtime at $0.08 per session-hour (counted only while the session is running), and a session budget is the brake. When the session’s spend reaches the budget, every open run pauses, and each working agent finishes the request it already started.

For the full parameter reference, see the multi-agent orchestration docs, covering the multiagent_20261001 type, predefined and inline agents, and system-prompt guidance. For the spend side, see the Managed Agents pricing page.

Prerequisites

• A Claude Platform API account with an API key. Managed Agents are enabled by default for API accounts; every request needs the managed-agents-2026-04-01 beta header.
• Familiarity with the Claude API and JSON request bodies. This is a developer API feature, not a setting in the Claude chat app.
• A rough budget for token spend before you start. Dynamic workflows are built for ambitious workloads, and every agent in a run consumes tokens.
• Optional: Claude Code installed, which ships a Managed Agents onboarding helper.

Step 1: Understand what a run is (and is not)

Before touching the API, internalize the two modes. With subagents, the session’s agent delegates a task itself, reads each subagent’s report, and can send follow-up messages to any thread, because a subagent’s thread stays available until archived. Delegation is one level deep, with at most 25 child threads at a time.

With dynamic workflows, the agent writes a workflow program that the server runs in the background while the agent keeps working or ends its turn. Results pass programmatically from one agent to the next, and the agent cannot send follow-up messages to a run’s threads. That tradeoff is the whole point: workflows buy scale and hands-off execution, and they cost you mid-run steering.

Practical consequence: a run suits jobs that decompose cleanly, like reviewing hundreds of documents or sweeping a codebase for bugs. A job that needs the agent to react to each subagent’s findings mid-flight fits subagents better.

Step 2: Enable dynamic workflows on your agent

Create or update the agent with the multiagent_20261001 type in its multiagent block, and send the beta header on the request:

{
  "multiagent": {
    "type": "multiagent_20261001",
    "workflows": { "type": "enabled" },
    "subagents": { "type": "enabled" }
  }
}

Three facts from the docs govern this block. First, with the multiagent_20261001 type, subagents and workflows are both enabled by default, so the explicit entries above are for clarity. For workflows only, set "subagents": {"type": "disabled"}. Second, the workflows setting lives inside the multiagent block, not at the top level of the agent definition. Third, an update that keeps the multiagent_20261001 type changes only what it sends: a setting you omit keeps its stored value, while a setting you send as null resets to its default, which for workflows means enabled. To turn workflows off deliberately, send {"type": "disabled"}.

Two gotchas reject requests with a 400 error: the ant__ tool-name prefix is reserved, so rename any custom tool that uses it first. And an agent that itself has multiagent set cannot be listed in another agent’s predefined_agents.

If you prefer the guided route, Claude Code ships an onboarding command: run /claude-api managed-agents-onboard inside Claude Code for a walkthrough of the same setup.

Step 3: Tell the agent when to start a run

Turning workflows on only gives the agent the ability to start runs. The agent determines when to start one, guided by your system prompt. There is no API call that starts a run: you describe the work in a user.message, and from that the agent decides whether and when to start. Permission policies apply to the tools that a run’s agents call, not to starting the run itself.

The docs’ contract-review example is the template to copy. Name the tasks in your domain that call for a run, and the small tasks the agent should do itself. Three dimensions the docs recommend spelling out:

• How to split the work. For example: “In a run, use one agent per contract. Then have a second agent review every contract, not only the ones where the first agent found something, and look for what the first agent missed. Anything that fails the review gets redone and reviewed again.”
• What to do when an agent fails. For example: “One agent failing must not fail the run. If an agent fails to read a contract, list that contract as not covered.”
• A time limit. For example: “Give the run a one-hour time limit.”

End the guidance with the docs’ core rule: keep runs to the tasks that need them, because every agent in a run uses tokens. A vague prompt (“review the codebase”) hands the agent a blank check; a scoped prompt (“sweep these 40 files for authentication bugs, one agent per file, then merge”) does not.

Step 4: Create the session with a budget, then describe the work

Create the session referencing the agent, as you would for any Managed Agents session, and set a session budget on creation to cap the session’s spend, runs included. You cannot add a budget to an existing session later.

{
  "agent": "agent_01ABC...",
  "budget": { "max_cost_usd": 25 }
}

The exact budget field names follow the budgets documentation, so check the current docs page before copying this snippet into production. The principle is what matters: set the cap up front, at session creation, before any run exists.

Then send the work as a user.message on the session’s event stream:

{
  "type": "user.message",
  "content": "Review the 320 vendor contracts in /data/contracts. Start a workflow run: one agent per contract checking for renewal-date and liability-cap clauses, then a second agent re-reviews every contract to catch what the first pass missed. Merge into one report."
}

Notice the message does two jobs. It describes the work, and by echoing the system prompt’s trigger language (“start a workflow run”, “one agent per contract”), it nudges the agent toward starting a run rather than grinding through 320 contracts itself.

Step 5: Follow the run through workflow_run.* events

Run events arrive on the session’s event stream, alongside the standard thread events. Stream the session and watch for the workflow_run.* family: the run starting, its phases progressing, and its completion. Each agent in the run works in a session thread that you can list, read, and stream like any other thread, so you can inspect individual agents’ findings while the run is in flight.

What you cannot do is steer mid-run. If a run goes off track, the documented recourse is to interrupt it and start over with tighter guidance. Design your prompts accordingly: a run is fire-and-forget by architecture, so the “forget” part had better be safe.

One structural limit: only the agent on the primary thread can start a run. Runs do not nest, so a workflow’s agents cannot themselves start sub-runs. If your decomposition needs recursion, restructure it into phases instead.

Step 6: Control costs before they control you

Dynamic workflows bill like the rest of the session: every agent’s tokens at its model’s list rates, plus $0.08 per session-hour of Managed Agents runtime. The budget you set in Step 4 is the control plane. When the session reaches the budget, runs pause; raising or removing the budget resumes them, unless an interrupt also paused them.

Cost discipline in practice:

• Start scoped. Anthropic’s own advice is to begin with a scoped task. Your first run should cover a bounded slice of the real job, so you learn the token cost per unit of work before committing to the full corpus.
• Constrain the agent mix. Inline agents use the model of the agent that runs the session. If you want cheaper models for the bulk workers and a stronger model only for the merge phase, create those as separate agents and list them in workflows.predefined_agents (up to 20).
• Restrict tools per agent. MCP servers are agent-scoped: each agent definition declares its own servers. An inline agent inherits the session agent’s tools, which can be broader than a worker needs. Predefined agents with narrow tool sets keep workers from burning tokens on irrelevant capabilities.
• Set time limits in the prompt. A per-run time limit (Step 3) bounds both duration and spend for jobs where completeness has diminishing returns.

Troubleshooting

The agent never starts a run and does the work itself. This is the most common first-run symptom. Either the system prompt never says when to start a run, so the agent defaults to doing the work, or workflows was never actually enabled. Check the agent’s stored multiagent block; a session copies settings at creation, so create a new session after enabling workflows. You can also ask for a run directly in the user.message.

A 400 error when creating or updating the agent. The usual suspects are all documented. A custom tool whose name starts with ant__ fails every update until you rename it. Listing an agent that itself has multiagent set in predefined_agents fails validation. Setting inline_agents to disabled with an empty predefined_agents list fails. And every agent in both lists must pin the same inference geography, or none of them can; a mismatch is rejected when the agent is saved and when a session is created.

The run pauses unexpectedly. A reached session budget pauses every open run. This is working as designed: raise or remove the budget to resume, unless an interrupt also paused the run. If runs keep pausing, measure the token cost of one phase and re-budget from that number rather than from intuition.

A run ends with a thread limit error. Going over the 1,000-agent cap ends the run with a thread limit error. The cap counts agents started, and reruns of failed agents on new threads count too, so a run with heavy failure churn can hit the cap early. Mitigations: make worker prompts robust so fewer agents fail, and split the job across multiple runs.

You cannot reach into a run to correct it. By design, the agent cannot send follow-up messages to a run’s threads once it starts. If the merge output is wrong, the fix is a new run with a corrected prompt, not a mid-run patch. Keep each run’s phases idempotent where possible so reruns are cheap.

FAQ

How do I turn on dynamic workflows in Claude Managed Agents? Set the agent’s multiagent type to multiagent_20261001 and send the managed-agents-2026-04-01 beta header. Workflows are on by default with that type. Then tell the agent in its system prompt when to start a run.

How is a dynamic workflow different from delegating to subagents? With subagents, the agent delegates and can send follow-ups to each thread. With a workflow, the agent writes a program that runs agents in phases without its direct involvement, and it cannot message a run’s threads.

How many agents can one workflow run start? Up to 1,000 over a run’s lifetime, with up to 64 working at once as a target rather than a guarantee. A run lives up to 24 hours by default, and a session holds 10 open runs by default.

How do workflow runs get billed? A run has no price of its own. Every agent’s tokens bill at its model’s rates, plus $0.08 per session-hour of Managed Agents runtime. A session budget caps spend, and runs pause when it is reached.

Can I stop a run from starting on its own? Yes: set workflows to {"type": "disabled"} in the agent’s multiagent block. Permission policies govern the tools a run’s agents call, not the act of starting the run.

Is this available in the Claude chat app? No. This is a Claude Platform API feature. Claude Code shipped its own dynamic workflows in May 2026 as a separate system.

Conclusion

Dynamic workflows move multi-agent orchestration from code you write to a program the agent writes: set multiagent_20261001, guide the agent’s judgment in the system prompt, cap the spend with a session budget, and follow workflow_run.* events while the server does the work. Lesson: scope the first run small, measure its token cost, and only then scale. For a related pattern you run yourself instead of on Anthropic’s servers, see our n8n multi-agent sub-agents tutorial, and for the agent platform this feature builds on, see Claude Code MCP setup.

Frequently asked questions