Managed AgentsをConsoleで可視化・デバッグする方法
Managed Agentsのセッションが止まった・コストが膨らんだときに、Consoleのセッションビューアのどこを見るか。症状別の見分け方とantコマンドでの開き方をまとめます。
Managed Agentsのセッションはコードを書かなくてもConsoleで追える
Managed Agentsのセッションは、イベントストリームを眺めるだけでは何が起きたか把握しづらいことがあります。ツール呼び出しの入出力、スレッドごとの分岐、コストの推移が別々に流れてくるためです。障害調査のたびにJSONを目で追う作業になります。
Claude Consoleのセッションビューアは、この用途の画面です。サイドバーのManaged AgentsからSessionsを選ぶと、ワークスペース内の全セッションがステータス・エージェント・トークン使用量・コスト・作成時刻付きで並びます。1件選ぶと中身が開きます。閲覧できるのはDeveloperとAdminのロールだけです。
セッションビューアの3つのパネルと5つのタブ
セッションを開くと、性質の異なる3つのパネルが同時に見えます。
| パネル | 何を見るためのものか |
|---|---|
| タイムラインミニマップ | 何を見るためのものかセッション全体の活動をズームできる帯で概観する。マルチエージェントではスレッドごとに1レーン。レーンを選ぶとそのスレッドへ、マークを選ぶと該当イベントへ飛ぶ |
| トランスクリプト | 何を見るためのものかモデルリクエスト単位でまとめた会話。thinking・入出力付きのツール呼び出し・ストリーミング中のメッセージ本文を含む。イベントの絞り込みと、JSONでのコピー・ダウンロードができる |
| インスペクター | 何を見るためのものかセッションの詳細を5タブに分けた、サイズを変えられるサイドパネル |
インスペクターの5タブは、切り口が別々です。
インスペクターの5タブ
Session
メタデータ、時系列の累積コスト、予算を設定している場合はその消費状況。
Events
現在のスレッドの生イベントを、サーバーが送った順にすべて表示。選ぶとJSONが見える。開いている間にストリーミングされたメッセージには、デルタ専用のDeltasビューも付く。
Tools
エージェントに設定されたツールを、呼び出し回数・失敗回数・所要時間の中央値付きで一覧。ツールを選ぶと呼び出し一覧が出て、トランスクリプトへジャンプできる。
Resources
マウントされたファイル・リポジトリ・メモリーストアをコンテナ内のパス付きで一覧。各ストアのメモリー内容とこのセッションでの変更、
/mnt/session/outputsへ書き出されたファイル、エージェントに付いたスキルも含む。Threads
全スレッドをステータス・コンテキストサイズ・コスト付きで一覧。選ぶとエージェント・モデル・コンテキスト使用量・コストが見える。
セッションURLに?event={event_id}を付けると、指定したイベントの位置でビューアが開きます。エラー報告にはセッションIDだけでなく、このクエリ付きURLを添えると、相手が同じ箇所をすぐ開けます。
「セッションが止まった」ときに見る場所
セッション一覧のステータスがidleでも、原因は1つとは限りません。idleは「エージェントが入力を待っている状態」を指し、仕事を終えたセッションも、承認待ちのセッションも、予算の上限で止まったセッションも同じidleになります。理由は、Eventsタブのsession.status_idleイベントにあるstop_reasonで分かります。
stop_reason | 意味 | 動かす方法 |
|---|---|---|
end_turn | 意味ターンを自力で終えた。割り込みで止めた場合も同じ値になる | 動かす方法新しいuser.messageを送る |
requires_action | 意味ツール呼び出しの承認など、返事待ち。止めているイベントのIDがstop_reason.event_idsに入る | 動かす方法user.tool_confirmationなどで応答する |
budget_reached | 意味セッションの予算に達した。終了ではなく一時停止で、履歴とサンドボックスは残る | 動かす方法予算の上限を引き上げるか、予算を外す |
予算で止まったセッションは、ビューアのSessionタブの予算消費状況で、上限に達しているかが分かります。上限を超えた最後のリクエストは完了まで走るため、記録上のコストは上限ちょうどか、わずかに超えた値になります。たとえば上限が50セント("50")のセッションが、53セントで止まることがあります。
予算で止まったセッションにuser.messageを送っても動きません。新しい作業を始めるイベントは400エラーで拒否されます。受け付けられるのはuser.tool_confirmation・user.tool_result・user.custom_tool_result・user.interruptの4つです。ただしuser.interruptは受理されても無視され、イベント一覧にも出ません。上限を引き上げるときは、元のmax_list_costではなく、セッションのusage.list_costを基準に決めます。止まった時点のコストは上限をわずかに超えているためです。
requires_actionは、権限ポリシーがalways_askのとき、またはautoでサーバーが判定を下せなかったときに出ます。コストに余裕があるのに止まっているセッションは、Eventsタブで直近のagent.tool_useに対するuser.tool_confirmationが届いているかを見ます。
トランスクリプトとEventsタブの使い分け
同じ会話を見る画面が2つあるのは、読む人が違うためです。
どちらの画面で読むか
トランスクリプト
エージェントの動きを時系列で追いたいときに開きます。バグ報告や再現ログを人に渡すときは、ここからJSONをコピーまたはダウンロードします。
Eventsタブ
stop_reasonの値や、特定イベントのJSON構造を確かめたいときに開きます。ストリーミング配信の中身を見たいときはDeltasビューに切り替えます。
症状から逆算するデバッグの順番
デバッグ指針には、セッションイベントの確認、ツール結果の見直し、トークン使用量の追跡などが挙げられています。そのうち障害の原因特定に直結する3つは、症状に合わせて次の順で当てはめると迷いません。
原因を絞る3段階
- 1
session.error の有無を見る
セッションエラーは
session.errorイベントで伝わります。イベントをsession.errorで絞ると、トランスクリプトを頭から読まずに済みます。このイベントには型付きのerrorオブジェクトが入り、retry_statusも含まれます。 - 2
Toolsタブで失敗回数を見る
エージェントが奇妙な動きをしたときは、ツール実行の失敗が理由になっていることがあります。失敗回数が0でないツールを開き、呼び出し一覧からトランスクリプトの該当ターンへ飛びます。
- 3
コストの出どころを探す
想定より早くコストが膨らむなら、Sessionタブの累積コスト推移とThreadsタブのスレッド別コストを突き合わせます。どのスレッドが消費源かが絞れます。
session.errorは有無が1イベントで決まるので最初に見ます。エラーが無ければ、次にToolsタブの失敗回数、最後にコスト推移へ進みます。
手元のターミナルからセッションを追う
ConsoleのURLを開く代わりに、antコマンドからセッションに接続することもできます。ant beta:sessions connectはCLIのバージョン1.32.0以降で使え、セッションのトランスクリプトを読み込んで、エージェントが動く様子をそのまま追います。
ant beta:sessions connect sesn_011CZkZAtmR3yMPDzynEDxu7
ant beta:sessions connect sesn_011CZkZAtmR3yMPDzynEDxu7 --web1行目は端末の中で動く画面で、各ツール呼び出しの所要時間と結果が見えます。Ctrl+Oで入出力・トークン使用量・ステータスイベントの詳細を出し入れでき、Escでuser.interruptを送って実行中のエージェントを止められます。承認待ちの呼び出しがあると入力欄が「Allow tool call?」に変わります。Yes・No・理由付きのNoのどれかを選べば、その結果がuser.tool_confirmationとして送られます。
2行目の--webは、Consoleのセッションビューアを127.0.0.1の一時サーバーから配信し、ブラウザで開きます。端末版がマルチエージェントでは主スレッドだけを追うのに対し、ブラウザ版は全スレッドを追います。表示されたURLは出力から2分以内に1度だけ開けます。別の端末で見たいときは、コマンドを実行し直します。端末の画面にはインタラクティブな端末が必要なので、スクリプトからはant beta:sessions:events streamを使います。
Consoleで見た指標をAPIで自動収集する
セッションビューアが新しいデータを作っているわけではありません。表示しているのは、イベント履歴・セッションオブジェクト・スレッド情報としてAPIからも取れる同じデータです。Consoleで決めた診断の見方は、そのままコードにできます。
- Toolsタブの失敗回数・所要時間: イベント履歴から
agent.tool_useとagent.tool_resultを取り出して集計すれば、自前で計算できます - Sessionタブの累積コスト: セッションの
usage.list_costを取得するか、ストリーム上のsession.usageイベントを購読します。session.usageはセッションがidleになる直前に必ず1回出ます - Threadsタブの一覧: スレッド一覧APIで列挙できます。スレッドの
usageには、スレッド単位のlist_costが入ります。ただし各値は個別に丸められ、セッション全体の実行時間コストも含まないので、足してもセッションのlist_costとは一致しません。予算の判定に使われるのはセッション側の値です - コンテキストの圧縮: 履歴がコンテキストウィンドウに収まるよう圧縮されたタイミングは、
agent.thread_context_compactedイベントで分かります - Eventsタブの
session.error: 同名のイベントをストリームで監視すれば、Consoleを開かずにアラートへ使えます
監視ダッシュボードを作るなら、先にConsoleで「どのタブのどの数値が異常のサインか」を確かめ、その指標だけをAPIで集める順番が無駄がありません。しきい値の感覚がないまま実装すると、アラートが鳴りすぎるか鳴らないかのどちらかになりやすいためです。
Resourcesタブで成果物と添付を確かめる
エージェントに成果物を作らせたのに、どこに出力されたか分からないときは、Resourcesタブの/mnt/session/outputsの欄を見ます。ターンの最後に書かれた出力ファイルは、idleになってから数秒後にセッションのファイル一覧に現れることがあります。一覧に出ていないときは、少し待ってから開き直します。
セッションを削除すると、そのセッションが作ったファイルはサンドボックスごと完全に消えます。持ち帰りたい成果物は、削除の前にResourcesタブで存在を確かめて、ダウンロードしておきます。
まとめ
止まった理由はstop_reason、動かない理由はイベントの種類、膨らむコストはThreadsタブと、症状ごとに見る場所が違います。ビューアを開く前に、どの症状かだけ決めておくと迷いません。
予算や承認待ちで止まる挙動そのものはManaged Agentsの予算到達・アイドル再開・システムメッセージの実装パターンで扱っています。ツールの有効化・無効化はエージェント設定の話で、Managed Agentsのツール一覧と有効化・無効化の設定方法にまとめています。設計の全体像はManaged Agentsの設計思想を参照してください。