# Build a Claude workflow that reviews documents in parallel
> Anthropic’s beta Managed Agents can turn a document review into a multi-phase workflow. This guide shows how to configure a run, inspect its events and output, and account for cost and limits.
By BIG CHANGE Editorial
Published: 2026-10-09T20:34:58.333Z
Updated: 2026-10-09T20:34:58.333Z
Canonical: https://bigchange.ai/blog/claude-managed-agents-parallel-document-review-guide
Conceptual illustration of a reader manually checking a proposed document-review report. It is not a Claude product screenshot or a BIG CHANGE hands-on test. AI-generated illustration by BIG CHANGE.
Claude Managed Agents can now write a workflow program that assigns pieces of a large task to multiple agents, gathers their findings and combines them. The feature is in beta. Here is a documented setup for a software builder who wants to review a folder of documents and produce a checked findings file.
This uses Anthropic's Claude Platform API and CLI. BIG CHANGE reviewed the current documentation; we did not run the setup or test a workflow.
## What the workflow does
A [dynamic workflow](https://platform.claude.com/docs/en/managed-agents/workflow-runs) is one program for one run. The program can split work into phases, start agent threads in parallel, pass their results between phases, retry or handle a failed branch, and combine the results. For example, a first phase could inspect separate files while a later phase reconciles the findings. The primary agent starts the run; the server executes it in the background.
That differs from asking the main agent to create separate runs. A workflow run coordinates child threads inside a single run and returns its result to the agent that started it. An ordinary session message does not start a run by itself; the agent decides when to start one based on the task and its system prompt. Anthropic says a session can have several runs open, but each run has its own phases and outcome.
## Before you start
You need a Claude Console account, an API key, and access to Claude Managed Agents, which Anthropic says is enabled by default for API accounts. The agent and workflow endpoints require the `managed-agents-2026-04-01` beta header. Anthropic's SDK sets that header automatically; when calling the API without an SDK, include it yourself.
Managed Agents is still labeled [beta in the current documentation](https://platform.claude.com/docs/en/managed-agents/overview). Anthropic's [release notes](https://platform.claude.com/docs/en/release-notes/overview) date its public beta to April 9, 2026, multiagent orchestration to May 11, and dynamic workflows to October 9. Dynamic workflows are also in beta. The date matters: the “1,000 agents” figure is a current workflow-run limit, not a newly available 1,000-way simultaneous launch.
The platform stores session conversation history, sandbox state and outputs server-side. Anthropic says Managed Agents is not currently eligible for [Zero Data Retention or HIPAA Business Associate Agreement coverage](https://platform.claude.com/docs/en/managed-agents/overview). Do not put regulated or confidential material in a session unless your organization has confirmed the applicable data rules and setup.
## 1. Install the CLI and SDK
Install Anthropic's `ant` CLI using the method for your operating system in the [Managed Agents quickstart](https://platform.claude.com/docs/en/managed-agents/quickstart). For example, the documented macOS command is:
```sh
brew install anthropics/tap/ant
```
For Python, install the SDK and provide the API key through your environment rather than putting it in a source file:
```sh
pip install anthropic
export ANTHROPIC_API_KEY="your-api-key"
```
The key above is a placeholder. Keep the real value in your normal secret manager or protected environment configuration.
## 2. Define an agent that can use workflows
Create `document-reviewer.md`. The `multiagent` block enables the October workflow type. Disabling subagents makes the configured delegation path explicit: this agent uses dynamic workflows rather than one-off subagent delegation.
```yaml
---
name: document-reviewer
model: claude-sonnet-5-5
tools:
- type: agent_toolset_20260401
multiagent:
type: multiagent_20261001
subagents:
type: disabled
workflows:
type: enabled
---
You review documents for a user-defined checklist.
When a request contains more than 20 independent files, use a dynamic workflow.
Make one phase that checks the files independently and a later phase that
reconciles duplicate findings. Do not infer missing facts. Save the final
machine-readable results to report.json and a concise explanation to summary.md.
Include the source filename and a short evidence excerpt for every finding.
If a file cannot be read or a worker fails, record that file as unresolved;
do not silently omit it. The final response must report the number of files
reviewed, unresolved files, and whether every output file was written.
```
The threshold and review instructions are your policy choices, not Anthropic defaults. Adapt them to the work and to the cost of errors. `claude-sonnet-5-5` is an example model ID; choose a model currently available to your account and budget.
Create the agent and retain its returned ID:
```sh
ant apply document-reviewer.md
```
The CLI prints the agent ID and records it in `claude-lock.json`. Managed Agents separates the reusable agent definition (model, instructions and tools) from the environment in which a session runs.
## 3. Configure the sandbox
An environment controls where sessions run: in an Anthropic-managed cloud sandbox or a self-hosted sandbox on your infrastructure. The quickstart's cloud example uses restricted networking and allows package managers:
```yaml
# environment.yaml
name: document-review
config:
type: cloud
networking:
type: limited
allow_package_managers: true
```
Apply it with `ant apply environment.yaml`; its ID is also saved in `claude-lock.json`. If the agent needs network access, list only the required hosts in `allowed_hosts`. With limited networking, that host list also restricts Managed Agents' web search and fetch tools. A setting that permits package managers does not add websites to the allowlist.
For a first run, use a small, non-sensitive folder and only the tools it needs. The built-in agent toolset includes shell and file operations; adding tools can widen what the agent is able to do. Check the documented permission policy and sandbox controls before granting access to external systems or credentials.
## 4. Start a session and send a bounded task
Use the agent and environment IDs to create a session with the Python SDK:
```python
import anthropic
client = anthropic.Anthropic()
session = client.beta.sessions.create(
agent="AGENT_ID_FROM_CLAUDE_LOCK",
environment_id="ENVIRONMENT_ID_FROM_CLAUDE_LOCK",
title="Small document review",
)
print(session.id)
```
Replace the two ID placeholders with the values in `claude-lock.json`. Then send a concrete task through the session event stream. Start the stream before sending the event so you can see the run and its progress as they arrive:
```python
with client.beta.sessions.events.stream(session.id) as stream:
client.beta.sessions.events.send(
session.id,
events=[{
"type": "user.message",
"content": [{
"type": "text",
"text": (
"Review each Markdown file in /review-set for a missing "
"owner, deadline, or acceptance criterion. Quote evidence; "
"do not infer missing details. Reconcile duplicate findings "
"and write /mnt/session/outputs/report.json plus "
"/mnt/session/outputs/summary.md. In report.json, use "
"a files array with one record per input: path, status "
"(reviewed or unresolved), and findings; each finding has "
"a check, evidence excerpt, and source location. Include "
"input, reviewed, and unresolved counts."
),
}],
}],
)
open_runs = {}
run_results = {}
for event in stream:
if event.type == "workflow_run.created":
open_runs[event.workflow_run_id] = event.name
print(f"Run started: {event.name}")
elif event.type == "workflow_run.status_ended":
run_results[event.workflow_run_id] = event.result.type
open_runs.pop(event.workflow_run_id, None)
print(f"Run ended: {event.result.type}")
elif event.type == "workflow_run.error":
print(f"Run error: {event.error}")
elif event.type == "agent.message":
for block in event.content:
if block.type == "text":
print(block.text)
elif event.type == "session.status_idle":
if event.stop_reason.type == "end_turn" and not open_runs:
break
# Inspect the child threads associated with completed workflow runs.
for thread in client.beta.sessions.threads.list(session.id):
if thread.workflow_run_id in run_results:
print(f"Thread {thread.id}: {thread.status}")
for thread_event in client.beta.sessions.threads.events.list(
thread.id, session_id=session.id
):
if thread_event.type == "session.error":
print(f"Thread error: {thread_event}")
```
This example assumes your configured session input method exposes the files at `/review-set`. Put the files in the session's sandbox using the documented input method before asking the agent to review them. For outputs, have the agent write under `/mnt/session/outputs/`; the [Managed Agents file documentation](https://platform.claude.com/docs/en/managed-agents/files) describes how to list files scoped to a session and download them. In the Python SDK, the documented readback shape is:
```python
files = client.beta.files.list(
scope_id=session.id,
betas=["managed-agents-2026-04-01"],
)
for report in files:
if report.filename == "report.json":
content = client.files.download(report.id)
content.write_to_file("report.json")
break
```
A file can take a few seconds to appear after the session becomes idle, so list again after a short delay if it is missing. For a safe first pass, make a test folder with a few documents whose expected findings you can inspect manually. The example prompt defines the review task; it does not guarantee the agent will find every issue.
The output contract should be strict enough to audit. For example:
```json
{
"files": [
{
"path": "requirements.md",
"status": "reviewed",
"findings": [
{
"check": "deadline",
"evidence_excerpt": "...",
"source_location": "requirements.md, section 2"
}
]
}
],
"input_count": 1,
"reviewed_count": 1,
"unresolved_count": 0
}
```
This is a suggested schema for your workflow, not a schema supplied by Anthropic. Preserve unresolved or unreadable files as records so a missing result cannot look like a clean review.
## 5. Check the run and its output
When a workflow starts, the event stream reports `workflow_run.created`, including a run ID and the phases declared by the workflow. The sample keeps each run ID open until its matching `workflow_run.status_ended`; an idle primary session alone does not establish that its background workflow has ended. The primary stream summarizes child-thread status, while a thread's own event list contains its messages and errors. The sample lists threads by `workflow_run_id` and surfaces `session.error` events. Inspect those events for exhausted retries (including `retry_status.type == "exhausted"`) or other child errors, and mark affected files unresolved.
Treat the output file as the deliverable, not the word “completed.” Anthropic explicitly warns that a run can end with `completed` even if work on a thread failed or a thread could not be created. Open `report.json` and check that each input file has either findings or an explicit unresolved status, evidence excerpts point to the right source file, and the counts match the files you supplied. Compare the small test folder against your own expected results before using the workflow on a larger corpus.
If your client disconnects, a new event stream sends only events emitted after it opens. Rebuild the run state by listing past session events with the documented event-type filters and following pagination. Do not infer that a run is finished from the primary agent going idle while child threads may still be working. After all observed runs end, list session-scoped files and download `/mnt/session/outputs/report.json` and `summary.md` using the documented Files API. Check that every supplied file has a reviewed or unresolved record and that the counts reconcile. The sample event loop does not download or validate the report itself.
## Limits that change the design
Anthropic's [workflow-run limits](https://platform.claude.com/docs/en/managed-agents/workflow-runs) currently document up to 64 workflow threads working at once in one run, but say the API does not guarantee that concurrency and the value may change. The 1,000-agent limit counts agents started over the run's entire lifetime. It is not a simultaneous-thread count. If a workflow asks to start another agent after reaching that total, the run ends with `thread_limit_error`; retries of failed agents can create additional threads.
A run lasts 24 hours by default, or less if its agent sets a shorter lifetime. Time spent waiting on your client counts, and a paused run can still time out. A session has 10 open runs by default, including idle runs. A session's usage budget applies to all workflow agents; when it is reached, open runs pause until the budget is raised or removed. Plan smaller work units, save checkpoints to files, and make the reconciliation phase report unfinished items rather than pretending they were reviewed.
For failures, inspect the `workflow_run.error` and the affected thread. `program_error` can mean workflow code or a child failed; `thread_limit_error` identifies the 1,000-agent ceiling; `timeout_error` identifies the run lifetime. If a run reaches the session budget, increase or remove the budget to resume it. If you need to stop a workflow, ask the primary agent to stop its runs; interrupting a session turn is not itself a run-cancellation command.
## Cost
Anthropic's [pricing documentation](https://platform.claude.com/docs/en/about-claude/pricing) bills Managed Agents for model tokens at the selected model's rates and for session runtime at **$0.08 per running session-hour**. Runtime accrues while the session status is `running`; idle, rescheduling and terminated time do not count. A workflow run has no separate fee, but the threads' token use is billed as part of the session. Web search invoked inside a session is listed at $10 per 1,000 searches. The exact total depends on model, input and output tokens, tools and how long the session runs; check usage in the Console rather than estimating from the 1,000-agent ceiling.
The practical setup is to start with a handful of files, verify that the workflow's output accounts for each one, inspect failed threads, then expand the input only when the review policy and cost are acceptable. Managed workflows provide a way to coordinate asynchronous parallel work; they do not certify the findings.
## The big change
Since October 9, a Managed Agents agent can write a workflow program that the server runs across multiple agent threads and phases. Builders can use that path for bounded, auditable fan-out while the main session follows progress. The feature remains beta, and the published limits do not promise that every run will reach its maximum concurrency or produce correct findings.
## Sources & further reading
- [Claude Managed Agents overview](https://platform.claude.com/docs/en/managed-agents/overview) — beta status, API header, access, stateful sessions, tools and data-retention limits.
- [Get started with Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/quickstart) — CLI, SDK, agent/environment setup, session creation and event-stream example.
- [Multiagent orchestration](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration) — enabling dynamic workflows and choosing between workflows and subagents.
- [Workflow runs](https://platform.claude.com/docs/en/managed-agents/workflow-runs) — run events, result interpretation, recovery, budgets and documented limits.
- [Session threads](https://platform.claude.com/docs/en/managed-agents/session-threads) — listing run-associated child threads and reading their event histories.
- [Session files](https://platform.claude.com/docs/en/managed-agents/files) — mounted inputs, output paths, session-scoped file listing and downloads.
- [Claude Platform release notes](https://platform.claude.com/docs/en/release-notes/overview) — October 9, 2026 dynamic-workflows update and beta configuration.
- [Claude Platform pricing](https://platform.claude.com/docs/en/about-claude/pricing) — token billing and session-runtime rates.
## Sources
- [Claude Managed Agents overview](https://platform.claude.com/docs/en/managed-agents/overview) — Current beta status, API header, access, stateful sessions and data-retention limits.
- [Get started with Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/quickstart) — CLI and SDK setup, agent/environment configuration, session and event-stream examples.
- [Multiagent orchestration](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration) — Workflow enablement and distinction from subagents.
- [Workflow runs](https://platform.claude.com/docs/en/managed-agents/workflow-runs) — Workflow/run mechanics, events, output-state interpretation, recovery, budgets and limits.
- [Claude Platform release notes](https://platform.claude.com/docs/en/release-notes/overview) — Dated public-beta history and October 9, 2026 dynamic-workflows update; canonical corrected URL.
- [Claude Platform pricing](https://platform.claude.com/docs/en/about-claude/pricing) — Managed Agents token and session-runtime prices.
- [Session threads](https://platform.claude.com/docs/en/managed-agents/session-threads) — Listing run-associated child threads and reading their event histories.
- [Session files](https://platform.claude.com/docs/en/managed-agents/files) — Mounted inputs, output paths, session-scoped file listing and downloads.
The BIG CHANGE newsletter
The big picture. At your pace.
Recent stories on AI and robotics, the shifts worth watching and practical ideas to use. Choose a daily briefing, weekly digest or monthly perspective.
Next scheduled send (UTC): . Your first edition arrives at the next scheduled send after you confirm.
Your privacy, your choice.
Necessary storage supports site security and remembers your choices. Optional Google Analytics stays off until you allow it. You can read every story with necessary storage only. Privacy details