ツールで調べるAIエージェントを作り、でっち上げの答えを見抜くテストで確かめる

## 調査エンジンと、サービスごとのプラグインを分ける システムを、ユーザー向けの入口、設定の読み込み、調査エンジン、ツールマネージャー、差し替え可能な情報源、ツールセット、プロンプト、出力先という明示的な層に分けます。入口ではリクエストを振り分けてログ記録を設定し、設定層では設定値を検証して連携機能を構築します。エンジンではツールを選択し、証拠を収集し、結果を分析して、必要に応じて承認済みの出力先へ調査結果を返します。 プロバイダー固有の動作はプラグインの背後に置き、中核ループが安定したツール契約に基づいて推論できるようにします。検証済みの設定から連携機能を動的に読み込み、情報源の取り込み、調査、出力先への書き込みを分離して、読み取り専用の診断が知らないうちに外部の状態変更へ変わらないようにします。 ## ツールは薄いラッパーにし、失敗した時は何をどこで調べたかを返す 一つの外部エンドポイントまたは操作を包む薄いラッパーを優先します。各連携機能には、小さな検証済み設定オブジェクト、明示的な前提条件またはヘルスチェック、基盤となるリクエストへ直接対応するパラメーターを持つツール関数を用意します。透過的なトランスポート呼び出しのほうが動作とエラーを調べやすい場合は、重いクライアント抽象化を避けます。 呼び出し元が自ら修正できるだけの失敗情報を返します。正確なクエリまたはコマンド、時間範囲、フィルター、関連パラメーター、レスポンス状態、基盤となるエラーメッセージを含めます。データなしの結果では、何をどこで検索したかを明示しなければなりません。アクセス制御を維持し、実行可能なコマンドを検証し、ツールをデフォルトで読み取り専用に保ち、秘密情報を公開したりコミットしたりしないでください。 ## AIが読む前に、ツールが返すデータの量を絞る 範囲が無制限のコレクションをツールから公開してはいけません。大量の結果を返し得るエンドポイントにはサーバー側フィルターを必須とし、呼び出し元が最も重要な範囲パラメーターを省略できないスキーマを設計します。無制限の一覧操作によるトークンまたはメモリのオーバーフローは、プロンプトの問題ではなくツール契約の欠陥です。 リモートサービスで十分な絞り込みができない場合は、最大深度、結果数の上限、フィールド選択、構造化クエリ式など、明示的なクライアント側制御を追加します。切り捨てたことと、適用した制限を報告します。デフォルトのレスポンスは簡潔に保ちつつ、調査に追加の証拠が必要な場合は対象を絞った拡張を可能にします。 ## 古い設定名も動くようにし、共通の動きは正しいクラスの層に置く 設定フィールドの名前を変更する時は、非推奨の名前を追加の入力として受け付け、現在のフィールドへ対応づけ、非推奨警告を出します。公開スキーマとシリアル化した出力には現在の名前だけを残し、互換性対応が生成設定や後続のロジックを汚染しないようにします。 名前の付いた連携機能にフィールド、メソッド、タイムアウト、再試行ポリシーを追加する前に、そのクラス階層と同列の実装を調べます。共有動作は、それを本当に必要とする最も一般的な層に配置します。試行回数と遅延ポリシーを明示できる実績ある再試行機能を使います。標準機構で要件を表現できない場合に限って独自ループを作り、その理由を文書化します。 ## 単体テストからエージェントの評価まで、3つの層でテストする 相互に補完する三つの層を使います。単体テストではローカルの動作を分離し、統合テストではツールとサービスの境界を動かし、エージェント評価では現実的なプロンプトとフィクスチャを使って調査全体の動作を検証します。新しいローカル動作には単体テスト、新しい連携機能には境界のテスト、複雑な調査には評価ケースが必要です。 ソース構造とテスト構造を対応させます。リクエスト動作をテストする時は、上位関数を置き換えるのではなくトランスポート層のHTTPモックを使い、ヘッダー、URL、パラメーター、アダプターが実際に動くようにします。実ツールは意図的に設定した環境でのみ実行し、通常の決定論的テストと、モデルの認証情報または外部サービスを必要とする評価を区別します。 ## でっち上げの答え（ハルシネーション）を見抜く評価を作る 各プロンプトでは、評価で確認する事実そのものを求めます。テスト用に挿入した一意の識別子、正確な件数、タイトル、エラーコードなど、クエリしなければ発見できない期待値を優先します。期待する回答はエージェントから見えない状態に保たなければなりません。回答が一般的すぎて発見を証明できない場合は、正しいツールが呼び出された証拠を求めます。 認識ではなく発見をテストします。中立的なリソース名と現実的なシナリオを使い、実装や予想される解決策を明かさないプロンプトを作ります。モデルが分野知識から推測できる一般的なアサーションは避けます。登録済みのテストタグ、一意のリソース名、固定した依存関係またはイメージのバージョンだけを使い、セットアップでサービスの動作を証明できない場合は明示的に失敗終了させます。 ## 複数のテスト実行が、クラウドのリソースを壊し合わずに共有できるようにする 複数のブランチによるクラウド基盤の評価が、同じアカウント上で重なる可能性を前提とします。セットアップは冪等でなければなりません。リソースがすでに存在しても失敗せず、作成または再利用します。クリーンアップでは、別の実行がまだ使用している可能性のある固定の共有リソースを決して削除してはいけません。クリーンアップを省くか、一意の実行スコープ識別子に限定します。 準備完了の状態だけでなく、実際のAPIレスポンスによって機能を検証します。作成時の競合に対処するため、上限付きの再試行でポーリングし、期待する内容が一度も現れなければ早期に失敗させ、タイムアウト時の診断情報を取得します。複数のテストが同じサービスを必要とする場合は標準化された共有基盤を再利用しますが、各テストのデータと識別子は分離します。 ## ターミナルの表示のずれと評価の悪化を、実際の実行記録から調べる 対話型端末の不具合は疑似端末で再現し、生のエスケープシーケンスを取得します。カーソル移動と消去操作をレンダリングされたフレームの高さと比較し、端末として強制設定したメモリ内ストリームでレンダラーをテストします。ずれを生むフレームまたは更新契約を修正します。端末の最下部で動作が異なる時に、カーソル移動だけを根拠なく修正してはいけません。 エージェント評価の回帰では、ソース差分や集約統計に頼る前に、同じテストとモデルについて一つのベースライントレースと一つの現在のトレースを比較します。レンダリング後のプロンプト、ツール呼び出し順、呼び出しごとの指標、返された証拠を調べます。テンプレートはソース上で増えても実行時には縮むことがあり、集約されたばらつきは実行ごとの決定論的な変化を隠すことがあります。疑わしいリビジョンで最も目立つファイルだけを元に戻す判断をする前に、変更一式をすべて読みます。 ## 整形やチェックは対象のファイルだけにし、許可なくプッシュしない リポジトリ固有のスタイル、型、テスト、バージョン管理ポリシーに従います。ただし、ユーザーまたは適用されるワークフローが明示的に要求しない限り、無関係なファイルを変更すると分かっている広範な自動修正、フォーマット、リポジトリ全体のチェックは実行してはいけません。自動フォーマットとlintは対象ファイルだけに限定し、対応するテストとともにレビューの焦点を保ちます。 インポートと共有ユーティリティはプロジェクトの規約に従って配置し、元に戻せる履歴を保ち、明示的な承認がない限り強制的な履歴の書き換えを避けます。ローカルタスクそのものは、コミット、プッシュ、公開、外部状態の変更を許可するものではありません。実行した検証と、意図的に除外したチェックを報告します。 ## 文書のページや見出しが変わったら、全部の参照を直す プロジェクトの動作を調べる時は、公開Webサイトより先にリポジトリ内の文書を一次情報源として使います。ページの移動、ファイル名の変更、見出しアンカーの変更があった場合は、文書、ソース内の文字列、最上位ガイド、コメントを含むリポジトリ全体から古いパスとアンカーを検索し、影響するすべての参照を更新します。 名前が似ていても使われていない設定ではなく、文書システムが実際に使用するナビゲーションの正本を更新します。必須の空行や有効な見出し階層など、レンダラー固有の構造を保持します。古い機能一覧や繰り返しのセキュリティ文言を避け、簡潔な例と集約されたトラブルシューティングブロックを優先します。連携機能を追加する時は、その概要、インデックス、専用ページ、ナビゲーション項目、ビジュアル素材をまとめて更新します。