Managed AgentsをConsoleで可視化・デバッグする方法

Managed Agentsのセッションはコードを書かなくてもConsoleで追える

Managed Agentsのセッションは、イベントストリームをそのまま眺めるだけでは何が起きたか把握しづらいことがあります。ツール呼び出しの入出力、スレッドごとの分岐、コストの推移が同じ画面にまとまっていないと、障害調査のたびにログをJSONごと目で追う作業になります。

Claude Consoleのセッションビューアは、この用途に特化した画面です。サイドバーのManaged AgentsからSessionsを選ぶと、ワークスペース内の全セッションがステータス・エージェント・トークン使用量・コスト・作成時刻付きで一覧表示され、1件選ぶとその中身を開けます。閲覧できるのはDeveloperとAdminロールのみです。

セッションビューアの3つの主要パネル

セッションを開くと、性質の異なる3つのパネルが同時に見えます。

障害調査の起点はたいていタイムラインミニマップです。全体のどのあたりで挙動がおかしくなったかを先に掴んでから、該当箇所のマークをクリックしてトランスクリプトへ飛ぶ流れが、JSONを頭から読むより速く原因にたどり着けます。

インスペクターの5タブでわかること

インスペクターの5タブは、それぞれ別の切り口でセッションを見せます。

• Session: セッションのメタデータ、時系列の累積コスト、予算を設定している場合はその消費状況
• Events: 現在のスレッドの生イベントを、サーバーが送信した順にすべて表示。選ぶとJSONが見える。ページを開いている間にストリーミングされたメッセージには、イベントデルタ専用のDeltasビューも付く
• Tools: セッションのエージェントに設定されたツールを、呼び出し回数・失敗回数・所要時間の中央値付きで一覧表示。ツールを選ぶとその呼び出し一覧が出て、トランスクリプトの該当箇所へジャンプできる
• Resources: マウントされたファイル・リポジトリ・メモリーストアをコンテナ内のパスとともに一覧表示。各ストアのメモリー内容とこのセッションでの変更、/mnt/session/outputsへエージェントが書き出したファイル、セッションのエージェントに付いているスキルも含む
• Threads: 全スレッドをステータス・コンテキストサイズ・コストとともに一覧表示。スレッドを選ぶとエージェント・モデル・コンテキスト使用量・コストの詳細が見える

セッションURLに?event={event_id}を付け加えると、指定したイベントの位置からセッションビューアが開きます。エラー報告のリンクを社内で共有するときは、セッションIDだけでなくこのクエリ付きURLを渡すと、相手が同じ箇所をすぐ開けます。

トランスクリプトとEventsタブの使い分け

同じ会話を見るのに、なぜ2つの画面があるのか迷うかもしれません。役割は明確に分かれています。

トランスクリプトは絞り込みができ、内容をJSONとしてコピー・ダウンロードもできます。バグ報告を添付するときや、CI上で再現したセッションのログを保存しておくときは、この機能でエクスポートしてから共有すると、社内のissueトラッカーに貼り付けやすくなります。ページを開いている間にストリーミングされたメッセージには、EventsタブからDeltasビューでトークン単位の配信過程も見えます。ストリーミング表示が途中で崩れるような不具合を追うときはここまで見る必要があります。

Resourcesタブでわかる各リソースの中身

Resourcesタブは、セッションのサンドボックスに何がマウントされているかをコンテナ内パス付きでまとめます。表示される内容は4種類です。

• ファイル: セッションに添付されたファイルの一覧とパス
• リポジトリ: 接続されたGitHubリポジトリのマウント先
• メモリーストア: ストアごとのメモリー内容と、このセッションが行った変更点
• スキル: セッションのエージェントに付いているスキル一覧

加えて、エージェントが/mnt/session/outputsへ書き出したファイルもここに表示されます。「エージェントに成果物を作らせたのに、どこに出力されたか分からない」という問い合わせは、Resourcesタブを開けば大抵解決します。成果物を別の保存先へ移す運用にしていない場合は、セッションを終了する前にResourcesタブで存在を確認しておくと取りこぼしに気づきやすくなります。

デバッグの実践フロー — どのタブから見るべきか

公式のデバッグ指針は「セッションイベントを確認する」「ツール結果を見直す」「トークン使用量を追う」「システムプロンプトに追跡用の指示を足す」の4点ですが、このうち障害の原因特定に直結する最初の3つを順番に当てはめると迷いません。

1. まずsession.errorイベントの有無を確認する: セッションエラーはこのイベント型で伝わります。Eventsタブでイベント種別をsession.errorで絞り込めば、原因の特定が「トランスクリプトを頭から読む」作業ではなくなります
2. 次にToolsタブで失敗回数を見る: エージェントが「意味不明な行動」を取ったように見える場合、原因の多くはツール実行の失敗です。失敗回数が0でないツールを見つけたら、その呼び出し一覧からトランスクリプトの該当ターンへジャンプします
3. 最後にトークン使用量で異常な消費がないか確認する: 想定より早くコストが膨らんでいる場合、Sessionタブの累積コスト推移とThreadsタブのスレッド別コストを突き合わせると、どのスレッドが消費源かを絞り込めます

この順序が有効なのは、session.errorが「セッションが止まった理由」、Toolsタブの失敗回数が「エージェントが誤動作した理由」、コスト推移が「想定外に時間がかかっている理由」と、それぞれ別の症状に対応しているためです。症状から逆算してタブを選べば、トランスクリプト全体を読む必要はほとんどありません。

実例 — 「セッションが急に止まった」ときの見分け方

セッション一覧のステータスがidleになっているだけでは、何が原因で止まったのか分かりません。Sessionタブを開いて次の2点を見れば、原因の種類はすぐに絞り込めます。

• 予算の消費状況が上限に貼り付いている: 累積コストが設定した予算のほぼ100%に達していれば、stop_reason: budget_reachedで止まっています。この状態から動かすにはuser.messageではなく予算そのものの更新が必要です
• 累積コストは余裕があるのにToolsタブで直近の呼び出しが失敗している: 確認待ちのpermission_policy(always_ask)によってrequires_actionになっている可能性が高く、Eventsタブで直近のagent.tool_useとそれに対するuser.tool_confirmationの有無を確認します

Sessionタブとエラー系イベントを先に見る習慣がつくと、「止まった理由をコードで判定する処理」を書く前に、目視で仮説を立てられるようになります。

Consoleで見た情報はAPIでも同じものが取れる

セッションビューアは新しいデータを生成しているわけではありません。表示しているのはすべて、イベント履歴・セッションオブジェクト・スレッド情報としてAPIからも取得できる同じデータです。したがって、Consoleで手動確認した診断ロジックは、そのままコードに落とし込めます。

• Toolsタブの失敗回数・所要時間中央値 → イベント履歴をagent.tool_useとagent.tool_resultのペアで集計すれば同じ指標を自前で計算できる
• Sessionタブの累積コスト → セッションのusage.list_costフィールドをフェッチ、またはストリーム上のsession.usageイベントを購読すれば取得できる
• Threadsタブのスレッド一覧そのもの → スレッド一覧APIでセッション内の全スレッドを列挙できます。コスト総額を追うだけなら、スレッドごとの内訳ではなくsession.usageイベントやusage.list_costフィールドで足ります。コンテキストサイズの推移そのものは公開APIの数値としては追えませんが、圧縮が発生したタイミングはagent.thread_context_compactedイベントで検知できます
• Eventsタブのsession.error → 同名のイベントをストリームで監視すれば、Consoleを開かなくてもアラートに使える

社内向けの監視ダッシュボードを作るときは、まずConsoleで「どのタブのどの数値を見れば異常に気づけるか」を人間の目で確認してから、その指標だけをAPI経由で自動収集する順番が無駄がありません。逆に、Consoleで一度も確認せずに監視ロジックだけを組むと、「異常値」の閾値の感覚がつかめないまま実装することになりがちです。

まとめ

セッションビューアは「タイムラインで場所を絞り、インスペクターで種類別に深掘りする」画面です。障害調査ではsession.errorの有無、Toolsタブの失敗回数、コスト推移の3点を症状に応じて順番に当てはめるだけで、生のイベントストリームを追うより早く原因へたどり着けます。セッションが予算やアイドルで止まる挙動そのものはManaged Agentsの予算到達・アイドル再開・システムメッセージの実装パターンで扱っています。ツールの有効化・無効化はエージェント設定側の話で、Managed Agentsのツール一覧と有効化・無効化の設定方法にまとめています。設計思想の全体像はManaged Agentsの設計思想を参照してください。