先給結論:動態工作流收走的是「等模型說完再解析」,進度合約仍是一串 JSON 事件。2026 年 10 月 9 日,Claude Managed Agents 開放動態工作流 beta,請求頭是 managed-agents-2026-04-01。代理自己寫一段程式,伺服器在後臺跑成一次 workflow run。你要跟的不是最終那句自然語言,而是會話事件流上的 workflow_run.*。
這篇按 2026 年 10 月 12 日寫,依據當天仍有效的發布說明和 Workflow runs 頁。本站已有《Agents API 與 JSON Schema》《MCP、Skills、Tools、Subagents》。本文只回答:幾百份材料被拆開跑的時候,哪一份 JSON 才算這次執行結束,哪一份不能當成成功。
10 月 9 日開啟了什麼
開關寫在代理定義的 multiagent 上。型別用 multiagent_20261001 時,subagents 和 workflows 預設都開。只要動態工作流、不要委託,把 subagents 設成 disabled。已經建好的代理放進 workflows.predefined_agents。工作流自己現寫的代理是 inline agent,預設也能用。
{
"type": "multiagent_20261001",
"workflows": { "type": "enabled" }
}
一次執行有三層。最外層是後臺的 workflow run,一個會話可以同時開好幾次。中間是階段,名字由模型寫,例如「讀合約」。最裡層是代理執行緒:程式可以同時起多個代理,把上一個的結果傳給下一個,也可以在階段內部迴圈。失敗可以由程式自己接住,也可以讓它結束整次執行。只有代理能發起執行。你發出去的事件結束不了它;歸檔會話可以。
這些事件走會話事件流,列出會話事件時也能看見。它們不觸發 webhook。預設壽命 24 小時,代理可以設得更短。等你的客戶端、停在預算上,時間照樣走。停著不動也可能以 timeout_error 結束。
created 才是階段名單
workflow_run.created 帶 workflow_run_id(wrun_ 開頭)、name、description,以及 phases。每個階段有 id(wrph_ 開頭)、name、description。沒有描述時 description 是 null。phases 一定在,但可以是空陣列。名字是模型寫的,也可能是伺服器補的,會重複你請求裡的詞。不要把它們當穩定列舉。
{
"type": "workflow_run.created",
"id": "sevt_01abc",
"workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
"name": "Find change-of-control clauses",
"description": "Reads each contract and lists those that have the clause.",
"phases": [
{
"id": "wrph_01Kd3a1f3",
"name": "Read the contracts",
"description": "Reads each contract for the clause."
},
{ "id": "wrph_01Kd3b7c9", "name": "Reconcile the findings", "description": null }
]
}
後面的 phase_started 和 phase_ended 只有 workflow_run_phase_id,沒有階段名。名字要回 created.phases 裡按 id 查。phase_ended 用 phase_started_id 對上那條開始事件,它也不說明這一階段的活做完沒有。說明書寫階段一次一個、按 phases 順序、每個最多一次,同時寫明 API 不保證這一點。要能接住:同時開著的階段、不在名單裡的階段、名單上卻從沒開始的階段。每個開始過的階段都會在 status_ended 之前結束。
completed 不是幹成了
workflow_run.status_ended 一定是這次執行 workflow_run.* 的最後一條,裡面有 result。執行從 created 到這條之間都算開著,中間可以是 running,也可以是 idle。
| result | 含義 |
|---|---|
| type 為 completed | 程式跑完了。不表示每份材料都成功。執行緒可以失敗,執行緒也可以建不出來。 |
| type 為 stopped | 代理停了執行,或會話被歸檔。事件不區分是哪一種。 |
| error.timeout_error | 到了壽命。預設 24 小時,或代理自己設的更短時間。 |
| error.program_error | 工作流程式碼失敗、違反規則,或某個執行緒失敗且程式讓它結束整次執行。 |
| error.thread_limit_error | 超過一次工作流能啟動的代理數量。 |
| error.unknown_error | 伺服器續不上,或碰到其他服務端限制。 |
錯誤結果的形狀是 {"type":"error","error":{"type":"timeout_error","message":"..."}}。message 可以記日誌。認不出的 result.type 當成「以別的方式結束」。認不出的 error.type 當成錯誤。
workflow_run.error 會在 status_ended 之前到達,帶同樣的錯誤。它不是結束。workflow_run_id 為 null 表示執行根本沒建起來。否則要繼續跟,直到 status_ended。模型、MCP、憑據、帳單這一類失敗先出現在失敗執行緒的 session.error,本身不結束執行;若因此讓執行緒失敗、程式又允許這次失敗收場,執行才以 program_error 結束。
執行緒上沒有階段名
執行裡的每個代理佔一條會話執行緒。宣佈它的 session.thread_created 帶這次的 workflow_run_id。其他執行緒這個欄位是 null。沒有任何事件或欄位說這條執行緒屬於哪個階段,同一次執行裡 agent_name 還可以重複。進度看階段事件,執行緒用 session_thread_id 區分。
你事先列在 predefined_agents 裡的代理,執行緒上的 agent 有 id 和 version。工作流自己定義的 inline agent,type 是 inline,沒有這兩個欄位。它用的是會話代理的模型。工具、MCP、技能是會話代理的子集,說明書寫「會拿到全部」,同時寫明 API 不保證。許可權策略跟著工具走。執行緒共享會話沙箱裡的同一批檔案,對話歷史各自一份。
你不能按執行緒 ID 停掉其中一條,執行還開著時也不能歸檔它。要停,讓代理停整次執行。執行開著時,自定義工具呼叫可以在會話仍是 running 時到達。不要乾等 session.status_idle。evaluated_permission 為 ask 的 agent.tool_use 或 agent.mcp_tool_use 一到就回答。
上線前先核的四份 JSON
- 代理上的 multiagent。型別是
multiagent_20261001,workflows.type是enabled。只想要工作流時,subagents顯式disabled。 - 一條 workflow_run.created。
phases在,id 以wrph_開頭。空陣列也合法。名字不要寫進你的校驗白名單。 - 一條 status_ended。先看
result.type。completed之後還要讀各執行緒事件,才知道有沒有失敗的材料。 - 階段開始和結束的配對。用
phase_started_id對上,階段名從 created 的phases查。缺名字不是解析壞了。
用本機 JSON 工具對事件
把 beta 開啟之前,在瀏覽器裡攤開三份文字:代理定義裡的 multiagent、一條 workflow_run.created、一條 workflow_run.status_ended。
- JSON 校驗 — 事件是不是合法 JSON;
result是否只有你認得出的type。 - JSONPath —
$.phases[*].id抽出階段 id,再和workflow_run_phase_id對。 - JSON Diff — 對比 created 裡的階段名單和你後來收到的 phase 事件,看有沒有名單外的 id。
資料不離開瀏覽器。事件看平了,再讓代理開始寫工作流。伺服器會在後臺跑程式;你的成功條件不應只寫成 result.type == completed。
常見問題 FAQ
這是正式版嗎?不寫 beta 頭可以嗎?
截至 2026 年 10 月 12 日仍是 beta。請求要帶 managed-agents-2026-04-01。multiagent 型別用 multiagent_20261001,workflows 設為 enabled。
result.type 為 completed,是不是每份材料都成功了?
不是。completed 只表示工作流程式跑完。執行緒可以失敗,也可以建不出來。失敗要到各執行緒自己的事件裡看。
收到 workflow_run.error 就可以收場嗎?
不可以。它出現在 status_ended 之前,不是結束。workflow_run_id 為 null 表示執行沒建起來。否則要等到 status_ended。
phase_started 裡為什麼沒有階段名?
名字只在 workflow_run.created 的 phases 裡。用 workflow_run_phase_id 回去查。phase_ended 用 phase_started_id 對上開始事件。
我能發一條事件把某條執行緒停掉嗎?
不能。執行開著時不能按執行緒 ID 停,也不能歸檔那條執行緒。要讓代理停整次執行。你發出的事件結束不了執行;歸檔會話可以。
和 MCP 的 tools/list 是同一份 JSON 嗎?
不是。tools/list 是工具發現。這篇的合約是會話事件流上的 workflow_run 事件。inline 代理的工具是會話代理工具的子集,欄位不是另一份 tools/list。
總結
動態工作流把「幾百份材料」收成後臺程式,進度仍是 JSON 事件。10 月 9 日的 beta 用 multiagent_20261001 開啟。created 給出階段名單,status_ended 才是結束,completed 不代表每條執行緒都成功。error 事件要等後面的結束事件。階段名不在 phase 事件上,要回 created 查。
先在本機把 multiagent、created 和 status_ended 看平,再讓代理寫工作流。程式會在後臺跑;成功條件不應只剩一個 completed。