AQuAの原因調査を読む前に、会話とソースの版を確かめる

記事作成日: 2026年10月9日

昨日失敗したエージェントの会話を、今日のmainブランチで調べる。更新の速いサービスでは、これだけで調査対象がずれることがあります。ログに対応するプロンプトやツールの実装が、すでに変更されているためです。

Googleが発表したAQuA（Ambient Quality Agent）は、本番の会話記録から問題を見つけ、観測対象エージェントのソースを使って原因を調べる仕組みです。デプロイ版のスナップショットを参照できる点が、この版のずれを考える材料になります。公式発表

ただし、スナップショットを使えることと、診断が必ず正しい実行版に対応することは別です。公式実装には版を省略したときのフォールバックがあり、版の不一致を拒否せず警告する処理もあります。

診断の単位を、問題の種類から一度の観測へ絞る

同じ種類の失敗でも、複数のデプロイ版で起きている可能性があります。AQuAのRCA手順は、問題をまとめたinsightから一度の観測であるoccurrenceを選び、その occurrence_id と agent_revision を控えるよう定めています。

次に、その版をソース参照ツールへ渡し、同じoccurrenceの会話を取得します。調査担当者に必要なのは「この問題に似たログ」と「それらしいコード」の組み合わせではなく、どの会話をどのコードで説明しているかの対応です。

複数のoccurrenceをまとめて取得すると、会話ごとに版が異なる場合があります。この場合、RCA手順では各会話の版を使うか、説明対象を一つの版に限定するよう指示しています。会話が途中までしか保存されていない場合も、その不足を明示する設計です。公式RCA手順

例えば、版8の会話で商品検索が失敗し、版10では検索ツールが変更されていたとします。版10のコードを読むことで修正済みかを調べることはできます。しかし、版8の失敗理由を説明する証拠として使うなら、その違いを明示する必要があります。

版を省略すると、最新のスナップショットを読む

ソース参照ツールの resolve_snapshot は、revision が指定されていればその版を選びます。省略された場合は、有効なmanifestを持つ最新のスナップショットを選びます。返却値の revision_source で選択理由を区別します。ソース参照ツールの実装

explicit は「正しい実行版を自動判定した」という意味ではありません。呼び出し側が別の版を指定することもできます。また、明示した版のmanifestがない場合、この関数は別の版へ黙って切り替えず、参照できない理由を返します。

この違いは運用上役立ちます。「コードに問題が見つからない」と「当時のコードを読めない」を、同じ結論として扱わずに済むためです。ただし、返却された理由を診断結果に残す必要があります。

行の検証が守るのは、修正案の参照先

原因を記録する record_root_cause は、修正案のファイルと行範囲をスナップショットに照合します。修正前の文字列 before は、モデルの出力をそのまま採用せず、参照したソースから埋めます。

manifestにファイルがない、本文が欠落している、行範囲がファイル末尾を超える、といった修正案は拒否します。一つでも照合できない案があれば、その呼び出しの記録全体を拒否する処理です。原因記録の実装

ここで確認されるのは、提案された変更が参照先のコードに結び付くことです。その行が失敗の原因だったか、置き換え後に期待どおり動くかを、この照合処理は検証していません。自由文の原因説明全体を、機械的に証明する処理でもありません。

さらに、会話の版と修正案の版が両方指定されていて異なる場合、_compute_revision_warnings は警告を返します。不一致だけを理由に記録を拒否する処理ではありません。どちらかの版が空なら、この比較による警告も返しません。

したがって、記録が成功したことだけで「実行時の版との一致まで確認済み」と判断するのは早計です。診断を受け取る人は、成功フラグとともに対象版と警告を読む必要があります。

ソースにない問題を、無理にコード修正へ変えない

ソース参照ツールは、取得対象から除外されたファイル、manifestにないパス、一覧にはあるが本文のないファイルを区別します。除外規則に一致するファイルなら、スナップショットにないだけで、リポジトリには存在する可能性があります。

第三者の依存サービスの内部は、観測対象エージェントのスナップショットからは読めません。公式RCA手順も、外部依存の振る舞いは読める呼び出し箇所から考察するものとして扱っています。公式RCA手順の欠落コードに関する説明

例えば外部APIの応答が疑わしい場合、呼び出し元の行を示せても、API内部の障害原因まで分かったことにはなりません。担当者へ渡す際は、観測した応答、呼び出し箇所、外部側で追加確認が必要な点を分けるのが妥当です。

record_root_cause は修正案が空の記録も受け付けます。原因調査の結果を残すために、必ずコード変更を提案する必要はありません。

修正担当者へ渡す前の確認

AQuAのRCA手順は、観測対象のソースを書き換えず、修正案が未検証であることを伝えるよう定めています。診断結果は、修正の着手点として読むのが適切です。

この記事で確認した実装を踏まえると、引き継ぎ時には次の情報を一緒に残すと判断しやすくなります。

• 説明対象の occurrence_id と、その会話の agent_revision。
• 実際に参照した版と、explicit または latest_fallback の別。
• 読めたファイル・行範囲と、会話やソースの欠落。
• 記録時の警告、原因としての仮説、修正後に確かめる振る舞い。

調査結果を、修正と再発防止につなげる

AQuAの診断を会話・実行版・ソースの行に結び付けると、修正担当者は「どの失敗を、どのコードで説明しているか」をたどれます。版のずれや証拠の欠落も分かるため、コード修正を試すか、外部サービスを調べるか、追加の記録を集めるかを判断する材料になります。

例えば、プロンプトやツールを頻繁に更新する問い合わせ対応エージェントでは、過去の会話を当時の実装で調べる用途に活かせそうです。外部APIを組み合わせた業務エージェントなら、呼び出し元の修正と外部サービス担当への調査依頼を切り分ける際に役立ちます。

さらに、失敗した会話と期待する振る舞いを整理すれば、修正後に確かめる回帰テストの題材にもできます。診断で見つけた仮説を再現・修正・再確認へつなげることで、本番の失敗を次の改善に使えるようになります。