ワークフロー実行

「workflow」（ワークフロー）とは、エージェントが多数のエージェントを実行し、それらが返す結果を組み合わせるために書くプログラムです。「workflow run」（ワークフロー実行）とは、1つのワークフローの実行です。Dynamic workflows（動的ワークフロー）は、エージェントがワークフローを書き、実行を開始できるようにする機能です。この機能は、エージェントの multiagent ブロック内の workflows 設定でオンまたはオフにします。

サーバーはワークフローをバックグラウンドで実行します。そのエージェントは、ワークフローが必要とするたびにサーバーが作成するセッションスレッドで作業します。実行は、セッションのイベントストリームで追跡します。実行を開始するのはエージェントだけです。あなたが送信するイベントで実行が終了することはありませんが、セッションをアーカイブすると終了する場合があります。

動的ワークフローの仕組み

セッションが実行するエージェントは、あなたが説明する作業に合わせて各ワークフローを書きます。ワークフローはプログラムです。他のエージェントを実行し、それぞれが返すものを収集し、結果を組み合わせます。これにより、エージェントは数百件のドキュメントのレビューなど、1つの会話には大きすぎるタスクに取り組むことができます。実行中、エージェントは作業を続けることも、ターンを終了することもでき、実行の状況を確認することもできます。

この図は一例を示しています。エージェントが書く各ワークフローには、それぞれ独自のフェーズとエージェントがあります。実行には次の階層があります。

• ワークフロー実行： サーバーはワークフローを1つのワークフロー実行としてバックグラウンドで実行します。1つのセッションで複数の実行を同時に開いておくことができます。
• フェーズ： ワークフローは作業を「phase」（フェーズ）に分割できます。フェーズとは、「Read the contracts」（契約書を読む）のような、実行の名前付きの段階です。実行の進捗は、そのフェーズイベントで追跡します。
• エージェントスレッド： フェーズ内で、プログラムはエージェントを実行します。各エージェントは、プログラムが書いたプロンプトに基づいて、それぞれ独自のセッションスレッドで作業します。実行内のエージェントは、プログラム自身が定義するインラインエージェントか、あなたが workflows.predefined_agents に列挙する事前定義エージェントのいずれかです。各スレッドが示す内容については、実行のスレッドを参照してください。

プログラムは次のことができます。

• エージェントを同時に実行する： プログラムは多数のエージェントを同時に実行できます。これを「fanning out」（ファンアウト）と呼びます。図では、最初のフェーズで3つのエージェントが契約書を読んでいます。
• あるエージェントの結果を別のエージェントに渡す： 各エージェントは結果をプログラムに返します。プログラムはその結果を別のエージェントに渡すことができます。図では、2番目のフェーズのエージェントが、最初の3つが返したものを使って作業します。実行のエージェントは、セッションのサンドボックス内で同じファイルも扱います。
• 次のステップを自ら進める： エージェントの結果は、セッションが実行するエージェントではなく、プログラムに渡されます。プログラムは次にどのエージェントを実行するかを決定し、そのプロンプトを書きます。
• 繰り返しと選択： フェーズ内で、プログラムは作業を繰り返し、エージェントが返したものに基づいて次のステップを選択できます。たとえば、レビューに合格するか、設定された回数を使い切るまで、下書きを修正させることができます。図では、プログラムは2番目のフェーズ内でステップを繰り返すことができます。
• 失敗したエージェントを処理する： エージェントの1つが失敗した場合、プログラムはその失敗を処理するか、それによって実行を終了させることができます。

実行が終了すると、セッションが実行するエージェントは、実行が何をしたかを読むためのターンを得ます。その後、あなたに回答するか、別の実行を開始できます。そのターンが後になる場合や来ない場合については、実行イベントに記載されています。

実行が作業をどのように行うか、たとえば作業をどのように分割するか、エージェントが失敗したときに何をするかを指示できます。実行を使用するタイミングをエージェントに伝えるを参照してください。

実行の状態遷移

実行は、実行中またはアイドル状態で開始します。たとえば予算に達すると、実行中の実行は一時停止してアイドル状態になります。その後、予算を引き上げるか削除すると、中断によっても一時停止している場合を除き、再び実行されます。実行中の実行は、ワークフローが完了したとき、エージェントが実行を停止したとき、実行が失敗したとき、有効期間が過ぎたとき、またはセッションがアーカイブされたときに終了します。アイドル状態の実行も、たとえばエージェントが実行を停止したときやセッションがアーカイブされたときに終了することがあります。

実行は、実行中かアイドル状態かにかかわらず、workflow_run.created イベントから workflow_run.status_ended イベントまでの間、open（開いている）状態です。実行は、たとえばセッションの予算に達して一時停止している間、アイドル状態になります。実行の有効期間はデフォルトで24時間です。エージェントは実行を開始するときに、より短い有効期間を設定できます。実行がクライアントを待っている時間も、その有効期間に含まれます。一時停止しても実行の有効期間の経過は止まらないため、一時停止したままの実行は timeout_error で終了することがあります。次のイベントは、実行の開始、フェーズ、および終了を報告します。予算での一時停止でもイベントが1つ送信されます。中断後の一時停止では、イベントが送信されない場合があります。すべての workflow_run.* イベントには workflow_run_id が含まれ、これが null になるのは、実行が作成されなかった場合の workflow_run.error のみです。

実行イベント

実行イベントは、プライマリスレッドのストリームであるセッションのイベントストリームに届き、セッションのイベントを一覧表示した場合にも返されます。実行イベントは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 を受け取ります。それだけでは実行は終了しません。しかし、それによって実行のスレッドの1つが失敗し、ワークフローがそれによって実行を終了させた場合、実行は 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 でスレッドを停止したり、実行が開いている間にスレッドをアーカイブしたりすることはできません。

• グループ化： 実行のスレッドは、それを通知する session.thread_created イベントと同様に、実行の workflow_run_id を持ちます。その他のスレッドと、それらを通知する 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 は、他の子スレッドと同様に送信されます。スレッド自身のストリームが記録する内容については、セッションスレッドのイベントを参照してください。
• フェーズ： スレッドがどのフェーズで作業しているかを示すイベントやフィールドはなく、1つの実行のスレッドが同じ agent_name を持つこともあります。実行の進捗はフェーズイベントで追跡し、スレッドは session_thread_id で区別してください。
• スレッド制限： 実行のスレッドは、セッションの子スレッド制限の対象外です。
• 実行の開始： 実行を開始するのは、セッションのプライマリスレッド上のエージェントだけです。実行のスレッドで作業しているエージェントは独自の実行を開始できないため、実行が入れ子になることはありません。
• アーカイブ： サーバーは、各スレッドを遅くとも実行の終了までにアーカイブします。スレッドが結果を返した時点、または実行がそのスレッドを使い終えた時点で、より早くアーカイブすることもあります。その時点でスレッドがまだ実行中であるか、クライアントを待っている場合、サーバーはまずそれを停止します。アーカイブされたスレッドは、ステータス terminated でスレッド一覧に残ります。実行のスレッドを自分でアーカイブする必要はありません。実行が開いている間、サーバーがまだアーカイブしていないスレッドをアーカイブするリクエストは、error.details.error_code: "workflow_run_open" とともに 400 を返します。
• 可視性： ワークフローのコードは表示されませんが、このリストの後のヒントで説明するように、エージェントにワークフローを出力するよう依頼できます。また、エージェントが実行を開始および管理するために行うツール呼び出しや、各スレッドがワークフローに返す結果も表示されません。

作業が完了したタイミングを知る

実行が実行中の間は、どのスレッドも作業していないときでも、セッションは 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 を送信します。

実行が開いている間

再接続後に実行の状態を再構築する

各実行の状態は、セッションのイベントから再構築します。ストリームは見逃したものを再生しません。新しい接続は、接続が開いた後に発行されたイベントのみを配信します。そのため、過去のイベントを一覧表示するのように、イベントタイプごとに1つの types[] エントリを指定した types フィルターでイベントを一覧表示してください。next_page が null になるか存在しなくなるまで、各レスポンスの next_page を page として渡します。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 の料金を参照してください。

• 1つの実行の使用量： セッションのスレッドを一覧表示し、実行の workflow_run_id を持つスレッドの usage 内のトークン数を合計します。一覧にはステータスが terminated のアーカイブ済みスレッドも含まれるため、完了した実行のスレッドも数えられます。next_page が null になるか存在しなくなるまで、各レスポンスの next_page を page として渡し、usage が null のスレッドはスキップしてください。代わりにスレッドの list_cost を合計すると、合計にはセッションのランタイムが含まれず、各数値は個別に丸められます。
• 予算に達したとき： 開いているすべての実行が一時停止し、セッションは budget_reached で idle、またはツール呼び出しも待機している場合は requires_action を報告します。各スレッドはすでに開始したモデルリクエストを完了するため、実行は作業中のスレッドごとに1リクエスト分、予算を超えることがあります。予算を引き上げるか削除すると、中断によっても一時停止している場合を除き、予算によって一時停止した実行が再開されます。セッションの使用量にリスト価格のないモデルが含まれる場合は、予算を削除した場合のみ再開されます。リスト価格のないモデルを参照してください。

サーバーは、実行またはフェーズの name を64文字に、description を256文字に短縮します。サーバーには、ここに記載されていないワークフローに関する他の制限とルールがあります。表示される内容は、サーバーが問題を検出するタイミングによって異なります。

セッションは、その全期間を通じて任意の数の実行を開始できます。

レート制限

実行の作業は、組織にすでに設定されている「rate limit」（レート制限）に計上されます。

実行のスレッドの1つからのモデルリクエストがレート制限を受けた場合、またはモデルが過負荷の場合、スレッド自身のストリームが model_rate_limited_error または model_overloaded_error タイプの session.error を受け取ることがあります。

• その retry_status.type が retrying の場合、サーバーはリクエストを再試行しており、スレッドはまだ作業中です。
• exhausted の場合、スレッドは失敗しています。ワークフローがその失敗によって実行を終了させた場合、実行は program_error で終了しますが、これは原因を示しません。原因を見つけるには、失敗したスレッドのイベントを読んでください。

サーバーは、組織のすべてのセッションが1分あたりに行う処理量も制限しています。この制限に達したスレッドは停止し、そのスレッド自身のストリームに、メッセージでレート制限を示す session.error が届きます。エージェントに続行を依頼する前に、1分待ってください。

実行は同じ作業に対して複数のスレッドを作成することがあるため、エージェントが呼び出すツールは2回呼び出しても安全になるようにしてください。