デモではエージェントが動作していました。チケットを読み込み、3つのAPIを呼び出し、きれいな要約を投稿しました。そしてあなたはそれをリリースしました。1週間後、エージェントは同じ顧客に2度メールを送り、リトライループで1日分のトークン予算を使い果たし、フロントエンドが解析できないペイロードを渡しました。
動作するプロトタイプと信頼性の高いエージェントの間のギャップこそ、ほとんどのチームが立ち往生する場所です。モデルが原因であることは稀です。問題は、配管のように扱われる部分、つまりエージェントが回答を得る途中で行うAPI呼び出しにあります。エージェントはツール呼び出しのループであり、すべてのツール呼び出しは、失敗したり、スロットリングされたり、タイムアウトしたり、予期しないものを返したりするHTTPリクエストです。本番APIをテストするのと同じようにこれらの呼び出しのテストを怠ると、あなたのエージェントはたった1つの悪い応答でインシデントを引き起こす可能性があります。
ここで安心できることがあります。エージェントの信頼性はテスト可能です。モデルが正しく動作することを信頼する必要はありません。ユーザーが障害パスを発見する前に、意図的に障害パスを検証することができます。このガイドでは、エージェントの障害を5つのモードに分類し、それぞれを捕捉する方法を示します。作業はAPI境界で発生するため、エージェントの依存関係を指し示し、契約を設計し、障害をモックし、返されるものを確認できるプラットフォームが必要です。Apidogがその役割を担い、以下の例で説明します。
エージェントはプロンプトではなくAPI境界で失敗する
エージェントが本番環境で誤動作すると、プロンプトを編集しようとするのが本能です。それが役立つこともありますが、多くの場合、失敗は言葉遣いとは関係ありません。エージェントが実際のAPIに何かを要求し、その応答が遅かったり、不正な形式だったり、レート制限されたり、エージェントが期待していたものとは異なる形だったりしたのです。その後、モデルは不良な入力に基づいて推論し、自信満々に間違ったことを実行しました。
エージェントの単一のステップが何を含むか見てみましょう。モデルがツールを選択します。あなたのコードはその選択をHTTPリクエストに変換します。外部サービスが応答します。あなたのコードはその結果をモデルにフィードバックします。4つの引き渡しがあり、そのうち3つは機械学習ではなく、通常のAPI統合です。これは良いニュースです。なぜなら、API統合は解決済みのテスト問題だからです。遅いエンドポイントをモックしたり、JSONスキーマをアサートしたりする方法はすでに知っています。エージェントは、モデルがクリーンな例外をスローする代わりに受け取ったものに基づいて動作するため、リスクを高めます。
したがって、信頼性の問題は「モデルは十分賢いか」ではなく、「エージェントのAPI呼び出しが横道にそれる可能性のあるすべての方法をテストしたか」です。5つのモードがそのほとんどをカバーします。
失敗モード1：契約から逸脱するツール呼び出し
最も一般的なエージェントの失敗は、呼び出しているAPIと一致しないツール呼び出しです。モデルがパラメーターを発明したり、必須フィールドを削除したり、スキーマが整数を要求している場所に文字列を送信したり、意味のない引数で正しいエンドポイントを呼び出したりします。例えば、予約エージェントがguests: 2ではなくguests: "two"でPOST /reservationsを呼び出したとします。APIは400を返すか、さらに悪いことに、ボディにエラーが埋め込まれた200を返し、エージェントは成功したかのように処理を続けます。
これは、ツール呼び出しを契約としてテストすることで捕捉できます。エージェントが呼び出すことができる各ツールのスキーマを定義し、送信されるリクエストが一致すること（必須フィールドが存在すること、型が正しいこと、enumが有効であること）をアサートします。エージェントが契約に違反する呼び出しを生成した場合、それが本番環境で静かに失敗するのではなく、テストで大々的に失敗することを望みます。AIエージェントのツール呼び出しをテストするに関する詳細な解説でこれについて深く掘り下げており、APIを呼び出すエージェントをテストするためのより広範な方法は、エンドツーエンドのセットアップをカバーしています。
実用的な対策：エージェントが使用するツールスキーマをキャプチャし、それらをApidogに読み込み、エージェントの実際のツール呼び出しをそれらの定義に対して実行します。不一致は、破損した正確なフィールド名を挙げる検証エラーとして現れます。
失敗モード2：アップストリームエラーとレート制限
エージェントが行うすべての外部呼び出しは、タイムアウト前に429、500、または何も返さない可能性があります。適切に構築されたエージェントは、リトライとバックオフでこれらを処理します。脆弱なエージェントは、最初のエラーで諦めるか、より危険なことに、過度にリトライしてさらなるスロットリングを引き起こし、予算を使い果たすループに陥ります。Anthropic SDKのディスカッションボードで最もよく尋ねられる質問は、文字通りエージェントのエラー回復パターンについてであり、この問題がどれほど一般的であるかを示しています。
健全なAPIに対して回復をテストすることはできません。なぜなら、健全なAPIは処理する必要があるエラーを返さないからです。ここでモックが役立ちます。エージェントの依存関係のモックを立ち上げ、シーケンスをプログラムします。Retry-Afterヘッダー付きの429、次に500、そして成功です。次に、エージェントが何をするかを確認します。ジッター付きでバックオフしますか？ヘッダーを尊重しますか？妥当な回数の試行後に gracefully に諦めますか、それとも明らかに停止しているサービスを叩き続けるのをやめるためにサーキットブレーカーを開きますか？また、リトライされたアクションが冪等ではない場合、繰り返しによって二重課金や二重送信が発生しますか？冪等性キーは、リトライを安全に繰り返すことを可能にします。
レート制限はそれ自体でリハーサルする価値があります。プロバイダーがエージェントをスロットリングしたときに、エージェントがどのように動作するかを見たことがない場合は、レート制限超過応答の意味に関するガイドを読んでからシミュレーションしてください。AIエージェントのエラー回復に関する専用ガイドでは、リトライ、タイムアウト、バックオフ、およびサーキットブレーカーのパターンを完全に網羅しています。
失敗モード3：非決定的な出力
温度をゼロに設定しても、実行間でバイト単位で同一の出力は得られません。開発者は常にこのことを再発見しています。シードと温度だけでは再現性が不十分であるというvLLMのスレッドは長く続いています。ハードウェア、バッチ処理、プロバイダー側の変更がすべてバリエーションをもたらします。テストが厳密な文字列をアサートする場合、それらは不安定になり、不安定なテストは無視されてしまい、テストがないよりも悪い状況になります。不安定なテストの原因に関する私たちの説明がここに直接当てはまります。
解決策は、厳密なテキストではなく、構造と意味をアサートすることです。応答がJSONスキーマに対して検証されることを確認します。ツール呼び出しが正しい形と正しいターゲットを持っていることを確認します。数値の回答が妥当な範囲内にあることを確認します。必須キーが存在し、禁止されたフィールドがないことを確認します。「返信には0からカートの値までのtotalが含まれる」というテストは、モデルの自然なバリエーションを乗り越えながらも、実際のリグレッションを捕捉します。非決定的なAIエージェントのテストに関するガイドでは、戦略の全セットが示されており、エージェントのメモリがどのように機能するかに関する記事は、状態がこれを難しくする理由を示しています。
失敗モード4：暴走するコスト
エージェントはループし、ループにはコストがかかります。数千回にわたって失敗した呼び出しをリトライする1つのスタックしたエージェントは、小さな請求書を一晩で大きなものに変える可能性があります。SDKのディスカッションにある現場レポートの1つでは、品質を損なうことなくエージェントのコストを月500ドルから80ドルに削減したと記述されており、コストがいかに早く増加するか、そして設計に通常どれほどの余裕が隠されているかを示しています。
コストは財務上の問題だけでなく、信頼性の問題でもあります。なぜなら、無駄なコストを発生させるバグ（ループ、冗長な呼び出し、過大なコンテキスト）は、エージェントを遅くし、予測不能にするからです。実行あたりのトークンを追跡し、タスクごとの予算を上限設定し、可能な限りキャッシュしてください。コマンドライン側のこれについては、エージェントのトークンコストを削減するに関するガイドで具体的な手段を説明しています。モックに対して回復パスをテストする際には、呼び出し回数も確認してください。成功したが、そのために40回の呼び出しを行うエージェントは、コストインシデント発生を待っている状態です。
失敗モード5：ガードレールがない
最も痛手となる失敗は、エージェントが指示された通りに正確に実行したにもかかわらず、結果が依然として悪い場合です。モデルの決定と実際の行動の間に何も障壁がなかったため、メールを送信したり、レコードを削除したり、注文を行ったりします。SDKの掲示板には、あるエージェントが午前3時に誰かの上司にメールを送信したことに関する記憶に残るスレッドがあります。最初は面白いが、2度目は高くつくものです。
ガードレールはシートベルトです。承認なしにエージェントが実行できるアクションに許可リストを設定してください。破壊的または不可逆的な呼び出しは、人間の確認を介してゲートしてください。エージェントに、実際に実行せずに何をするかを記述するドライランモードを与えます。次に、ガードレールが保持されていることをテストします。副作用のあるエンドポイントをモックし、エージェントを実行し、それが実際の行動ではなく確認パスに到達することを確認します。LLMアプリケーションのOWASP Top 10のようなセキュリティガイダンスは、保護すべきものの確実なチェックリストとなります。AIエージェントのガードレールに関するガイドでは、承認ゲートと爆発半径制御について詳しく説明しています。
エージェントテストの構造
5つのモードは1つのテスト形式を共有しており、それを再利用できます。
- エージェントが呼び出すことができるツールスキーマをキャプチャし、アサートするための契約を持つようにします。
- タイミング、ステータスコード、ボディを制御し、実際の副作用を避けるために、各依存関係をモックします。
- ライブAPIがオンデマンドで生成しないような不都合なパスを含め、シナリオを通じてエージェントを駆動します。
- エージェントが送信したものと、それがどのように反応したか（リクエストの形状、回復動作、呼び出し回数、ガードレールが発動したかどうか）をアサートします。
1つのツールに対してそのループを実行し、次に別のツールを追加します。この設定は、ユーザーが発見する前に壊れたツール呼び出しを最初に捕捉したときに、その価値を証明します。
エージェントの信頼性チェックリスト
エージェントを本番環境に投入する前に、このリストを確認してください。
- すべてのツール呼び出しはスキーマに対して検証され、契約違反はテストを失敗させます。
- アップストリームの429、500、およびタイムアウト応答はシミュレートされ、エージェントはバックオフで回復します。
- リトライされたアクションは冪等であるため、繰り返しによって二重課金や二重送信は発生しません。
- テストは厳密な文字列ではなく、構造と意味をアサートするため、通常のバリエーションが不安定さを引き起こすことはありません。
- 実行あたりのトークン使用量が測定され、予算上限が暴走ループを停止させます。
- 破壊的なアクションは、許可リストまたは人間の承認ゲートの背後にあります。
- ガードレールパスはモックでテストされ、仮定されません。
これら7つすべてにチェックマークを付ければ、エージェントが本番環境で故障する可能性のある方法をテストしたことになります。
Apidogが適合する点（およびしない点）
ツールの役割を明確にしてください。Apidogはエージェントフレームワーク、モデルホスト、または評価ハーネスではありません。あなたのエージェントを構築したり実行したりするものではありません。Apidogが行うのは、あなたのエージェントが依存するAPIレイヤーを所有することであり、まさにこれらの失敗が存在する場所です。
実際には、これは3つのことを意味します。エージェントが呼び出すツールの契約を設計および保存し、それらに対して送信リクエストを検証できるようにします。これらの依存関係をモックし、ライブAPIがオンデマンドで生成しない失敗応答（429、500、タイムアウト、不正な形式のボディ）をプログラムすることで、回復をリハーサルできます。そして、非決定的な出力でも有効な応答（スキーマ、形状、範囲、必須キー）に対するアサーションを作成します。それがApidogの正直な適合性です。Apidogはエージェントが呼び出すAPIをテストし、処理する必要のある失敗をモックし、返されるものをチェックします。エージェントAIテストの概要では、これをより広いQAの観点から位置付けています。
よくある質問
エージェントの信頼性はモデルの問題ですか、それともエンジニアリングの問題ですか？ ほとんどはエンジニアリングの問題です。モデルの選択は重要ですが、インシデントを引き起こす失敗（不適切なツール呼び出し、未処理のレート制限、ガードレールの欠如）は、モデルを変更せずに解決できる統合とテストの問題です。
エージェントが呼び出す実際のAPIにアクセスせずにエージェントをテストできますか？ はい、できますし、そうすべきです。依存関係をモックして、エラー応答を強制したり、タイミングを制御したり、副作用を回避したりできるようにします。それが回復パスとガードレールパスをテストする唯一の信頼できる方法です。
実行ごとに出力が変わる場合、どのようにテストを作成すればよいですか？ 厳密なテキストではなく、構造と意味をアサートしてください。応答をスキーマに対して検証し、ツール呼び出しの形状を確認し、数値には範囲を使用してください。非決定的なAIエージェントのテストに関するガイドで詳しく説明されています。
まず何をテストすべきですか？ 破壊的なアクションに対するガードレール、次いでエラー回復です。これら2つは、最もコストのかかる失敗（エージェントが有害なアクションを実行したり、エージェントがループして予算を使い果たしたりする）からあなたを保護します。
まず1つの失敗モードから始める
5つのモードすべてを一度にテストする必要はありません。最も恐ろしいもの、通常はガードレールかエラー回復を選び、今週中にモックに対してリハーサルしてください。失敗をプログラムし、エージェントを実行し、その動作を確認します。予算を使い果たすループではなく、クリーンなバックオフでシミュレートされた429をエージェントが処理するのを初めて見たとき、あなたはデモの成功以上の良い理由で、それをより信頼するようになるでしょう。
エージェントが依存する契約の設計、失敗のモック、および応答のアサートを行うには、Apidogをダウンロードしてください。