【ITニュース解説】Debugging the Black Box: Why Session Replay, Error Tracking, and Structured Logs Are the Missing Observability Layer for Production AI Agents

システム開発において、システムが期待通りに動作しているかを確認する「監視（オブザーバビリティ）」は非常に重要である。しかし、近年普及が進むAIエージェントのような複雑なシステムでは、従来の監視手法だけでは不十分な場合が多い。例えば、ユーザーからの問い合わせに対応するAIエージェントを稼働させたとしよう。監視ダッシュボードにはすべて正常を示す「HTTP 200 OK」が表示され、エラーも発生せず、応答時間も問題ない。LLM（大規模言語モデル）の提供元もシステムは正常だと報告している。しかし、ユーザーからは「AIが間違った回答をした」「途中で止まった」といった苦情が殺到することがある。これは、従来の監視システムが想定していないAIエージェント特有の性質が原因である。従来のシステムは、決まった入力に対して決まった出力が返る「決定論的」で、一度の処理で完結する「ステートレス」なサービスを監視するように設計されていた。しかし、AIエージェントはこれらとは大きく異なる。

AIエージェントには主に四つの特性があるため、従来の監視が通用しない。 まず「非決定性」が常態である。同じユーザーの入力に対しても、AIエージェントは毎回異なる推論経路をたどったり、異なるツールを呼び出したり、最終的に異なる回答を生成したりすることがある。そのため、「結果が期待通りである」と断言できる保証がなく、テストも確率的なチェックにならざるを得ない。エラーは特定のコードパスの問題ではなく、回答の「分布のずれ」として現れる。 次に「会話が状態」である。データベースに永続的に保存されるデータが従来のシステムの「状態」であったのに対し、AIエージェントにとって重要な状態は、ユーザーとのメッセージ履歴、作業中の記憶、ツール呼び出しの文脈、エージェント自身の内部的な推論などである。これらは通常、LLMの「コンテキストウィンドウ」と呼ばれる一時的な記憶空間に存在し、セッションが終わると消えてしまうため、後から確認することが難しい。 三つ目は「意味論的な失敗」があることだ。AIエージェントは、技術的には正しいツールを呼び出し、正しいデータを受け取ったにもかかわらず、その情報を使って生成した回答が、文法的にも完璧であるにもかかわらず、事実とは異なる「ハルシネーション（幻覚）」を起こすことがある。この場合、システム的には何のエラーも発生しないため、従来の監視では検知できない。エラーはシステムのエラーコードではなく、「回答の内容」に潜んでいる。 最後に「多段階で長時間のセッション」である。一つのユーザーとのやり取りが、LLMへの複数回の問い合わせ、複数のツール実行、そして数十秒にわたる処理を含むことがある。従来の監視は、短く独立したリクエストを前提としていたため、監視の単位を「リクエスト」から「セッション」へとシフトする必要がある。これらの特性により、監視ダッシュボードがすべてグリーンを示していても、ユーザーの3%が間違った回答を受け取り、ビジネス上の損失が発生するような事態が起こりうるのである。

AIエージェントのデバッグを可能にするためには、以下の三つの「欠けている柱」が必要である。 一つ目は「セッションリプレイ」である。これは単なる画面録画ではない。AIエージェントにおけるセッションリプレイとは、エージェントの思考や行動のログを、まるで「イベントソーシング」のように記録することである。具体的には、セッション開始、LLM呼び出し、ツール起動、エージェントの内部推論、状態の変化、セッション終了など、セッション中に発生したすべての重要なイベントを、決定論的かつクエリ可能な形で詳細に記録する。これにより、過去のセッションのイベントシーケンスを再現し、AIエージェントがどの時点でどのような判断を下し、なぜその結果に至ったのかをステップバイステップで確認できるようになる。これは、非決定論的なシステムをデバッグ可能な状態にする上で極めて重要である。

二つ目は「意味論的エラー追跡」である。従来のシステムが例外などの技術的なエラーを追跡するのに対し、AIエージェントでは「出力が本当に間違っているか」を追跡する仕組みが必要になる。これには、技術的なエラーでは捕捉できない以下のような意味論的な失敗を検知することが含まれる。例えば、AIが架空の情報をでっち上げる「ハルシネーション」、ツールを呼び出す際の引数が誤っている「ツール誤用」、会話が長くなりすぎて過去の文脈を忘れてしまう「コンテキストオーバーフロー」、システムの安全規定に抵触して回答を拒否する「拒否・ポリシー違反」、外部APIからのデータが空だったにもかかわらずAIがそれを無視して回答を生成する「上流データ欠損」などがある。これらのエラーは、後処理で検証する（例えば、別のLLMに判定させる）ことで検知し、セッションリプレイと関連付けて追跡する必要がある。

三つ目は「構造化エージェントログ」である。これは単なるテキストログとは異なる。エージェントログは、セッションID、トレースID、ステップインデックスなどを用いて各ログ行が互いに関連付けられ、クエリ可能なスキーマを持つ必要がある。これにより、特定のセッションで何が起こったのかを時系列で追跡したり、特定の条件下でのLLM呼び出しを絞り込んで分析したりできる。また、各LLM呼び出しにかかった入力・出力トークン数や推定コスト、レイテンシ（応答時間）も記録することで、コスト管理や性能分析にも役立つ。ClickHouseのようなログ分析に特化したデータベースにこれらのログを保存し、Grafanaなどのツールで可視化することで、システムの挙動や異常を効率的に把握できるようになる。

これらの観測性を実現するためのアーキテクチャでは、「Observability Injection Layer（観測性注入レイヤー）」をエージェントのランタイム（実行環境）に組み込むことが重要である。これは、AIエージェントがLLMを呼び出したり、ツールを実行したり、内部状態を変化させたりするあらゆる処理をラップするミドルウェアとして機能する。このレイヤーを通して、すべての重要なイベントが構造化されたデータとして、イベントバス、意味論的エラーバリデーター、構造化ログパイプラインに送られる。 具体的な実装としては、AgentEventというイベントの型を定義し、各イベントがセッションID、ステップインデックス、タイムスタンプ、イベントタイプ、そして詳細なペイロードを持つようにする。そして、ObservabilityBusのようなクラスを通じて、これらのイベントを生成し、セッションごとに専用のストレージ（例えばS3とデータベースを組み合わせたもの）に永続化したり、リアルタイムのメッセージバス（NATSやKafka）に発行したりする。 セッションリプレイでは、LLM呼び出しの前後やツール実行の前後で、bus.emitメソッドを使って適切なイベント（llm.callやtool.invokeなど）を発行し、エージェントの思考や行動を詳細に記録する。これにより、エージェントのロジックに新しいツールが追加されても、その呼び出しは自動的に観測性注入レイヤーを通過し、ログとして記録されるため、常に高い観測性を維持できる。 意味論的エラー追跡の実装では、セッション終了後や特定のタイミングで、記録されたイベント全体を分析するSemanticValidatorのような機能が必要となる。これは、LLM呼び出しのプロンプトトークン数を見てコンテキストオーバーフローを検知したり、ツールが空の結果を返したにもかかわらずエージェントがそれを無視して回答を生成していないかをチェックしたりする。さらに、LLM自体を「判定者」として活用し、AIエージェントの最終回答が事実に基づいて忠実であるかを評価させ、ハルシネーションを検知するアプローチも考えられるが、これはコストがかかるため、サンプリングして実行するなどの工夫が必要となる。 構造化エージェントログのパイプラインは、エージェントのランタイムから出力されるJSON形式のログを、Fluent BitやOpenTelemetry Collectorなどのツールで収集し、個人情報（PII）の匿名化やサービスメタデータの付加といった処理を行った後、ClickHouseのような高速な分析用データベースに送り込む。そして、Grafanaなどのダッシュボードツールで可視化し、異常値を検知した際にはPagerDutyなどのアラートシステムに通知する。このログを活用することで、「特定のユーザーがなぜ間違った回答を受け取ったのか」といった具体的なデバッグから、「成功セッションあたりのコストが閾値を超えた」といった集計的な分析までが可能になる。

AIエージェントの観測性を運用する上では、いくつかの重要な考慮点がある。 「サンプリング戦略」はその一つだ。1日4万セッションといった大規模な運用では、すべてのLLM呼び出しのプロンプトや応答の全ペイロードを保存すると、ストレージコストが膨大になる可能性がある。そのため、意味論的エラーが検出されたセッションや、エンタープライズユーザーのセッションなど、特に重要なものについては詳細なペイロードを保存し、それ以外のセッションではペイロードを一部を切り詰めて保存するといった工夫が必要となる。また、LLMを判定者として使う意味論的エラー検知も、コストを抑えるために一部のセッションに対してのみ実行する。 「PIIとコンプライアンス」も重要な側面である。AIエージェントが扱う会話には、個人情報や機密情報が含まれる可能性があるため、観測性パイプラインはPIIの匿名化、ストレージの暗号化、データ保持期間（TTL）の設定などを適切に行う必要がある。 「リプレイの非決定性」への理解も重要である。LLMの出力は非決定性を持つため、過去のセッションを完全に「再実行」しても、同じ結果が得られるとは限らない。しかし、記録されたイベントログをステップバイステップで確認することで、エージェントの思考や判断の経緯を追跡し、どこで問題が発生したかを特定することは可能である。 「クロスエージェント観測性」では、複数のAIエージェントが連携して動作するシステムの場合、OpenTelemetryのトレースIDのように、親エージェントから子エージェントへとトレース情報が伝播するように設計する必要がある。 「コスト異常アラート」も重要だ。AIエージェントが無限ループに陥り、ツール呼び出しを繰り返すような事態が発生すると、短時間で高額なLLM利用料が発生することがある。セッションあたりのコストやステップ数が異常に増加した場合にアラートを出すことで、このような問題を早期に検知できる。 そして、「観測性レイヤー自体のテスト」も忘れてはならない。観測性コード自体にバグがあれば、システムは正常に見えるが実際には何も監視できていないという事態に陥る。そのため、すべてのLLM呼び出しやツール起動が正しくログに記録されているか、セッション終了イベントの集計値が正しいかなどを確認する統合テストを導入することが推奨される。

最後に、これらの観測性機能を「いつ導入すべきか」という問いに対しては、すべての柱を最初から導入する必要はない。最も基本的な「構造化エージェントログ」から始めるのが良い。これは最も実装が容易で、デバッグ能力の80%を提供してくれる。次に、複数のLLM呼び出しや多段階の推論を行うようになったら「セッションリプレイ」を追加する。そして、ユーザーからの品質に関する苦情が増えたり、NPS（顧客推奨度）が低下し始めたりしたら「意味論的エラー追跡」を導入すると良いだろう。この三つの柱は相互に補完し合う関係にあり、開発の進捗に合わせて段階的に導入していくことが効果的である。