Markdown 版本
AI-translated from English; not yet reviewed by a fluent editor.
# 建立可并行审阅文件的 Claude 工作流
> Anthropic 的 Managed Agents 测试版可将文件审阅转为多阶段工作流。本指南说明如何设定执行作业、检查事件与输出，并考量成本和限制。
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 现在可以撰写工作流式，将大型任務的部分工作分派給多个代理程式、收集其结果并加以整合。此功能仍处于测试版。以下是为軟體建置者提供的文件化设定方式，適用于审阅资料夾中的文件并產生经核查的发现档案。
这会使用 Anthropic 的 Claude Platform API 和 CLI。BIG CHANGE 已检視目前文件；我們未执行设定，也未测试工作流。
## 工作流的功能
一个 [动态工作流](https://platform.claude.com/docs/en/managed-agents/workflow-runs) 是單次执行的一个程式。程式可将工作拆分成多个阶段、并行啟动代理程式执行緒、在阶段之间傳遞结果、重试或处理失敗的分支，并整合结果。例如，第一阶段可检查不同档案，后续阶段再核对发现。主要代理程式会啟动执行作业；伺服器則在背景执行。
这与要求主要代理程式建立多个獨立执行作业不同。工作流执行作业会在單一执行作业中協调子执行緒，并将结果回傳給啟动它的代理程式。一般的工作阶段讯息本身不会啟动执行作业；代理程式会根据任務和系統提示決定何时啟动。Anthropic 表示一个工作阶段可同时有多个开啟中的执行作业，但每个执行作业都有自己的阶段和结果。
## 开始之前
您需要 Claude Console 账户、API 金鑰，以及 Claude Managed Agents 的存取權。Anthropic 表示 API 账户预设已启用此功能。代理程式和工作流端点需要 `managed-agents-2026-04-01` beta 标头。Anthropic 的 SDK 会自动设定此标头；若不使用 SDK 直接呼叫 API，請自行加入。
目前文件仍将 Managed Agents 标示为 [测试版](https://platform.claude.com/docs/en/managed-agents/overview)。Anthropic 的 [发行说明](https://platform.claude.com/docs/en/release-notes/overview) 将公开测试版日期列为 2026 年 4 月 9 日、多代理協调功能列为 5 月 11 日，动态工作流則列为 10 月 9 日。动态工作流也仍处于测试版。日期很重要：「1,000 个代理程式」是目前單次工作流执行的上限，并非新推出的同时啟动 1,000 个代理程式功能。
平台会在伺服器端儲存工作阶段对話记录、沙箱状态和输出。Anthropic 表示 Managed Agents 目前不符合 [零资料保留或 HIPAA 商业夥伴協議涵蓋范圍](https://platform.claude.com/docs/en/managed-agents/overview)。除非貴組織已确认適用的资料規則和设定，否則請勿在工作阶段中放入受管制或機密资料。
## 1. 安裝 CLI 和 SDK
使用作业系統適用的方法，依照 Anthropic 的 `ant` CLI 安裝指南，參考 [Managed Agents 快速入門](https://platform.claude.com/docs/en/managed-agents/quickstart)。例如，文件中的 macOS 指令为：
```sh
brew install anthropics/tap/ant
```
如要使用 Python，請安裝 SDK，并透過环境提供 API 金鑰，而不要将金鑰放入原始碼档案：
```sh
pip install anthropic
export ANTHROPIC_API_KEY="your-api-key"
```
上方的金鑰是佔位值。請将實際值保存在慣用的密碼管理工具或受保護的环境设定中。
## 2. 定義可使用工作流的代理程式
建立 `document-reviewer.md`。其中的 `multiagent` 区塊会启用十月推出的工作流類型。停用子代理程式可明确指定委派方式：此代理程式使用动态工作流，而不是一次性的子代理程式委派。
```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.
```
門檻和审阅指示是您的政策选择，并非 Anthropic 的预设值。請依工作内容和错误成本调整。 `claude-sonnet-5-5` 是范例模型 ID；請选择目前账户可用且符合预算的模型。
建立代理程式并保留系統傳回的 ID：
```sh
ant apply document-reviewer.md
```
CLI 会印出代理程式 ID，并将其记录在 `claude-lock.json`。Managed Agents 将可重複使用的代理程式定義（模型、指示和工具）与工作阶段执行的环境分开。
## 3. 设定沙箱
环境会控制工作阶段的执行位置：Anthropic 管理的云端沙箱，或您基礎架構上的自架沙箱。快速入門的云端范例採用受限网路，并允許套件管理工具：
```yaml
# environment.yaml
name: document-review
config:
type: cloud
networking:
type: limited
allow_package_managers: true
```
使用 `ant apply environment.yaml`套用设定；其 ID 也会儲存在 `claude-lock.json`。若代理程式需要网路存取，請只将必要的主機列入 `allowed_hosts`。在有限网路环境中，这份主機清单也会限制 Managed Agents 的网頁搜索和擷取工具。允許套件管理工具的设定不会将网站加入允許清单。
首次执行时，請使用小型、非敏感的资料夾，并只启用必要工具。内建代理程式工具組包含 shell 和档案操作；加入工具可能擴大代理程式可执行的操作。授予外部系統或憑证存取權之前，請检查文件所述的权限政策和沙箱控制。
## 4. 啟动工作阶段并傳送范圍明确的任務
使用代理程式和环境 ID，透過 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)
```
将兩个 ID 佔位符替换为 `claude-lock.json`中的值。接著透過工作阶段事件串流傳送具體任務。請先啟动串流再傳送事件，才能即时看到执行作业及其進度：
```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}")
```
此范例假设您设定的工作阶段输入方式会在 `/review-set`提供档案。要求代理程式审阅之前，請使用文件所述的输入方式将档案放入工作阶段沙箱。請代理程式将输出写入 `/mnt/session/outputs/`； [Managed Agents 档案文件](https://platform.claude.com/docs/en/managed-agents/files) 说明如何列出工作阶段范圍内的档案并下载。Python SDK 文件所述的读回格式如下：
```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
```
工作阶段閒置后，档案可能要等幾秒才会出现；若尚未看到，請稍候再列出一次。安全的首次试跑可建立含有少量文件的测试资料夾，并手动检查预期结果。范例提示词定義了审阅任務，但不保证代理程式会找出所有問題。
输出契約应严謹到足以稽核。例如：
```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
}
```
这是建議給您工作流使用的结構，并非 Anthropic 提供的结構。請将未解決或无法读取的档案保留为记录，避免缺少结果看起來像是审阅完全无误。
## 5. 检查执行作业及输出
工作流啟动时，事件串流会回報 `workflow_run.created`，包括执行 ID 和工作流宣告的阶段。范例会让每个执行 ID 保持开啟，直到收到相符的 `workflow_run.status_ended`；僅有主要工作阶段閒置，不能证明背景工作流已结束。主要串流会摘要子执行緒状态，而各执行緒自己的事件清单則包含其讯息和错误。范例会按 `workflow_run_id` 列出执行緒，并呈现 `session.error` 事件。請检查是否有重试耗盡（包括 `retry_status.type == "exhausted"`）或其他子执行緒错误，并将受影響档案标示为未解決。
請将输出档視为交付成果，而不是「已完成」这个字。Anthropic 明确警告，即使执行緒工作失敗或无法建立执行緒，执行作业仍可能以 `completed` 结束。开啟 `report.json` ，确认每个输入档都有发现结果或明确的未解決状态、证据摘錄指向正确來源档案，且筆数符合您提供的档案。将小型测试资料夾与您自行预期的结果比較后，再把工作流用于較大的文件集。
若用户端中斷连线，新事件串流只会傳送它开啟后產生的事件。請使用文件列出的事件類型篩选器和分頁，重建過去的工作阶段事件与执行状态。即使主要代理程式閒置，也不要推斷执行作业已完成，因为子执行緒可能仍在工作。所有已觀察到的执行作业结束后，請列出工作阶段范圍内的档案，并使用文件所述 Files API 下载 `/mnt/session/outputs/report.json` 和 `summary.md` 。确认每个提供的档案都有已审阅或未解決记录，且数量相符。范例事件迴圈不会下载或验证報告本身。
## 会影響设計的限制
Anthropic 的 [工作流执行限制](https://platform.claude.com/docs/en/managed-agents/workflow-runs) 目前記載單一执行作业最多可有 64 个工作流执行緒同时運作，但 API 不保证此并行程度，且数值可能变更。1,000 个代理程式的限制計算整个执行期间啟动的代理程式总数，不是同时执行的执行緒数。若達到此总数后工作流仍嘗试啟动代理程式，执行作业会以 `thread_limit_error`结束；失敗代理程式的重试也可能新增执行緒。
执行作业预设持续 24 小时；若其代理程式设定較短时间則会更短。等待用户端的时间也計入，暫停的执行作业仍可能逾时。工作阶段预设最多有 10 个开啟的执行作业，包括閒置作业。工作阶段使用预算適用于所有工作流代理程式；達到预算时，开啟的执行作业会暫停，直到提高或移除预算。請規劃較小的工作單位、将检查点存入档案，并要求核对阶段回報未完成项目，不要假裝已完成审阅。
发生失敗时，請检查 `workflow_run.error` 和受影響的执行緒。 `program_error` 可能表示工作流式碼或子执行緒失敗； `thread_limit_error` 代表達到 1,000 个代理程式的上限； `timeout_error` 代表执行时间上限。若执行作业達到工作阶段预算，請提高或移除预算以恢復执行。若要停止工作流，請要求主要代理程式停止其执行作业；中斷工作阶段回合本身并不是取消执行作业的命令。
## 成本
Anthropic 的 [价格文件](https://platform.claude.com/docs/en/about-claude/pricing) 按所选模型的 Token 费率，以及工作阶段执行时间收取 Managed Agents 费用，费率为 **每个执行中工作阶段每小时 $0.08**。工作阶段状态为 `running`时会累計执行时间；閒置、重新排程和已終止的时间不計费。工作流执行作业沒有额外费用，但执行緒的 Token 使用量会計入工作阶段。工作阶段内呼叫的网頁搜索标价为每 1,000 次搜索 $10。总费用取決于模型、输入与输出 Token、工具及工作阶段执行时间；請在 Console 检查用量，而不要根据 1,000 个代理程式的上限估算。
實務上，先從少量档案开始，确认工作流输出已逐一处理每个档案，检查失敗的执行緒，只有在审阅政策和成本都可接受时才擴大输入。受管理工作流提供協调非同步并行工作的方式，但不会替发现结果背書。
## 重大变化
從 10 月 9 日起，Managed Agents 代理程式可撰写由伺服器跨多个代理程式执行緒和阶段执行的工作流式。建置者可使用此方式進行范圍受限且可稽核的分流工作，同时由主要工作阶段追蹤進度。此功能仍在测试版，已公布的限制不保证每次执行都達到最高并行度或產生正确发现。
## 來源与延伸阅读
- [Claude Managed Agents 概览](https://platform.claude.com/docs/en/managed-agents/overview) — 测试版状态、API 标头、存取權、具状态工作阶段、工具和资料保留限制。
- [开始使用 Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/quickstart) — CLI、SDK、代理程式／环境设定、建立工作阶段和事件串流范例。
- [多代理程式協调](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration) — 启用动态工作流，以及在工作流和子代理程式间做选择。
- [工作流执行作业](https://platform.claude.com/docs/en/managed-agents/workflow-runs) — 执行事件、结果判读、復原、预算和文件列出的限制。
- [工作阶段执行緒](https://platform.claude.com/docs/en/managed-agents/session-threads) — 列出与执行作业相关的子执行緒并读取其事件歷程。
- [工作阶段档案](https://platform.claude.com/docs/en/managed-agents/files) — 掛載输入、输出路徑、工作阶段范圍档案清单和下载。
- [Claude Platform 发行说明](https://platform.claude.com/docs/en/release-notes/overview) — 2026 年 10 月 9 日动态工作流更新及测试版设定。
- [Claude Platform 定价](https://platform.claude.com/docs/en/about-claude/pricing) — Token 計费和工作阶段执行费率。
## Sources
- [Claude Managed Agents 概览](https://platform.claude.com/docs/en/managed-agents/overview) — 目前的测试版状态、API 标头、存取權、具状态工作阶段和资料保留限制。
- [开始使用 Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/quickstart) — CLI 与 SDK 设定、代理程式／环境配置、工作阶段及事件串流范例。
- [多代理程式協调](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration) — 工作流启用方式，以及与子代理程式的差异。
- [工作流执行作业](https://platform.claude.com/docs/en/managed-agents/workflow-runs) — 工作流／执行作业機制、事件、输出状态判读、復原、预算和限制。
- [Claude Platform release notes](https://platform.claude.com/docs/en/release-notes/overview) — 公开测试版的日期紀錄和 2026 年 10 月 9 日动态工作流更新；修正后的标准网址。
- [Claude Platform pricing](https://platform.claude.com/docs/en/about-claude/pricing) — Managed Agents Token 和工作阶段执行费用。
- [Session threads](https://platform.claude.com/docs/en/managed-agents/session-threads) — 列出与执行作业相关的子执行緒并读取其事件歷程。
- [Session files](https://platform.claude.com/docs/en/managed-agents/files) — 掛載输入、输出路徑、工作阶段范圍的档案清单和下载。