AIエージェントのデバッグ：ダッシュボードはコストを知っていても、原因は知らない

AIエージェントのデバッグは、可観測性ダッシュボードの限界から始まります。AIコーディングエージェントが何かを壊し、実行がすでに終わっている場合、ダッシュボードは実行コスト（トークン数、ドル、レイテンシ）を教えてくれますが、あなたが実際に知りたい唯一の問い——なぜエージェントはそのファイルを変更したのか——には沈黙したままです。その問いに答える成果物こそ、開いて読み、リプレイできる記録済みトレースです。トレースは実行を外側から説明するのではなく、実行そのものをあなたの手に返してくれるからです。

これは、エージェントが実際の作業を始めた瞬間から、珍しい出来事ではなくなった。エージェントはリポジトリをくまなく調べ、複数のファイルを編集し、チェックを実行して成功を報告する。そのすべてが、あなたが数分の間隔で入力した2つのプロンプトの合間に行われる。その編集の1つが間違っていたとしても、あなたが気付くのは後になってからだ。端末が閉じられ、スクロールバックが消え、自ら説明できたはずのプロセスが終了した後である。次に何が起こるかは、あなたが何を保持していたかに完全に依存する。それがコストダッシュボードであれば、あなたはこれから考古学をすることになる。それが記録であれば、あなたはこれから読書をすることになる。

再現できない障害

だいたいこんな具合です。リポジトリに戻ってくると、誰にも触れるよう頼んだ覚えのないファイルが書き換えられているか、削除されているか、他のすべてが依存している関数を空にされている。エージェントに何が起きたのか尋ねても、セッションは閉じられている。たとえトランスクリプトが残っている場合でも、エージェント自身の実行についての説明は再構成であって、記録ではない。そこで当然のことをして、もう一度実行してみるが、得られるのは異なる実行だ。異なるツール呼び出し、異なる編集、もしかすると失敗すらしないかもしれない。元の軌道がサンプリング、リポジトリの状態、タイミングに依存していたからだ。検査したい実行は、もう存在しない。

再現不能よりも悪い。再現不能であり、しかも成功としてマークされる。エージェントが終了コード0で終了すれば、実行も終了コード0で終了する。たとえ実行内のチェックが終了コード1で終了していてもだ。つまり、実行内の検証ステップが失敗していてもパイプラインはグリーンのままであり、あなたが自然と信頼する終了コードは何も教えてくれない。

ルーターがその実行に対してどのモデルを選んだかは関係ない（GLM 5.3 Flashであれ、他の何かであれ）：プロセスが終了すれば、推論の過程も一緒に消え去る。証拠は実行がライブである間だけ存在していた：プロンプト、ツール呼び出し、出力、差分。それらを何も記録していなければ、「なぜそのファイルを変更したのか」には答えがない。理論だけがある。

これが、AIコーディングエージェントをそれ以前のあらゆるツールから隔てる失敗モードです。損害と説明が同じ場所で発生し、その場所が閉じてしまうのです。

{{1}}ダッシュボードは何を測定し、何を見逃すのでしょうか？{{/1}}

うまくいかなかったランの後、人は可観測性ダッシュボードを開きたくなる。そしてそのダッシュボードは、実にきちんと自分の役割を果たしてくれる。その役割とはトラフィックの把握だ。1日あたりのトークン数、モデルごとのコスト、レイテンシ、エラー率。キャパシティプランニングと課金のためには、これはまさに適切な計器であり、本番環境でエージェントを運用しているなら、開いたままにしておくべきだ。

しかし、あなたの質問は集計的なものではありません。それは単独かつ因果的なものです。すなわち、なぜこの実行がこのファイルを変更したのか、ということです。集計は、まさにその問いに答える粒度を踏み越えてしまいます。複数の実行にわたって平均化すると、あなたが気にかけている実行はノイズになります。そして、その実行の中でも、あなたが気にかけているツール呼び出しは再びノイズになるのです。

ダッシュボードは、ランを外側から描写する。それが起こったこと、何を量ったのか、どれだけのコストがかかったのかを。しかし、ダッシュボードはランそのものを手渡してはくれない。「なぜ」は描写の属性ではない。それはシーケンスの属性なのだ。

• 実行のコストはいくらだったか — コストダッシュボードが答える vs 記録済みトレースが答える

• エージェントがそのファイルを変更したのはなぜか？ — コストダッシュボード 回答なし vs 記録済みトレース その編集（時系列で差分付き）

• グリーンラン内で失敗したチェックはどれか？ — コストダッシュボード: 応答なし vs 記録済みトレース。そのチェック（終了コード付き）。

• まったく同じ失敗を再現できますか？ — コストダッシュボード: いいえ vs 記録済みトレース: はい、オフラインで無料です

それに答える層は、すぐ下にあります。すなわち、記録されたリクエストログです。実行時に取得され、送信されたすべてのプロンプト、実行されたすべてのツール呼び出し、返ってきたすべてのレスポンスが順番に含まれています。実行の要約ではなく、実行そのものです。

1回の実行をタイムラインとして読み取る

録画があれば、デバッグは考古学ではなく読書になる。考古学とは、録画がないときにやることだ：git reflog、スタッシュエントリ、シェル履歴、その日の早い段階で自分が何を依頼したかという記憶。読書とは、{{1}}録画{{/1}}があるときにやることだ：タイムラインを開いてスクロールする。{{2}}録画{{/2}}がない場合の考古学には、git reflog、スタッシュエントリ、シェル履歴、その日の早い段階で自分が何を依頼したかという記憶が含まれる。{{1}}録画{{/1}}があれば読書になる：タイムラインを開いてスクロールするだけだ。

タイムラインは、実行の経過を発生順に並べて示す。すなわち、開始のきっかけとなったプロンプト、各ツール呼び出し、各ファイル編集とその差分、各チェック、各終了コードが並ぶ。ファイルシステムのスナップショットは、ツール呼び出しごとではなくターンごとに1回取得される。これで、呼び出しごとのノイズに埋もれることなく、会話の各段階におけるリポジトリの状態を把握できる。これをブラウジングではなくデバッグたらしめるのは、隣接性である。編集と、その問題を検出したチェックとが、順番どおりに、間に憶測を挟む余地なく隣り合っている。「なぜ」は、ほぼ隣接性に由来する性質なのだ。

記録された修正から読み取れる具体例を挙げよう。14個のイベントがあり、その中には +1 -3 と表示されたファイル変更と、終了コード1で失敗したチェックが含まれている。その編集と、そのせいで失敗したチェックは、記録上で隣り合っている。断片的なログから実行を再構成することと、一続きの記録を読むことの違いは、まさにそこにある。この違いはターミナルコーディングエージェントにとって最も重要である。彼らのワークスペースは、ジョブが完了した瞬間に閉じてしまうターミナルであり、タイムラインとは、生き残るスクロールバックのことである。

記録または推測：トレースが知っていることと、そこから導き出したこと

タイムラインは、何が順番に起こったかを教えてくれる。因果グラフは、何が何を引き起こしたかを教えてくれる。そして、その両者の間にある隔たりこそが、信頼が勝ち取られなければならない場所なのだ。

The graph connects events: this edit, then this failing check. Some of those edges are recorded facts: the tool call that produced the diff is right there in the trace. Others are inferred: the graph's conclusion that the check failed because of that diff. orca graph labels every edge recorded or inferred and names the rule it used either way, so you always know whether you are looking at something the run did or something the tool worked out about the run.

その区別は、努力目標ではなく、強制されるものだ。推論されたエッジは、トレースに書き戻されることは決してない。トレースは、起こったことの忠実な記録であり続け、推論はその上に載るビューであり、それを精査し、疑問を抱き、受け入れないこともできる。これは、複数のエージェントが関与するときに最も重要になる。リファクタリングエージェントとテスト作成エージェントが同じファイルに触れるとき、問いはまさに「どのエージェントがこれを引き起こしたのか」ということである。multi-agent attributionは、その問いに答えるために存在する。推論から事実へとひそかに昇格していくエッジがあれば、結局はランではなくストーリーをデバッグすることになる。

それを好きなだけ無料で複製する

読むことで説明がつく。リプレイすることで証明される。仮説ができたら（チェックが失敗したのは、編集によってリセット呼び出しが削除されたからだ）、もう一度実行して、それが実際に起こるのを確認したい。エージェントをライブで再実行すれば、新しい軌跡が得られ、新しい請求が発生する。

録音のリプレイは同じ実行をもたらす。リプレイ実行はネットワークが遮断された状態で行われるため、トークンを消費せず、ばらつきもない。毎回同じイベントが、オフラインで発生する。この特性こそが、エージェントのデバッグをギャンブルからエンジニアリングへと変える。すなわち、障害は決定的になり、決定的な障害は修正されるのだ。

このツールもブラックボックスではありません。OrcaReplayはApache-2.0ライセンスのオープンソースソフトウェアであり、トレース形式はCC BY 4.0ライセンスで提供されています。そのため、誰でもこれを再実装できます。あなたの録音も当社の録音も、プロプライエタリな形式に人質に取られることはありません。また、これはデモではなく、実際にテストされています。Node 20とNode 22で1393件のテストが実行されています。ソースを読み、形式を確認し、テストスイートを自分で実行してから、チームの実行をそれに委ねるかどうかを判断できます。

要点

ダッシュボードは請求書です。記録されたトレースこそが実行そのものです。AIエージェントのデバッグ計画がコストダッシュボードで終わっているなら、それはデバッグ計画ではありません。課金システムです。ダッシュボードは常に「その実行がいくらかかったか」を教えてくれますが、「なぜエージェントがあなたのファイルを削除したのか」を教えてくれることは決してありません。「なぜ」はシーケンスの中に存在し、そのシーケンスはあなたが保存して初めて存在するからです。

方法全体は4つのステップからなります：

• 実行を記録します。

• タイムラインを読んでください。

• グラフのエッジを確認してください。

• 怖いと感じるものは、無料で、好きなだけ何度でも再生できます。

情報源の注記: 本記事のすべての数値はベンダー報告に基づくものであり、当社製品、ならびにOrcaReplayリポジトリとそのドキュメントから取得しています。すなわち、実行の終了コードの挙動、+1 -3の差分とexit-1チェックを伴う14イベント記録修正、orcaグラフのエッジラベリング、ターンごとに1回のスナップショット頻度、ネットワークを遮断した状態でのオフラインリプレイ、そしてNode 20とNode 22での1393件のテストスイートです。本記事では第三者の測定結果は一切引用していません。1393件のテストスイートは、リポジトリをクローンして実行すればご自身で検証できる唯一の主張です。すべての項目は2026-09-04に最終確認済みです。