工作流程執行

「Workflow」（工作流程）是代理撰寫的程式，用來執行多個代理並合併它們傳回的結果。「Workflow run」（工作流程執行）是一個工作流程的一次執行。Dynamic workflows（動態工作流程）是讓代理能撰寫工作流程並啟動執行的功能。您可以透過代理 multiagent 區塊中的 workflows 設定來開啟或關閉它。

伺服器會在背景執行工作流程。其代理在「session threads」（工作階段執行緒）中工作，這些執行緒由伺服器依工作流程的需要建立。您可以在工作階段的「event stream」（事件串流）上追蹤執行。只有代理能啟動執行。您傳送的任何事件都不會結束執行；封存工作階段則可以。

動態工作流程的運作方式

工作階段所執行的代理會針對您描述的工作撰寫每個工作流程。工作流程是一個程式：它會執行其他代理、收集每個代理傳回的內容，並合併結果。如此一來，代理就能承擔對單一對話而言過於龐大的任務，例如審閱數百份文件。在執行期間，代理可以繼續工作或結束其回合，也可以查看執行的狀況。

此圖顯示一個範例。代理撰寫的每個工作流程都有自己的階段與代理。一個執行包含以下層次：

• 工作流程執行： 伺服器會在背景執行工作流程，作為一個工作流程執行。一個工作階段可以同時開啟多個執行。
• 階段： 工作流程可以將其工作劃分為「phases」（階段）。階段是執行中一個具名的環節，例如「Read the contracts」。您可以透過階段事件追蹤執行的進度。
• 代理執行緒： 在一個階段中，程式會執行代理。每個代理都在自己的工作階段執行緒中，依據程式撰寫的提示工作。執行中的代理可以是「inline agent」（內嵌代理），由程式自行定義；也可以是「predefined agent」（預先定義代理），由您在 workflows.predefined_agents 中列出。關於每個執行緒會顯示的內容，請參閱執行的執行緒。

程式可以執行以下操作：

• 同時執行多個代理： 程式可以同時執行許多代理，這稱為「fanning out」（扇出）。在圖中，三個代理在第一個階段閱讀合約。
• 將結果從一個代理傳遞給另一個代理： 每個代理都會將其結果傳回給程式。程式可以將該結果傳遞給另一個代理。在圖中，第二個階段的代理會使用前三個代理傳回的內容進行工作。執行中的代理也會在工作階段的沙箱中處理相同的檔案。
• 自行採取下一步： 代理的結果會傳給程式，而不是傳給工作階段所執行的代理。程式會決定接下來執行哪些代理，並撰寫它們的提示。
• 重複與選擇： 在一個階段內，程式可以重複工作，並根據代理傳回的內容選擇下一步。例如，它可以讓草稿持續修訂，直到審閱通過或用完設定的輪數為止。在圖中，程式可以在第二個階段內重複某個步驟。
• 處理失敗的代理： 當其中一個代理失敗時，程式可以處理該失敗，或讓它結束執行。

執行結束時，工作階段所執行的代理會獲得一個回合來閱讀執行所做的事。接著它可以回答您，或啟動另一個執行。執行事件列出了該回合延後到來或不會到來的情況。

您可以引導執行如何完成工作，例如如何拆分工作，以及代理失敗時該怎麼做。請參閱告訴代理何時使用執行。

執行如何在各狀態之間轉換

執行以「running」（執行中）或「idle」（閒置）狀態開始。例如，達到預算會暫停執行中的執行，使其變為閒置；接著提高或移除預算會使其再次執行，除非它也因中斷而暫停。當工作流程完成、代理停止它、它失敗、其存續時間已過，或工作階段被封存時，執行中的執行就會結束。閒置的執行也可能結束，例如當代理停止它或工作階段被封存時。

從 workflow_run.created 事件到 workflow_run.status_ended 事件之間，無論執行是執行中還是閒置，它都處於開啟狀態。執行在暫停時為閒置，例如在達到工作階段的預算時。執行的存續時間預設為 24 小時。代理在啟動執行時可以設定較短的存續時間。執行等待您的用戶端所花費的時間會計入該存續時間。暫停不會停止執行存續時間的流逝，因此持續暫停的執行可能會以 timeout_error 結束。以下事件會回報執行的開始、其階段以及其結束。在預算處暫停也會傳送一個事件。中斷後的暫停可能不會傳送任何事件。每個 workflow_run.* 事件都包含 workflow_run_id，只有在未建立執行時的 workflow_run.error 上，其值才會是 null。

執行事件

執行事件會出現在工作階段的事件串流上，也就是主要執行緒的串流，列出工作階段的事件時也會傳回它們。執行事件不會觸發 webhooks。來自執行之執行緒的狀態事件也會出現在同一個串流上。每個事件都會在 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 事件也會出現在主要串流上（請參閱執行事件）。其訊息事件則保留在它自己的串流上。其執行緒 webhooks 的傳送方式與任何子執行緒相同。關於執行緒自身串流所記錄的內容，請參閱工作階段執行緒事件。
• 階段： 沒有任何事件或欄位會說明執行緒在哪個階段中工作，且同一個執行的執行緒可能具有相同的 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":
                # 事件抵達時再回應。run 的執行緒可能會等待您的
                # 用戶端，而工作階段仍保持執行中。
                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:
                    # 若結果太晚送達（在伺服器封存該呼叫的執行緒之後），
                    # 伺服器會拒絕該結果。請繼續追蹤該 run。
                    print(f"  Answer to {event.name} refused: {error.message}")
            case "session.status_idle":
                # 當所有 run 皆已結束且代理已完成其回合時即完成
                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 可重建進度。尚無任何狀態事件的執行表示尚未開始執行。沒有任何端點會列出執行。

預算與限制

執行的模型請求會計入工作階段的預算。執行本身沒有價格。其代理使用的 token 會像工作階段的其他 token 一樣，依各模型的費率計費。關於工作階段的所有費用，請參閱 Claude Managed Agents 定價。

• 單一執行的用量： 列出工作階段的執行緒，並加總帶有該執行之 workflow_run_id 的執行緒在 usage 中的 token 數量。清單包含已封存的執行緒（其狀態為 terminated），因此已完成之執行的執行緒也會被計入。將每個回應的 next_page 作為 page 傳遞，直到 next_page 為 null 或不存在為止，並略過 usage 為 null 的執行緒。如果您改為加總執行緒的 list_cost，總計會遺漏工作階段執行時間，且每個數字都會分別四捨五入。
• 達到預算時： 每個開啟的執行都會暫停，且工作階段會回報 idle 並帶有 budget_reached，若同時有工具呼叫在等待，則為 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。請等待一分鐘後再要求代理繼續。

執行可能會為同一項工作建立多個執行緒，因此請確保您的代理所呼叫的工具可以安全地被呼叫兩次。