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。