AIエージェントは、それが呼び出すAPIの信頼性と同じくらい信頼できます。モデルはツールを選択し、引数を埋め、リクエストを発行します。そのリクエストが失敗したり、間違った形式を返したり、ハングアップしたりすると、エージェントは間違ったデータに基づいて自信満々に決定を下します。ほとんどのエージェントのデモはこの部分をスキップします。本番環境のエージェントはこれにかかっています。
このガイドでは、実際のツールを呼び出すエージェントを構築する方法、そしてさらに重要なことに、ApidogをAPIレイヤーとテストハーネスの両方として使用する方法を示します。ツールのエンドポイントを設計し、オフラインで開発できるようにモックし、ユーザーに到達する前に壊れたツール呼び出しを捕捉するアサーションを作成します。目標は、ハッピーパスが一度うまくいったからではなく、テストしたからこそ信頼できるエージェントを作ることです。
APIレイヤーでエージェントが実際にすること
フレームワークを取り除けば、エージェントのループはシンプルです。
- モデルはユーザーの目標とツールのリストを受け取ります。
- ツール呼び出し（ツール名とJSON引数）を返します。
- あなたのコードはその呼び出しを実行します。通常、これは何らかのAPIへのHTTPリクエストです。
- 結果はモデルに戻されます。
- モデルは別のツールを呼び出すか、応答します。
興味深い失敗はすべてステップ3とステップ4で発生します。モデルが引数を幻覚したり、APIが422を返したり、応答スキーマがずれたり、呼び出しがタイムアウトしたり、ループ中にレート制限がかかったりします。AIエージェントが新しいAPIコンシューマーであることについて読んだことがあるなら、これはそのアイデアの具体的なバージョンです。つまり、あなたのエージェントはAPIを叩くクライアントであり、他のどのクライアントとも同じテストの厳密さが必要です。
したがって、作業は2つに分かれます。ツールを実際のテスト可能なAPI操作として定義し、次に、良い条件と悪い条件の両方でエージェントがそれらを正しく呼び出すことを検証します。
ステップ1: ツールを実際のAPI操作として設計する
エージェントのコードを一行も書く前に、各ツールをApidogでAPIエンドポイントとして定義します。ツールのスキーマとAPIスキーマを同じものとして扱います。なぜなら、それらは同じものだからです。get_weatherツールとGET /weatherエンドポイントは、同じパラメーター、同じ応答形式というコントラクトを共有します。
Apidogで、各ツールに対してOpenAPIスキーマ（パス、クエリ、ボディパラメーター、型付き応答）を持つエンドポイントを作成します。これにより、3つのことが無料で手に入ります。
- エージェントのプロンプトとテストの両方が参照する、ツールのコントラクトの単一の真実源。
- ツール定義としてモデルに渡すことができる自動生成されたドキュメント。
- 後で検証するためのスキーマ。これにより、応答が一致しなくなった瞬間にずれを検出できます。
このスキーマファーストの習慣は、堅牢なAPI設計作業全般の背後にあるものと同じです。エージェントにとってのメリットは具体的です。ツール定義と実際のエンドポイントが1つのスキーマから作成される場合、モデルはAPIがサポートしていないツールを呼び出すことはできません。
ステップ2: オフラインで構築できるようにツールをモックする
すべての開発実行で、費用がかかる、レート制限が適用される、またはまだ構築されていないライブAPIを叩きたいとは思いません。Apidogは、定義したスキーマから直接モックサーバーを生成します。各ツールエンドポイントは、バックエンドなしで、リアルでスキーマ検証済みのサンプルデータを返します。
これは、エージェントの構築方法を変えます。これにより、次のことが可能になります。
- 実際のAPIが存在する前に、合意された契約に一致するモックに対して完全なエージェントループを開発できます。
- 有料のエンドポイントに触れることなく、CIで統合テストを実行できます。
- 特定のリスポンス（空の結果、500エラー、不正な形式のフィールドなど）を強制して、エージェントがどのように反応するかを確認できます。
開発中にエージェントのツールエグゼキューターをモックのベースURLに向けます。モデルがget_weatherを呼び出し、あなたのコードがApidogモックを叩き、有効な応答が即座に返されます。本番環境の準備ができたら、環境変数を通じてベースURLを切り替えます。モックは、エージェントの開発を高速かつ決定論的にするものです。この同じアプローチが、あらゆる本格的なAIエージェントテストのワークフローを支えています。
ステップ3: エージェントがツールを呼び出すように配線する
エンドポイントとモックが整っていれば、エージェントのコードは薄く済みます。以下は、Claude Messages APIを使用したツール呼び出しループの形式です。ツール定義はApidogで構築したスキーマを反映しています。
import anthropic, requests, os
client = anthropic.Anthropic()
TOOL_BASE = os.environ["TOOL_BASE_URL"] # 開発中はApidogのモック、本番環境では実際のAPI
tools = [{
"name": "get_weather",
"description": "都市の現在の天気を取得する",
"input_schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
}]
def run_tool(name, args):
if name == "get_weather":
r = requests.get(f"{TOOL_BASE}/weather", params={"city": args["city"]}, timeout=10)
r.raise_for_status()
return r.json()
messages = [{"role": "user", "content": "今日の東京の服装は何が良いですか？"}]
while True:
resp = client.messages.create(
model="claude-fable-5", max_tokens=1024, tools=tools, messages=messages
)
if resp.stop_reason == "tool_use":
block = next(b for b in resp.content if b.type == "tool_use")
result = run_tool(block.name, block.input)
messages.append({"role": "assistant", "content": resp.content})
messages.append({"role": "user", "content": [{
"type": "tool_result", "tool_use_id": block.id,
"content": str(result),
}]})
else:
print(resp.content[0].text)
break
timeout=10とraise_for_status()の行は、モデル呼び出しよりも重要です。これらは、大声で失敗するエージェントと、ハングアップまたはエラーになったリクエストをサイレントにループにフィードバックするエージェントの違いです。エージェントがAPIワークフローにどのように適合するかをより広く理解するには、APIワークフローのための5つのAIエージェントのパターンが役立ちます。
ステップ4: ツール呼び出しをテストする。雰囲気だけではない。
ほとんどのチームがスキップする部分がここにあります。各ツールエンドポイントをApidogに保存されたリクエストとして、モデルとは独立してアサーション付きで実行します。エージェントの信頼性は、そのツールの信頼性に制限されるため、まずツールをテストします。
各ツールエンドポイントで、以下をアサートします。
- 有効な入力の場合、ステータスは
200である。 - レスポンスボディがスキーマに一致する。ApidogはあなたのOpenAPI定義に対してレスポンスを自動的に検証します。
- モデルが読み取る必須フィールドが存在し、正しく型付けされている。
- レスポンス時間がエージェントが強制するタイムアウト内である。
次に、エージェントが誤動作する可能性のある不測の事態をテストします。
- モデルが幻覚する可能性のある不正な引数（空の
city、文字列であるべき場所に数字など）を送信し、500ではなくクリーンな400/422が得られることをアサートします。 - モックからエラー応答を強制し、エージェントの
run_toolがガベージを返す代わりに例外を発生させることを確認します。 - 空の結果をテストし、エージェントが回答をでっち上げるのではなく、「データなし」を処理することを確認します。
これはエージェントツールに適用される契約テストです。API契約テストでカバーされているのと同じ規律が、モデルが呼び出すエンドポイントに向けられています。ツールのレスポンス形式がずれると、CIでアサーションが失敗し、エージェントが壊れたペイロードで推論を開始する前にそれを修正できます。
ステップ5: リトライ、タイムアウト、レート制限を処理する
エージェントは不安定なAPIを増幅させます。通常のアプリでの1回の再試行は1回の再試行ですが、エージェントループでは、失敗し続けるツールを呼び出し続けるモデルが、レート制限と予算をあっという間に使い果たしてしまう可能性があります。制御を構築し、それらをテストします。
- タイムアウト。上記の例のように、すべてのツールリクエストに明示的なタイムアウトを設定します。次に、Apidogを使用して低速なエンドポイントをシミュレートし、クライアントがループ全体をハングさせるのではなく、きれいに諦めることを確認します。
- バックオフ付きリトライ。一時的な障害は再試行しますが、回数を制限し、バックオフします。2回失敗してから成功するモックに対してテストし、エージェントが永遠にループするのではなく回復することを確認します。
- レート制限。負荷がかかると
429が発生することを想定します。レート制限された応答をモックし、エージェントが叩き続けるのではなく、待機して再試行することを確認します。生のモデルAPIでこれに対処したことがある場合、GPT APIのレート制限で同じ種類の問題を参照してください。エージェントバージョンは、ループがすべての呼び出しを乗算するため、より厳密です。 - サーキットブレーカー。ツールでN回失敗した後、呼び出しを停止し、エージェントが問題を報告するようにします。ブレーカーが作動することをテストします。
これらをApidogで繰り返し可能なシナリオとして実行し、エラー処理の回帰が本番環境のインシデントではなく、失敗したテストとして現れるようにします。
ステップ6: CIでモックに対してエンドツーエンドで実行する
全てをまとめます。CIで、Apidogモックサーバーに向けたエージェントを開始し、固定されたユーザー目標セットを与え、最終的な結果とツール呼び出しのシーケンスをアサートします。モックは決定論的であるため、同じ入力は毎回同じツール呼び出しを生成します。これにより、エージェントテストは不安定ではなくなります。自信がついたら、ベースURLを実際のAPIに切り替えて、より小規模なライブスモークテストを行います。この分割（テストの大部分は決定論的なモック、現実のための薄いライブチェック）こそが、エージェントAIテストを願望ではなく実践的なものにする理由です。
信頼できるエージェントのためのチェックリスト
- [ ] すべてのツールが、OpenAPIスキーマを持つ実際のAPI操作として定義されている。
- [ ] オフラインで構築およびテストできるように、すべてのツールにモックが存在する。
- [ ] 各ツールエンドポイントには、ステータス、スキーマ、およびタイミングに関するアサーションがある。
- [ ] 不測の事態（不正な引数、エラー、空の結果）が明示的にテストされている。
- [ ] タイムアウト、バックオフ付きリトライ、およびレート制限処理がコードに組み込まれ、テストされている。
- [ ] エンドツーエンドのCI実行が、決定論的なモックに対して完全なループを実行する。
これら6つすべてをクリアすれば、希望ではなく証拠に基づいて信頼性を説明できるエージェントが手に入ります。
よくある質問
なぜエージェントを実行するだけでなく、APIクライアントを使ってエージェントをテストするのですか？エージェントを実行すると、モデルとツールが一緒にテストされるため、失敗した場合に原因が不明確になります。Apidogで各ツールエンドポイントをテストすることで、APIレイヤーが分離され、問題がモデルの推論にあるのか、それともツールの破損にあるのかがわかります。
エージェントを構築する前に、実際のAPIを構築する必要がありますか？いいえ。Apidogでツール契約をスキーマとして定義し、モックを生成し、それらのモックに対してエージェントループ全体を構築します。後で環境変数を通じて実際のAPIエンドポイントに置き換えます。
失敗するツールでエージェントが永遠にループするのを止めるにはどうすればよいですか？リトライを制限し、バックオフを追加し、繰り返し失敗した後にサーキットブレーカーを作動させて、エージェントがスピンする代わりに問題を報告するようにします。エラーを返すモックに対して各制御をテストします。
モデルやAPI呼び出しに費用をかけずにエージェントをテストできますか？ほとんどの場合、可能です。ApidogでツールAPIをモックし、決定論的で無料の統合テストを実行し、ライブモデル呼び出しは小規模なスモークテストスイートにとどめます。
これはLangChainやClaude Agent SDKのようなフレームワークでも機能しますか？はい。ツールレイヤーは単なるHTTPです。ループを駆動するフレームワークが何であれ、テストにはApidogモックを、本番環境には実際のAPIエンドポイントをポイントします。Claude Code SDKガイドにそのようなループの一例が示されています。
まとめ
信頼できるエージェントは、より賢いプロンプトではありません。テストされたツールレイヤーです。ツールを実際のAPI操作として定義し、開発が高速かつ決定論的になるようにモックし、すべての応答形式をアサートし、意図的に失敗をテストします。Apidogは、これらのエンドポイントを設計し、モックし、テストハーネスとして実行する単一の場所を提供するため、エージェントの動作を証明することができます。Apidogをダウンロードして、実際に本番環境で信頼できるエージェントを構築してください。