Claude 動態工作流上線後,為什麼進度還是 JSON?從 multiagent_20261001 到 workflow_run.status_ended

截至 2026 年 10 月 12 日:10 月 9 日 beta 讓 Managed Agents 自己寫工作流。進度不在最終那句回答裡,而在 workflow_run 事件。completed 只表示程式跑完,不表示每條執行緒都成功。

先給結論:動態工作流收走的是「等模型說完再解析」,進度合約仍是一串 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

  1. 代理上的 multiagent。型別是 multiagent_20261001,workflows.type 是 enabled。只想要工作流時,subagents 顯式 disabled。
  2. 一條 workflow_run.created。phases 在,id 以 wrph_ 開頭。空陣列也合法。名字不要寫進你的校驗白名單。
  3. 一條 status_ended。先看 result.type。completed 之後還要讀各執行緒事件,才知道有沒有失敗的材料。
  4. 階段開始和結束的配對。用 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。