Managed Agentsのworkflow runを追う — 状態遷移・イベント・完了判定

Managed Agentsのworkflow runは、エージェントが書いたワークフロー(プログラム)をサーバーがバックグラウンドで実行する単位です。クライアントからrunを始めることも止めることもできません。できるのは、セッションのイベントストリームでrunを追うことです。

この記事は、その追い方をまとめます。runが取る3つの状態、流れてくるイベント、「作業が終わった」と言える条件、切断後の状態復元、上限値の順に見ていきます。この機能はbetaで、リクエストには managed-agents-2026-04-01 のbetaヘッダーが付きます。

workflow runとは何か

workflowは、エージェントが多数のエージェントを走らせて結果をまとめるために書くプログラムです。workflow runはその1回分の実行を指します。dynamic workflowsは、エージェントにワークフローを書かせてrunを始めさせる機能の名前です。

オン・オフはエージェント定義の multiagent ブロックにある workflows 設定で切り替えます。multiagent_20261001 タイプでは subagents と workflows がどちらも既定で有効です。設定の詳細はManaged Agentsでマルチエージェントを編成する方法で扱っています。Claude Code側の同じ発想の機能はダイナミックワークフローとはにあります。

runは3つの層でできています。

ワークフローの中では、エージェントの並列実行(fan out)、結果の受け渡し、繰り返しと分岐、エージェント失敗時の処理を書けます。各エージェントの結果はプログラムに戻り、セッションを動かしている主エージェントには戻りません。次にどのエージェントを動かすかはプログラムが決めます。

runが終わると、主エージェントに結果を読む番が回ります。その上で、ユーザーへ答えるか、次のrunを始めます。

runの状態はrunning・idle・endedの3つ

runはrunningかidleで始まり、最後はendedで終わります。

予算到達で止まったrunは、予算を引き上げるか外せば再開します。ただし割り込み(interrupt)でも止まっていた場合は、予算だけでは戻りません。

runがopenなのは、workflow_run.created から workflow_run.status_ended までです。runningかidleかは問いません。

runの寿命は既定で24時間で、エージェントが開始時にもっと短く設定することもあります。クライアントの応答待ちの時間も寿命に数えます。一時停止中も寿命は進むので、止まったままのrunは timeout_error で終わることがあります。

runイベントを読む

runのイベントは、主スレッドのイベントストリームに届きます。セッションのイベント一覧にも含まれます。webhookは発火しません。runのスレッドの状態イベントも同じストリームに流れ、session_thread_id でどのスレッドか分かります。

押さえておきたい癖がいくつかあります。

• phaseイベントにはphaseの名前がありません。workflow_run.created の phases から workflow_run_phase_id で引きます。
• phaseは順番に、1回ずつ動くのが通常です。ただしAPIはこれを保証しません。複数のphaseが同時にopenなこと、phases に無いphaseが現れること、宣言されたphaseが一度も始まらないことを、完了するrunでも想定しておきます。
• phaseの終了イベントは、そのphaseの仕事が成功したかを教えません。startとの対応は phase_started_id で取ります。
• workflow_run.error は status_ended の前に届きます。workflow_run_id が null なら、runは作られていません。

resultの種類

status_ended の result が終わり方を示します。

ここで誤解しやすいのが completed です。スレッドの作業が失敗していても、スレッドが作れなかった場合でも、runは completed で終わることがあります。completed は「プログラムが終わった」という意味で、「仕事に合格した」という意味ではありません。失敗した作業を探すには、runに属する各スレッドのイベントを読みます。

result.type や error.type が見知らぬ値でも、落とさない作りにしておきます。未知の result.type は「別の終わり方をしたrun」、未知の error.type は単にエラーとして扱います。

例: 300件の契約書を読むrun

契約書レビュー用のエージェントに「300件のうち、支配権変更条項があるのはどれか」と尋ねたとします。公式の流れは次のとおりです。

1. workflow_run.created がrun名「Find change-of-control clauses」とphase「Read the contracts」「Reconcile the findings」を運ぶ。続いて status_running が届く。
2. phaseイベントが段階を区切り、runがスレッドを作るたびに、runの workflow_run_id つきで session.thread_created が届く。
3. workflow_run.status_ended が result: {"type": "completed"} で届く。
4. エージェントが「300件中41件です」と答え、session.status_idle が end_turn で届く。

「作業が終わった」を見分ける

runが走っている間、セッションは running のままです。スレッドが1つも動いていなくても、そうです。スレッドがクライアントの応答を待っているときは、requires_action つきでidleになります。idleになっただけでは、作業の完了を意味しません。

完了と言えるのは、次の2つが両方成り立つときです。

1. 作成を見たrunのすべてに workflow_run.status_ended が届いている
2. その後に、stop_reason が end_turn の session.status_idle が届いている(自分のinterruptが原因のidleは数えない)

idleの理由ごとの注意点も押さえておきます。

• 予算到達: 一時停止中のrunはセッションをrunningに保たないので、セッションはidleになれます(budget_reached)。runが終わるまで作業は終わっていません。
• 別のrun: 主エージェントは結果を読んだ後に新しいrunを始められます。完了判定はそのたびにやり直します。
• outcomeの評価: アウトカムを定義していても、runがopenな間は評価が始まりません。runningかidleかは関係ありません。
• retries_exhausted: 主エージェントのターンがエラーで失敗した場合です。runが終わっていて、主エージェントがまだ結果を読んでいなければ、サーバーが入力なしで新しいターンを始めます。セッションが再びrunningになるので、次のidleを待ちます。idleのまま動かなければ、その手前の session.error を読んで原因を直します。

完了判定を書く

公式のサンプルは、workflow_run.created でopenなrunを記録し、status_ended で外し、openが0件のときの end_turn で止まります。同じ考え方を、ストリームでも一覧取得でも使える状態更新関数にすると、再接続時に同じコードを使い回せます。次は、公式のサンプルのロジックに沿って書いた一例です。

from dataclasses import dataclass, field
 
 
@dataclass
class RunBook:
    open_runs: dict[str, str] = field(default_factory=dict)  # run_id -> name
    phase_names: dict[tuple[str, str], str] = field(default_factory=dict)
    ended: dict[str, str] = field(default_factory=dict)  # run_id -> result type
 
    def apply(self, event) -> None:
        match event.type:
            case "workflow_run.created":
                self.open_runs[event.workflow_run_id] = event.name
                for phase in event.phases:
                    self.phase_names[event.workflow_run_id, phase.id] = phase.name
            case "workflow_run.status_ended":
                self.open_runs.pop(event.workflow_run_id, None)
                self.ended[event.workflow_run_id] = event.result.type
 
    def is_done(self, idle_event) -> bool:
        # 全 run が ended で、end_turn の idle が来たときだけ完了
        return not self.open_runs and idle_event.stop_reason.type == "end_turn"

is_done に渡すidleは、自分が送ったinterruptが原因のものを除きます。interruptの後は、次の user.message か user.define_outcome より後に来たidleだけを数えます。

runのスレッドと、runがopenな間にできないこと

runの各エージェントは、サーバーが作るセッションスレッドで動きます。一覧、読み取り、ストリームは通常の子スレッドと同じです。

ワークフローのコードそのものは見えません。見たいときは、runが終わってセッションがidleになった後に、user.message で「始めたときのワークフローをそのまま出力して。新しいrunは始めないで」と頼みます。主エージェントが書いた内容を教えてもらう形です。

runがopenな間に、クライアントの操作がどうなるかも確認しておきます。

最後の行は実装上いちばん効きます。runのスレッドが応答を待っていても、セッションは running のままです。idleを待ってから答える作りだと、いつまでも答えられません。

割り込みと停止

user.interrupt を session_thread_id なし(または主スレッドのID)で送ると、主エージェントのターンが止まります。runは終わりません。runが一時停止するか動き続けるかは、イベントから分からないことがあります。一時停止中も寿命は進むため、timeout_error で終わることがあります。

割り込み後にやることは3つあります。

• 待機中のツール呼び出し: 割り込み後も、runのスレッドのツール呼び出しが応答を待っていることがあります。確認を求める呼び出しはdeny、カスタムツールは is_error: true と理由のテキストを付けた結果で取り消します。requires_action のidleの間は user.message が400になるので、先に全部答えます。
• runを止める: 主エージェントにrunを止めるよう user.message で頼みます。止まったrunは {"type": "stopped"} で終わります。
• 続ける: 続行を頼む user.message を送ります。割り込み後のrunは、このメッセージを待つことがあります。

budget_reached のidleの間は user.message が400になるため、先に予算を引き上げるか外します。予算の側の実装は予算到達・アイドル再開の実装パターンにあります。

再接続したら、イベント一覧からrunの状態を作り直す

ストリームは取りこぼしたイベントを再送しません。新しい接続が届けるのは、接続を開いた後のイベントだけです。切断中に起きたことは、イベントの一覧取得で埋めます。手順はこうなります。

1. types フィルターにイベント種別を並べて、セッションのイベントを一覧取得する
2. レスポンスの next_page を page に渡し、next_page が null か欠けるまで繰り返す
3. workflow_run.created / status_running / status_idle / status_ended から各runの状態を作る
4. phase_started / phase_ended から進捗を作る

前節の RunBook.apply に一覧を順に流せば、手順3と4のうちopenなrunの集計までは同じコードで済みます。注意点が2つあります。

• 割り込み後に止まったrunは、一覧の上ではrunningのままに見えることがあります。
• ステータスイベントが1つも無いrunは、まだ実行が始まっていません。

runを一覧する専用のエンドポイントはありません。runの把握は、すべてセッションのイベントから行います。ストリームの実装の基本はSSEイベントストリームの実装を参照してください。

予算と上限

runには専用の価格がありません。runのエージェントが使うトークンは、セッションのほかのトークンと同じく、モデルごとの単価で課金されます。runのモデルリクエストはセッションの予算に数えます。

run 1回分の使用量を知りたいときは、セッションのスレッド一覧から、そのrunの workflow_run_id を持つスレッドの usage を足し合わせます。アーカイブ済み(terminated)のスレッドも一覧に含まれるので、終わったrunも集計できます。usage が null のスレッドは飛ばします。list_cost を足す方法もありますが、合計にセッションの稼働時間分が入らず、各値が個別に丸められています。

予算に達すると、開いているrunがすべて一時停止し、セッションは budget_reached でidleになります(ツール呼び出しも待っていれば requires_action)。各スレッドは開始済みのモデルリクエストを最後まで終えるので、動いているスレッド1つにつき最大1リクエスト分、予算を超えます。

1,000の数え方には注意が要ります。失敗したエージェントをサーバーが新しいスレッドで再実行することがあり、runのスレッド総数が1,000を超える場合があります。idleのrunも、同時にopenなrunの上限に数えます。

runやphaseの name は64文字、description は256文字に切り詰められます。ほかの上限やルールに触れたときの見え方は、気づく時点で変わります。

1つのセッションが生涯で始められるrunの数に上限はありません。

レート制限

runの仕事は、組織にすでにあるレート制限に数えられます。

• 取得・一覧のリクエスト: セッション、スレッド、イベントの取得や一覧は、Managed Agentsエンドポイントの読み取り上限に数えます。ポーリングではなくイベントストリームで追います。
• スレッドのモデルリクエスト: スレッドが使うモデルのMessages APIのレート制限に、ほかのトラフィックと合わせて数えます。runの分の余裕を残すか、上限の引き上げを申請します。

スレッドのモデルリクエストがレート制限やモデルの過負荷に当たると、そのスレッド自身のストリームに model_rate_limited_error か model_overloaded_error の session.error が出ます。retry_status.type が retrying ならサーバーが再試行中で、スレッドはまだ動いています。exhausted ならそのスレッドは失敗です。ワークフローがその失敗をrunの終了に回していれば、runは原因を示さない program_error で終わります。原因は失敗したスレッドのイベントを読んで探します。

組織全体のセッションが毎分に行える作業量にも上限があります。これに当たったスレッドは止まり、スレッド自身のストリームにレート制限を名指しする session.error が出ます。エージェントに続行を頼む前に、1分待ちます。レート制限の全体像はManaged Agentsのレート制限にあります。

runは同じ仕事のために複数のスレッドを作ることがあります。エージェントが呼ぶツールは、2回呼ばれても安全な作りにしておきます。

まとめ

runを扱う側の要点は3つです。完了はidleではなく「openなrunが0件で end_turn のidle」で判定します。completed は仕事の合否を示さないので、失敗はスレッド側で探します。切断したらストリームを頼らず、イベント一覧からrunの状態を作り直します。