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) — 掛載輸入、輸出路徑、工作階段範圍的檔案清單和下載。