工作流运行

"workflow"（工作流）是智能体编写的一个程序，用于运行多个智能体并合并它们返回的结果。"workflow run"（工作流运行）是一个工作流的一次执行。动态工作流是让智能体能够编写工作流并启动运行的功能。您可以通过智能体 multiagent 块中的 workflows 设置来开启或关闭它。

服务器在后台运行工作流。其智能体在服务器根据工作流需要而创建的会话线程中工作。您可以在会话的事件流上跟踪运行。只有智能体可以启动运行。您发送的任何事件都不会结束运行；归档会话则可以。

动态工作流的工作原理

会话所运行的智能体会针对您描述的工作编写每个工作流。工作流是一个程序：它运行其他智能体，收集每个智能体返回的内容，并合并结果。这样，智能体就可以承担对于单次对话来说过于庞大的任务，例如审阅数百份文档。在运行期间，智能体可以继续工作或结束其轮次，并且可以检查运行的状态。

该图展示了一个示例。智能体编写的每个工作流都有自己的阶段和智能体。一次运行包含以下层级：

• 工作流运行：服务器在后台以一次工作流运行的形式运行工作流。一个会话可以同时有多个处于打开状态的运行。
• 阶段：工作流可以将其工作划分为多个阶段。"phase"（阶段）是运行中一个具名的环节，例如"Read the contracts"。您可以通过阶段事件跟踪运行的进度。
• 智能体线程：在一个阶段中，程序运行智能体。每个智能体在自己的会话线程中工作，处理由程序编写的提示。一次运行中的智能体可以是内联智能体（由程序自行定义），也可以是预定义智能体（由您在 workflows.predefined_agents 中列出）。关于每个线程显示的内容，请参阅运行的线程。

程序可以执行以下操作：

• 同时运行多个智能体：程序可以同时运行许多智能体，这称为"fanning out"（扇出）。在图中，三个智能体在第一阶段阅读合同。
• 将结果从一个智能体传递给另一个智能体：每个智能体将其结果返回给程序。程序可以将该结果传递给另一个智能体。在图中，第二阶段的智能体处理前三个智能体返回的内容。同一运行的各个智能体还会在会话的沙箱中处理相同的文件。
• 自行执行下一步：智能体的结果会返回给程序，而不是返回给会话所运行的智能体。程序决定接下来运行哪些智能体，并编写它们的提示。
• 重复与选择：在一个阶段内，程序可以重复工作，并根据智能体返回的内容选择下一步。例如，它可以让草稿不断修订，直到审阅通过或用完设定的轮数。在图中，程序可以在第二阶段内重复某个步骤。
• 处理失败的智能体：当其中一个智能体失败时，程序可以处理该失败，或让它结束运行。

运行结束后，会话所运行的智能体会获得一个轮次来读取运行所做的工作。然后它可以回答您，或启动另一个运行。运行事件列出了该轮次延后到来或不会到来的情况。

您可以指导运行如何完成工作，例如如何拆分工作以及智能体失败时该怎么做。请参阅告诉智能体何时使用运行。

运行如何在各状态之间转换

运行以运行中或空闲状态开始。例如，达到预算会暂停正在运行的运行，使其变为空闲；随后提高或移除预算会使其再次运行，除非它也因中断而暂停。当工作流完成、智能体停止它、它失败、其生命周期到期或会话被归档时，正在运行的运行就会结束。空闲的运行也可能结束，例如当智能体停止它或会话被归档时。

从 workflow_run.created 事件到 workflow_run.status_ended 事件之间，无论运行处于运行中还是空闲状态，它都是打开的。运行在暂停期间（例如达到会话预算时）处于空闲状态。运行的生命周期默认为 24 小时。智能体在启动运行时可以设置更短的生命周期。运行等待您的客户端所花费的时间也计入该生命周期。暂停不会阻止运行的生命周期流逝，因此一直处于暂停状态的运行可能会以 timeout_error 结束。以下事件报告运行的开始、其阶段以及其结束。因达到预算而暂停时也会发送一个事件。中断后的暂停可能不会发送任何事件。每个 workflow_run.* 事件都包含 workflow_run_id，仅当未创建运行时，它在 workflow_run.error 上才为 null。

运行事件

运行事件会到达会话的事件流（即主线程的流），列出会话的事件时也会返回它们。运行事件不会触发 webhook。来自运行线程的状态事件也会到达同一个流。每个事件都在 session_thread_id 中指明其线程，而运行的线程就是那些 session.thread_created 事件带有该运行 workflow_run_id 的线程。

错误结果形如 {"type": "error", "error": {"type": "timeout_error", "message": "..."}}，其中 message 可以安全记录。将无法识别的 result.type 视为以其他方式结束的运行，将无法识别的 error.type 视为错误。当会话所依赖的某项内容失败时（例如模型、MCP 服务器、凭据或计费），失败线程的流会收到 session.error。这本身不会结束运行。但如果它导致运行的某个线程失败，而工作流让这一情况结束运行，则运行以 program_error 结束。

例如，您询问合同审查智能体 300 份合同中哪些包含控制权变更条款，智能体启动了一个运行：

1. workflow_run.created 将运行命名为"Find change-of-control clauses"，并在 phases 中列出阶段"Read the contracts"和"Reconcile the findings"。随后是 workflow_run.status_running。
2. 阶段事件标记每个阶段，运行创建的每个线程都会发送带有该运行 workflow_run_id 的 session.thread_created。
3. workflow_run.status_ended 到达，带有 result: {"type": "completed"}。
4. 智能体回答"300 份合同中有 41 份包含此条款"，然后 session.status_idle 以 end_turn 到达。

运行的第一个事件列出了其阶段：

{
  "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 }
  ],
  "processed_at": "2026-10-09T14:01:45Z"
}

每个阶段事件通过 workflow_run_phase_id 指明其阶段。它是 phases 中的一个 id，但 API 不保证这一点：

{
  "type": "workflow_run.phase_started",
  "id": "sevt_01def...",
  "workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
  "workflow_run_phase_id": "wrph_01Kd3a1f3",
  "processed_at": "2026-10-09T14:01:46Z"
}

运行的最后一个事件报告其结束方式：

{
  "type": "workflow_run.status_ended",
  "id": "sevt_01ghi...",
  "workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
  "result": { "type": "completed" },
  "processed_at": "2026-10-09T14:09:12Z"
}

运行的线程

一次运行中的每个智能体都在自己的会话线程中工作，该线程由服务器根据工作流的需要创建。您可以像对待任何子线程一样列出、读取和流式传输运行的线程，并从主事件流中回答它们的工具调用。要停止它们，请让智能体停止运行（请参阅在有打开的运行时中断会话）。您无法通过 ID 停止某个线程，也无法在其运行打开时归档它。

• 分组：运行的线程带有该运行的 workflow_run_id，宣告该线程的 session.thread_created 事件也是如此。其他线程以及宣告它们的 session.thread_created 事件的 workflow_run_id 设置为 null。
• 智能体：agent 显示线程所运行的智能体。对于您在 multiagent.workflows.predefined_agents 中列出的智能体，agent 包含该智能体的 id 和 version，与您列出的子智能体的线程相同。对于工作流定义的智能体（内联智能体），agent 的 type 为 inline，且没有 id 或 version。它使用工作流编写的系统提示，而不是会话智能体的系统提示。它还具有工作流为其指定的名称和描述；如果工作流未指定名称，服务器会分配一个。它使用会话智能体（即会话所运行的智能体）的模型。它的工具、MCP 服务器和技能是会话智能体的子集。它会获得全部这些内容，但 API 不保证这一点。它的工具保留各自的权限策略。
• 线程共享的内容：运行的线程在会话的沙箱中工作，因此每个线程都处理相同的文件。这包括会话挂载的记忆存储中的文件。工作流定义的智能体使用会话为其 MCP 服务器解析的凭据来使用这些服务器。每个线程都有自己的对话历史。
• 事件：运行线程的 session.thread_created、session.thread_status_running、session.thread_status_idle 和 session.thread_status_terminated 事件也会到达主事件流（请参阅运行事件）。其消息事件保留在它自己的流上。其线程 webhook 的发送方式与任何子线程相同。关于线程自身的流记录了什么，请参阅会话线程事件。
• 阶段：没有任何事件或字段说明线程在哪个阶段工作，并且同一运行的线程可能具有相同的 agent_name。请通过阶段事件跟踪运行的进度，并通过 session_thread_id 区分其线程。
• 线程限制：运行的线程不受会话的子线程限制约束。
• 启动运行：只有会话主线程上的智能体可以启动运行。在运行线程中工作的智能体无法启动自己的运行，因此运行不会嵌套。
• 归档：服务器最迟在运行结束时归档每个线程。一旦线程返回其结果或运行不再需要它，服务器可以更早地归档它。如果此时线程仍在运行或正在等待您的客户端，服务器会先停止它。已归档的线程保留在线程列表中，状态为 terminated。您无需自行归档运行的线程。在运行打开期间，归档服务器尚未归档的线程的请求会返回 400，并带有 error.details.error_code: "workflow_run_open"。
• 可见性：您看不到工作流的代码，但可以按照此列表后的提示所述，向智能体索要工作流。您也看不到智能体为启动和管理运行而进行的工具调用，或每个线程返回给工作流的结果。

了解工作何时完成

当运行处于运行中时，即使其线程都没有在工作，会话也应保持 running。当没有线程在工作且有线程在等待您的客户端时，会话会以 requires_action 变为 idle。空闲本身并不意味着工作已完成。当以下两项都成立时，工作才算完成：

1. 您看到创建的每个运行都有其 workflow_run.status_ended。
2. 此后，一个 stop_reason 为 end_turn 的 session.status_idle 到达，并且它不是由您自己的请求（例如中断）引起的。中断后，只计算在您下一条 user.message 或 user.define_outcome 之后到来的空闲。

• 已暂停的运行：已暂停的运行不会使会话保持 running，因此会话可能在运行仍打开时变为空闲。例如，在达到预算时，会话以 budget_reached 变为空闲。在运行结束之前，工作并未完成。
• 另一个运行：智能体在读取结果时可以启动新的运行，因此请再次检查。
• 结果：如果您定义了结果，则在运行打开期间（无论处于运行中还是空闲状态）不会开始评估。智能体读取运行结果的那个轮次可以开始评估。
• retries_exhausted：智能体的轮次因错误而失败：重试次数已用尽，或者该错误无法重试，例如计费失败。当此空闲到来时，运行可能仍在运行中。如果某个运行已结束而智能体尚未读取其结果，服务器会在没有您输入的情况下启动一个新轮次。会话会再次变为 running，因此请等待下一次空闲。如果会话保持空闲，请读取在它之前到来的 session.error 并修复原因。然后发送 user.message，或自行读取每个运行的 result。

跟踪运行

此示例跟踪一个会话，从您的消息到智能体的回答。它打开流并发送消息。然后执行以下操作：

• 跟踪每个运行，从其 workflow_run.created 到其 workflow_run.status_ended，并在每个阶段开始时打印该阶段。
• 回答自定义工具调用：在每个 agent.custom_tool_use 到达时进行回答，因为运行的线程可能在会话保持 running 时等待您的客户端。如果您的智能体的工具要求确认，请添加一个分支，回答每个 evaluated_permission 为 ask 的 agent.tool_use 或 agent.mcp_tool_use。示例中没有这样的分支，因为允许所有调用的分支会把 always_ask 变成始终允许。
• 停止：当工作完成时停止：没有打开的运行，并且会话以 end_turn 变为空闲。如果会话终止，它也会停止。当空闲的停止原因不是 requires_action 而是其他原因（例如 budget_reached、retries_exhausted 或 refusal）时，它会打印原因并停止，因此请在您自己的代码中处理这些情况。即使服务器即将自行启动新轮次，它也会在 retries_exhausted 时停止。在 requires_action 时，以及在运行打开期间的 end_turn 时，它会继续等待。

open_runs: dict[str, str] = {}  # workflow_run_id -> run name
phase_names: dict[tuple[str, str], str] = {}  # (run ID, phase ID) -> phase name

# 先打开流，再发送用户消息
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": "Which contracts in /contracts have a change-of-control clause?",
                    },
                ],
            },
        ],
    )

    for event in stream:
        match event.type:
            case "workflow_run.created":
                open_runs[event.workflow_run_id] = event.name
                for phase in event.phases:
                    phase_names[event.workflow_run_id, phase.id] = phase.name
                print(f"Run started: {event.name}")
            case "workflow_run.phase_started":
                phase_id = event.workflow_run_phase_id
                key = (event.workflow_run_id, phase_id)
                print(f"  Phase: {phase_names.get(key, phase_id)}")
            case "workflow_run.status_ended":
                name = open_runs.pop(event.workflow_run_id, event.workflow_run_id)
                print(f"Run ended: {name} ({event.result.type})")
            case "agent.custom_tool_use":
                # 事件到达时进行应答。运行的线程可能会等待您的
                # 客户端，而会话保持运行状态。
                result = call_tool(event.name, event.input)
                try:
                    client.beta.sessions.events.send(
                        session_id,
                        events=[
                            {
                                "type": "user.custom_tool_result",
                                "custom_tool_use_id": event.id,
                                "content": [{"type": "text", "text": result}],
                            },
                        ],
                    )
                except anthropic.BadRequestError as error:
                    # 如果结果来得太晚（在服务器归档该调用的线程之后），
                    # 服务器会拒绝该结果。请继续跟踪该运行。
                    print(f"  Answer to {event.name} refused: {error.message}")
            case "session.status_idle":
                # 当所有运行都已结束且智能体已完成其轮次时即完成
                if not open_runs and event.stop_reason.type == "end_turn":
                    break
                # 带有 requires_action 的 idle 会等待您的客户端，因此请继续读取。
                # 遇到任何其他停止原因时，打印该原因并停止。
                if event.stop_reason.type not in ("end_turn", "requires_action"):
                    print(f"Session idle: {event.stop_reason.type}")
                    break
            case "session.status_terminated":
                break

在有打开的运行时中断会话

发送不带 session_thread_id 或带有主线程 ID 的 user.interrupt。它会停止智能体的轮次，但不会结束任何运行。会话的运行可能会暂停或继续运行，而它们的事件可能不会显示是哪种情况。已暂停运行的生命周期会继续流逝，因此运行可能在暂停期间以 timeout_error 结束。

• 等待中的工具调用：中断后，运行线程的工具调用可能仍在等待您的客户端。请逐一回答。要取消要求确认的调用，请拒绝它。要取消自定义工具调用，请发送一个 is_error 设置为 true 的结果，并在 content 中附上说明原因的文本。当会话以 requires_action 处于 idle 状态时，user.message 会返回 400，因此请先回答这些调用。
• 停止运行：发送一条 user.message，要求智能体停止其运行。已停止的运行以 result {"type": "stopped"} 结束。当会话以 budget_reached 处于 idle 状态时，在您提高或移除预算之前，user.message 会返回 400。提高或移除预算还会恢复因预算而暂停的运行，除非这些运行也因该中断而暂停。
• 继续：发送一条 user.message，要求智能体继续其运行。中断后，运行可能会等待这条消息。如果会话以 budget_reached 处于 idle 状态，请先提高或移除预算。
• 运行结果：在中断后结束的运行仍会发送 workflow_run.status_ended。

运行打开期间

重新连接后重建运行状态

根据会话的事件重建每个运行的状态。流不会重放您错过的内容：新连接只会传递在其打开之后发出的事件。因此，请使用 types 过滤器列出事件，每种事件类型对应一个 types[] 条目，如列出过去的事件中所述。将每个响应的 next_page 作为 page 传递，直到 next_page 为 null 或缺失。workflow_run.created、workflow_run.status_running、workflow_run.status_idle 和 workflow_run.status_ended 给出每个运行的状态，但中断后暂停的运行可能仍显示为运行中。workflow_run.phase_started 和 workflow_run.phase_ended 用于重建进度。尚无状态事件的运行还未开始执行。没有列出运行的端点。

预算和限制

运行的模型请求计入会话的预算。运行本身没有单独的价格。其智能体使用的令牌与会话的其他令牌一样，按各模型的费率计费。关于会话的所有费用，请参阅 Claude Managed Agents 定价。

• 单个运行的用量：列出会话的线程，并将带有该运行 workflow_run_id 的线程的 usage 中的令牌计数相加。该列表包括已归档的线程（其状态为 terminated），因此已完成运行的线程也会被计入。将每个响应的 next_page 作为 page 传递，直到 next_page 为 null 或缺失，并跳过 usage 为 null 的线程。如果您改为将线程的 list_cost 相加，总数将不包括会话运行时间，并且每个数值都是单独四舍五入的。
• 达到预算时：每个打开的运行都会暂停，会话报告以 budget_reached 处于 idle 状态，如果同时有工具调用在等待，则报告 requires_action。每个线程会完成它已经开始的模型请求，因此运行可能会以每个工作线程一个请求的幅度超出预算。提高或移除预算会恢复因预算而暂停的运行，除非这些运行也因中断而暂停。如果会话的用量包括没有标价的模型，则只有移除预算才能恢复；请参阅没有标价的模型。

服务器会将运行或阶段的 name 截短为 64 个字符，将其 description 截短为 256 个字符。服务器对工作流还有此处未列出的其他限制和规则。您看到的情况取决于服务器何时发现问题：

一个会话在其生命周期内可以启动任意数量的运行。

速率限制

运行的工作计入您的组织已有的"rate limits"（速率限制）。

当来自运行某个线程的模型请求受到速率限制，或模型过载时，该线程自己的流可能会收到类型为 model_rate_limited_error 或 model_overloaded_error 的 session.error：

• 如果其 retry_status.type 为 retrying，则服务器正在重试该请求，线程仍在工作。
• 如果为 exhausted，则线程已失败。如果工作流让该失败结束运行，运行将以 program_error 结束，而它不会指明原因。请读取失败线程的事件来查找原因。

服务器还会限制您组织的所有会话每分钟的工作量。达到此限制的线程会停止，并在其自己的流上收到一个消息中指明速率限制的 session.error。请等待一分钟，然后再让智能体继续。

一个运行可能会为同一项工作创建多个线程，因此请确保您的智能体调用的工具可以安全地被调用两次。