【ITニュース解説】Your Agent Said "Done". The Trace Shows Nothing Changed.

自動化されたシステム、特にAIエージェントのようなプログラムが特定のタスクを「完了した」と報告する場面は、現代のソフトウェア開発では日常茶飯事である。しかし、この「完了」という報告が必ずしも「実際にシステムに変更が加えられた」ことを意味しない場合がある。これが今回取り上げる重要な問題であり、その解決策について解説する。

例えば、ステージング環境のリポジトリから古いブランチを削除するような定期的なクリーンアップ処理を想像してみよう。プログラムは複数のブランチ削除ツールを呼び出し、それぞれのツールが「OK」というステータスを返す。プログラム全体も「成功」と報告する。しかし、処理後にリポジトリの状態を確認すると、何も変更されていないことに気づく。ブランチは削除されておらず、名前も変更されていない。プログラムは成功したと言っているのに、現実世界では何も起こっていないのだ。

なぜこのようなことが起こるのだろうか。通常、システムの動作を追跡するための「トレース」という仕組みでは、どのツールがどのような引数で呼び出され、どのような出力結果を返し、そして成功したか失敗したかという「ステータス」が記録される。このステータスは、そのツールを呼び出した関数がエラーなく正常に終了したことを示している。しかし、関数が正常に終了したことと、その結果としてシステムの状態が実際に変化したかどうかは全く別の話なのだ。例えば、「古いブランチを削除する」ツールは、削除対象のブランチが一つも存在しなかった場合でも、「OK」と返すことがある。また、「データベースの行を移行する」ツールは、すでにそのバッチの行が移行済みだった場合でも「OK」と返すだろう。「設定ファイルを書き込む」ツールは、全く同じ内容でファイルを上書きした場合でも「OK」と報告するはずだ。これらはすべて、合法的な「何も変更しない」操作でありながら、トレース上では実際の作業が行われた場合と区別がつかない。

このような曖昧さは、特にAIエージェントがループ処理をしたり、失敗時に再試行したり、計画を立て直したりする際に、問題が複雑化する。プログラムは「うまくいった」と考えて何度も同じ無駄な作業を繰り返したり、いつまで経ってもタスクが完了しないという状況に陥りやすくなる。

この問題を解決するために提案されるのが、「Witness（証人）」というアプローチである。これは、システムの状態に変更を加える可能性のあるツールが実行される前後に、そのシステムの特定の状態を読み取り専用で取得し、記録するという方法だ。

具体的には、各ツール呼び出しの前に、対象となるシステムの部分（例えばリポジトリのブランチ一覧や設定ファイルのハッシュ値など）を小さなスナップショットとして取得し、その内容をハッシュ値に変換する。このハッシュ値は、その時点での状態のデジタルな「指紋」のようなものだ。そして、ツールを実行した後、再度同じ方法でシステムの状態のスナップショットを取得し、再びハッシュ値を計算する。最後に、ツール実行前と実行後に取得した2つのハッシュ値を比較する。この2つのハッシュ値が異なっていれば、ツールがシステムに何らかの変更を加えたことが証明される。逆に、同じであれば、ツールが成功と報告したにもかかわらず、実際には何も変更されなかったことがわかる。この「変更があったかどうか」という情報を、ツールの実行ログ（スパン）に記録するのだ。

この「Witness」として機能する状態取得処理（プローブ）にはいくつかの重要なルールがある。まず、プローブは決してシステムの状態を変更してはならない。あくまで「読み取り専用」でなければならない。次に、プローブは「境界のある」情報を返す必要がある。つまり、システム全体や数百万行のデータベースといった巨大なデータをそのまま返すのではなく、ブランチの数、ファイルのハッシュ値、レコードのIDリストなど、比較可能でコンパクトな情報に限定する。最後に、プローブが返す情報は「安定している」必要がある。例えば、リストの要素の順序が変わっただけで変更があったと誤認識されないよう、必ずソートするなどして、本質的な変化のみを捉えるようにする。また、updated_atのようなタイムスタンプは、触るたびに値が変わってしまうため、プローブに含めるべきではない。

この「ツール実行のステータス」（OKかエラーか）と「システムが実際に変更されたか」（変更ありか変更なしか）という2つの情報を組み合わせることで、以前は見分けがつかなかった失敗パターンを明確に区別できるようになる。

1. clean_success（クリーンな成功）: ステータスはOKで、実際にシステムに変更があった場合。これは期待通りの結果であり、プログラムは順調に進んでいることを示す。
2. silent_success（サイレントな成功）: ステータスはOKだが、システムに何も変更がなかった場合。これが最もエンジニアの時間を無駄にするパターンだ。プログラムは成功したと信じて先に進むが、実際には何も作業が行われていないため、タスクは完了せず、無駄な再試行や再計画を繰り返すことになる。
3. phantom_failure（ファントムな失敗）: ステータスはエラーだが、実際にはシステムに変更があった場合。これは非常に危険なパターンである。プログラムは失敗したと判断して再試行を試みるが、すでに一部の変更が行われているため、再試行によって重複した効果が生じたり、データの整合性が崩れたりするリスクがある。
4. clean_failure（クリーンな失敗）: ステータスはエラーで、システムに何も変更がなかった場合。これは期待通りのエラーであり、安全に再試行できることを示す。

これらの分類は、問題の早期発見と効率的なデバッグに大きく貢献する。特にsilent_successとphantom_failureは、手動での確認では見落としがちだが、このアプローチにより自動的に検出できる。例えば、CI/CD（継続的インテグレーション/継続的デリバリー）パイプラインにチェックツールを組み込み、silent_successやphantom_failureが検出されたらビルドを失敗させることで、問題が本番環境に到達する前に食い止められる。

デバッグの際にも、この新しい情報は大いに役立つ。例えば、タスクが完了しない場合、まずWitnessを有効にして再実行し、生成されたトレースログを分析する。特に「サイレント成功」と報告された最初の一つに注目する。多くの場合、根本的な原因はその最初の無駄な操作にあることが多い。その原因（例えば、フィルター設定が間違っていて何も一致しなかった、対象とするべきオブジェクトを間違えたなど）を特定し、修正する。そして、修正後に再度タスクを実行し、同じスパンが「クリーンな成功」に変わったことを確認する。この一連の再現性のあるデバッグループは、問題解決の効率を格段に向上させる。

このWitnessアプローチは非常に強力だが、いくつかの限界も理解しておく必要がある。まず、プローブの実行にはコストがかかる。各ツール呼び出しに対して2回余分にシステムの状態を読み取るため、非常にパフォーマンスが重視されるような「ホットパス」では、そのオーバーヘッドが無視できない場合がある。次に、プローブ自体が測定対象を破壊してしまっては意味がない。例えば、キューからメッセージを消費するようなプローブは、非冪等であり、測定対象を消してしまうため使えない。また、「変更があった」という事実は「その変更が正しかった」ことを意味しない。Witnessはシステムが動いたことを証明するが、意図した通りの変化であったかまでは保証しない。非常に大規模なシステムの状態をハッシュ化しても、意味のある情報が得られないこともある。さらに、プローブがシステムの状態をスナップショットとして取得する際に、機密情報が含まれる可能性も考慮し、トレースログに記録する際はハッシュ化するか、機密部分を削除する必要がある。外部システムをプローブする場合、結果整合性（すぐに変更が反映されないこと）により、一時的に「変更なし」と誤認識される可能性もある。

したがって、このアプローチは、プログラムが読み取り専用である場合や、ツールが安価な状態を公開していない場合、あるいはミリ秒以下のオーバーヘッドが求められるような厳密なパフォーマンス要件がある場合には適さないこともある。

結論として、単に「OK」と報告されたツールのステータスだけでは、システムが本当に意図した作業を行ったのかどうかは判断できない。しかし、「OK」というステータスに加えて、Witness（状態プローブ）によって得られた「システムが実際に変更された」という証拠を組み合わせることで、プログラムが本当に仕事をしたのか、それとも礼儀正しく何もせずに終わっただけなのかを明確に区別できるようになる。この新しい視点を取り入れることで、自動化システムのデバッグと信頼性を大きく向上させることが可能になるだろう。