agent-architecture-audit

エージェントアーキテクチャの監査

生のモデル呼び出しからユーザーに表示される出力まで、各レイヤーを調査してエージェントシステムの障害を診断します。

契約

入力：

• エージェントまたは LLM アプリケーションのリポジトリ、失敗した実行、トレース、ログ、または症状
• 任意：モデル／プロバイダーの一覧、ツール定義、メモリファイル、UI 出力

出力：

• 根拠への参照を含む、深刻度順の指摘事項
• レイヤーごとの障害診断
• プロンプトだけの変更よりもコードによるゲートを優先した、順序付きの修正計画

作成／変更：

• 監査モードではなし
• 明示的に依頼された場合に限り、追加の修正を実施

外部への副作用：

• デフォルトではなし
• すでに許可されている場合に限り、外部ログ、可観測性ツール、または本番システムを使用

確認が必要な操作：

• プロンプト、メモリ、ツールの契約、永続化、本番設定、またはユーザーデータを変更する前

委任先：

• 通常のソフトウェア不具合には debug
• ベンチマーク設計には evaluation（LLM-as-judge モードを含む）
• プロンプトインジェクション、シークレット、認証、または特権ツールのリスクには security-audit

使用する場面

• モデルのプレイグラウンドや直接の API 呼び出しでは動作するエージェントが、アプリ内では失敗する場合。
• ラッパー、オーケストレーションレイヤー、メモリシステム、またはツールルーターの追加後に、品質が低下した場合。
• モデルが必須ツールをスキップする、ツールを使っていないのに使ったと主張する、またはツール出力を誤読する場合。
• 古い会話の事実、古くなったメモリ、または圧縮された要約が新しいタスクに混入する場合。
• ログには正しい回答が記録されているのに、CLI、API、UI、ストリーミングレイヤー、またはレンダラーでは異なる結果が表示される場合。
• 隠れた再試行、フォールバック、修復、または要約のループが出力を書き換えている可能性がある場合。

一般的なコードレビューには使用しないでください。障害の原因がエージェントスタックにある可能性が高い場合に限ります。

レイヤーモデル

ソースの指示から最終出力まで、スタックを監査します。

レイヤー	発生しうる障害
システムプロンプト	競合、肥大化、古いルール、不明確な優先順位
セッション履歴	古いターンが現在のタスクより優先される、または矛盾する
長期メモリ	プロジェクト間の情報混入、古い設定、エージェントが書き込んだ事実
蒸留	圧縮によって推測が擬似的な事実に変わる
アクティブリコール	冗長な要約がコンテキストを浪費する、または古いコンテキストを呼び戻す
ツール選択	必須ツールがコードで任意扱いになっており、強制されない
ツール実行	呼び出しの欠落、呼び出しの失敗、未検証の引数
ツール解釈	出力が無視される、過信される、または逆に読み取られる
回答の整形	推論後に形式、スキーマ、Markdown、または JSON が変更される
転送／レンダリング	ストリーミング、API、CLI、または UI が有効なコンテンツを書き換える
隠れた修復ループ	2回目のモデル呼び出しが回答を密かに書き換える
永続化	キャッシュされた成果物や期限切れの状態が、現行の根拠として再利用される

監査プロセス

1. システムの範囲を特定する

以下を特定します。

• ユーザー向けのエントリーポイントと出力先
• モデルプロバイダー、モデルのティア、再試行／フォールバックの動作
• プロンプトの組み立て経路と指示のソース
• メモリ、検索、圧縮、永続化の経路
• ツールのスキーマ、ツールのルーティング、実行時の検証
• 既知の症状と、最初に発生したリリースまたはコミット

2. 根拠を収集する

以下を検索します。

• プロンプトテンプレートと指示の挿入箇所
• ツールのスキーマ、ルーター、バリデーター、実行ログ
• メモリの登録、検索、圧縮のコード
• 主要なエージェントループの外部にあるプロバイダー呼び出し
• フォールバック、再試行、修復、または出力の書き換え処理
• レスポンスのシリアライズ、Markdown のレンダリング、JSON の解析、ストリーム処理

ファイルと行番号による根拠を優先します。ログが利用できる場合は、生のモデル出力、後処理済み出力、転送後の出力、レンダリング後の出力を比較します。

3. 障害のメカニズムを特定する

疑わしい問題ごとに、以下を記録します。

• 症状：ユーザーに何が見えるか
• レイヤー：どこで破損が生じるか
• メカニズム：そのレイヤーがどのように動作を変えるか
• 根本原因：コード、設定、プロンプト、メモリ、転送、またはプロセス
• 根拠：ファイル、行、トレース ID、ログ行、または再現した実行
• 確信度：高、中、低

4. 修正の優先順位

次の順序で修正してください。

1. コードでツールの使用を必須にします。
2. 非表示の修復エージェントやフォールバックエージェントを削除するか、見えるようにします。
3. プロンプト、メモリー、履歴、要約の間で重複するコンテキストを減らします。
4. メモリーへの登録条件を厳格化し、ユーザーによる訂正をエージェントの主張より優先します。
5. 圧縮のトリガーを限定し、不確実性を示すマーカーを保持します。
6. すでに有効な出力は書き換えず、そのまま通します。
7. 内部プロトコルの境界には型付きエンベロープを使用します。
8. 生の出力、処理後の出力、転送後の出力、レンダリング後の出力を比較するトレーステストを追加します。

ツール使用の規律、メモリーの安全性、転送中の破損を、プロンプトの文言を強めるだけで解決しないでください。

深刻度

深刻度	意味
致命的	システムが、誤った、または危険な運用上の動作を確信を持って実行する可能性があります
高	通常の使用でも、正確性や安定性が頻繁に損なわれます
中	エージェントは通常は機能しますが、スタックが脆弱で、無駄が多く、デバッグしにくい状態です
低	保守性、可観測性、または出力の見た目に関する問題です

出力形式

指摘事項から始めてください。

## Findings

| Severity | Layer | Finding | Evidence | Fix |
| --- | --- | --- | --- | --- |
| High | Tool selection | Required retrieval is prompt-only and can be skipped | `src/agent/router.ts:42` | Gate final answer on retrieval result |

## Diagnosis

[Explain which layer corrupts the behavior and why.]

## Fix Plan

1. [Code-first fix]
2. [Validation]
3. [Follow-up hardening]

問題が見つからない場合は、その旨を伝え、確認した証拠と残る死角を列挙してください。

アンチパターン

• ラッパーレイヤーの動作を検証する前に、モデルのせいにする。
• コードで要件を強制していないのに、「ツールを必ず使う」というプロンプトの文言を受け入れる。
• 圧縮された要約を絶対的な事実として扱う。
• トレーサビリティなしに、非表示のモデル処理が最終出力を書き換えることを許す。
• 内部出力とユーザーに届けられた出力を比較せずに、ステータスを「問題なし」と報告する。