AIMockでAIエージェントのテストを決定論的にする — LLM・ベクトルDB・MCP・A2Aを1つのポートでモックする
AIMockはLLM・ベクトルDB・MCP・A2Aを1つのポートでモックします。エージェントのテストスイートは3秒以内に完了し、毎回同じ出力を返します。

目次
はじめに
LLMを使うアプリケーションのテストには厄介な問題があります。同じプロンプトを送っても、毎回微妙に違うレスポンスが返ってくるのです。月曜に通ったテストが、コードは変わっていないのに火曜に落ちます。モデルが非決定論的だからです。
さらに2026年のエージェントアプリは、LLMだけでなくベクトルDB(RAG)、MCPツール、A2Aプロトコルによるエージェント間通信など、1回のリクエストで6〜7個のサービスに触れることも珍しくありません。それぞれのサービスをどうモックするかが課題になります。
CopilotKitが2026年4月にリリースしたオープンソースのモックサーバー「AIMock」は、これらすべてを1つのポートでモックします。この記事で構築するテストスイートは、モック化されたLLM・ベクトルDB・A2Aに対して18個のテストを2.35秒で実行し、毎回まったく同じ出力を返します。
この記事ではまずそのテストスイートを構築します。次にllmock CLIで実際のフィクスチャを録画し、LLMockのカオスAPIで障害を注入します。
AIMockとは何か
AIMockは、AIアプリが通信するすべてのサービスをモックするためのnpmパッケージです。
- 11以上のLLMプロバイダーに対応(OpenAI、Claude、Gemini、Bedrock、Azure、Vertex AI、Ollama、Cohereなど)
- MCP JSON-RPC 2.0のフルサポート
- A2Aエージェントカードの探索とSSEストリーミング
- ベクトルDB(Pinecone、Qdrant、ChromaDB)のモック
- カオステスト(500エラー、不正JSON、ストリーム途中切断の注入。手動サーバーと
setChaos()API両方) - ゼロ依存、Node.jsの組み込みモジュールのみ
「1つの設定ファイル、1つのポートで、AIスタック全体をモックする」というコンセプトです。
類似ツールとの位置づけ
AIMockの競合は何かと調べてみましたが、実はこのニッチには直接の競合がほぼ存在しません。
| ツール | フォーカス | AIMockとの重複 |
|---|---|---|
| Keploy | 実トラフィック録画→テスト自動生成。汎用API向け | AI固有プロトコル(MCP、A2A、ストリーミングSSE)非対応 |
| VCR.py / Polly.js | 古典的なHTTPリクエスト録画・再生 | LLMモックに使えるが、ツールコール等のAI固有機能なし |
| Portkey / Helicone | LLMゲートウェイ。キャッシュ・リプレイ可能 | プロダクション向け。フォールト注入やMCPモックなし |
エージェントアプリをMCP・A2A含めてテストしたい場合、現時点でAIMockが唯一の選択肢と言えます。単純にOpenAI APIのモックだけが必要なら、VCR系のHTTPリプレイで十分です。
フィクスチャの録画・再生はなぜ重要か
AIMockの中核機能の一つが「Record & Replay」です。実APIのレスポンスを録画し、テスト時にそのまま再生する仕組みです。
Record & Replayが解決する問題:
# 月曜: テスト通るassert response.includes("SQL injection risk") ✅
# 火曜: 同じコード、同じプロンプト、OpenAIが言い換えたassert response.includes("SQL injection risk") ❌# "potential SQL vulnerability" が返ってきたフィクスチャを使えば、LLMの呼び出しが純粋関数のように振る舞います。同じ入力に対して、毎回同じ出力です。
| 観点 | フィクスチャなし | フィクスチャあり |
|---|---|---|
| コスト | テスト実行ごとに実APIコール | ゼロ |
| 速度 | LLMコールあたり2〜30秒 | 1ms未満 |
| 決定性 | 毎回異なる出力 | 完全に同一 |
| CI安定性 | ネットワーク・レートリミット・API変更で不安定 | 安定 |
| エッジケース | 再現不可能 | 永続的にキャプチャ |
CI/CDでモックを使うのは「逃げ」ではないか?
モックを使ったCIで検証するのはコードロジックです。プロンプトの品質を確かめるには、引き続き実APIが必要です。
| テスト対象 | 実APIが必要? |
|---|---|
| JSONパーサーがこのレスポンス形状を処理できるか? | No。フィクスチャで十分 |
| リトライロジックが500エラーで動作するか? | No。カオス注入の方が効果的 |
| プロンプトが良い出力を生成するか? | Yes。モックでは不可能 |
| UIがレスポンスを正しくレンダリングするか? | No。フィクスチャで十分 |
実務では2層のCIパイプラインが最適なパターンです。
- 全PR: モック化された高速テスト(コードロジックの検証)
- ナイトリー/週次: 実APIを使った統合テスト(ドリフト検知、プロンプト検証)
AIMockのドリフト検知機能がこれを補完します。CIで毎日、SDKの型定義・実APIレスポンス・AIMockの出力を三方向比較し、プロバイダーのAPI変更をユーザーより先にキャッチします。
デモの構築: 購入代行エージェント
AIMockの主要機能を実際に使い、テストを書いてみました。題材は「購入代行エージェント」です。
アーキテクチャ
1回のリクエストで、エージェントは外部を4回呼び出します。呼び出し先はすべてlocalhost上のモックです。
図の呼び出しは、すべて次のいずれかのモックに届きます。
- LLMock: OpenAI APIのモック(
@copilotkit/aimockのLLMockクラス) - VectorMock: Pinecone互換のベクトルDBモック(
VectorMockクラス) - A2Aモック:
http.createServerで自作したA2Aセラーエージェント
プロジェクト構成
aimock-a2a-demo/├── src/│ ├── buyer-agent/│ │ ├── index.ts # メインのBuyerAgentオーケストレーター│ │ ├── a2a-client.ts # A2Aプロトコルクライアント│ │ ├── knowledge-base.ts # ベクトルDB / RAGレイヤー│ │ └── reasoner.ts # LLM推論│ └── types/│ ├── a2a.ts # A2Aプロトコル型定義│ └── product.ts # 商品関連の型├── tests/│ ├── setup.ts # AIMockのセットアップ│ ├── buyer-agent.test.ts # メインテストスイート│ └── chaos.test.ts # カオステスト├── fixtures/llm/ # 録画されたLLMレスポンス├── aimock.json # AIMock設定ファイル└── package.jsonStep 1: LLMockのセットアップ
LLMockは systemMessage や userMessage のパターンマッチでフィクスチャを登録します。
import { LLMock, VectorMock } from "@copilotkit/aimock";
const llmock = new LLMock({ port: 0 }); // ランダムポート
// システムプロンプトの内容でフィクスチャを振り分けllmock.on({ systemMessage: "evaluating product offers" }, { content: JSON.stringify({ topPickIndex: 0, reasoning: "The MacBook Air M4 offers the best combination...", confidence: 0.92, }),});
llmock.on({ systemMessage: "purchasing concierge" }, { content: JSON.stringify({ refinedQuery: "ultrabook laptop under 1.3kg...", priorities: ["weight under 1.3kg", "battery life 15+ hours"], priceRange: { min: 900, max: 1300 }, }),});
await llmock.start();process.env.OPENAI_BASE_URL = `${llmock.url}/v1`;process.env.OPENAI_API_KEY = "mock-key";onMessage() はユーザーメッセージのテキストのみにマッチします。同じアプリ内でLLMを複数回呼び出す場合(検索戦略の立案とオファー評価で2回など)、ユーザーメッセージの内容が類似していると意図しないフィクスチャにマッチすることがあります。2回の呼び出しはどちらも同じ購入リクエストをユーザーメッセージに含みますが、システムプロンプトはそれぞれ異なります。そのため、on({ systemMessage: "..." }) を使ってシステムプロンプトの内容で振り分けるのが確実です。
2回の呼び出しはユーザーメッセージが同じなので、区別できるのはシステムプロンプトだけです。
LLMockは最初にマッチしたフィクスチャを返すため、より具体的なパターンを先に登録し、キャッチオール(onMessage(/.*/))を最後に登録します。
Step 2: VectorMockのセットアップ
VectorMockはPinecone互換のAPIを提供します。
const vectorMock = new VectorMock({ port: 0 });
vectorMock.addCollection("product-knowledge", { dimension: 1536 });
// 静的な結果を登録 — 毎回同じ結果が返るvectorMock.onQuery("product-knowledge", [ { id: "review-macbook-air", score: 0.94, metadata: { brand: "Apple", model: "MacBook Air M4", text: "MacBook Air M4: 1.24kg, 18hr battery life...", }, }, // ... 他のエントリ]);
await vectorMock.start();QueryResult 型には text フィールドがありません。テキストデータは metadata.text に格納し、アプリ側で m.metadata?.text として取得する必要があります。
また、LLMockの mount() を使えば、VectorMockを同じポートにマウントすることも理論上は可能です。ただし mount() はリクエストを渡す前にパスのプレフィックスを取り除かないため、VectorMockは別ポートで起動する方が確実に動作します。
マウントすると /vector プレフィックスがそのままVectorMockに届きます。別ポートで起動すれば、クエリのパスがエンドポイントに一致します。
Step 3: A2Aプロトコルのモック
A2AはGoogleとLinux Foundationが策定した、エージェント間通信のオープンプロトコルです(v1.2、150以上の組織が参加)。
A2Aは組織をまたいだエージェント通信のためのプロトコルです。自社のエージェントが他社のエージェント(例: 決済処理エージェント、物流エージェント)と通信するケースです。同じアプリ内のサブエージェントにA2Aを使うのはオーバーキルで、関数呼び出しで十分です。
今回のデモでは、バイヤーエージェントとセラーエージェントの間にA2Aを使います。これは異なる組織のエージェントが通信する想定なので、A2Aの正当なユースケースです。
バイヤーエージェントとセラーエージェントは別々の会社に属し、両者のやり取りはすべて HTTP 上の A2A のリクエストとレスポンスです。
A2Aモックは http.createServer で自作しました。A2A v1.0プロトコルに準拠しています。
const server = createServer((req, res) => { // Agent Card探索: GET /.well-known/agent-card.json (v1.0) if (req.url === "/.well-known/agent-card.json" && req.method === "GET") { res.writeHead(200, { "Content-Type": "application/json" }); res.end(JSON.stringify({ name: "Mock Electronics Seller", skills: [{ id: "product-search", name: "Product Search", ... }], ... })); return; }
// JSON-RPC: POST / — SendMessage (v1.0) if (req.method === "POST") { const rpc = JSON.parse(body); if (rpc.method === "SendMessage") { res.end(JSON.stringify({ jsonrpc: "2.0", id: rpc.id, result: { message: { role: "ROLE_AGENT", parts: [{ data: { offers: mockOffers } }], messageId: `reply-${rpc.id}`, contextId: rpc.params?.message?.contextId, }, }, })); } }});バイヤーエージェントのA2Aクライアントは、このモックとも実際のA2A v1.0エージェントとも同じように通信します。実エージェントに向けるときに変わるのはURLだけです。GoogleのCodelabのエージェントをCloud Runで動かして実際に接続した内容は、別の記事にまとめています。
Step 4: テストの実行
18個のテストケースを用意しました。すべて3秒以内で完了します。テストは次の4つのグループに分かれます。
| テストグループ | 件数 | 確認していること |
|---|---|---|
| A2A: Seller Agent Discovery | 3 | バイヤーエージェントがセラーのエージェントカードを読み、SendMessage でオファーを受け取れる |
| Vector DB: Knowledge Base | 3 | 同じクエリには同じ結果が返り、到達不能なサーバーには空の結果が返る |
| Integration: Full Purchasing Flow | 2 | クエリ → RAG → LLM → A2A → LLM の一連の流れが、RAGありでもなしでも動く |
| Chaos と Resilience | 10 | ベクトルDBとLLMを意図的に失敗させ、エージェントがテストの想定どおりに対処する |
$ pnpm test
Test Files 2 passed (2) Tests 18 passed (18) Duration 2.35s決定性:
このテストは同じ入力でナレッジベースに2回クエリし、2つの結果が同一であることを確認します。VectorMockなら毎回成り立ちますが、実際のPineconeにはこの保証がありません。
test("same query twice returns identical results (determinism proof)", async () => { const results1 = await kb.query("laptop"); const results2 = await kb.query("laptop");
// 実際のPineconeでは保証されない expect(results1).toEqual(results2);});グレースフルデグラデーション:
このテストはナレッジベースの接続先を、何も待ち受けていないポートに向けます。RAGの呼び出しはすべて失敗し、それでもエージェントがLLMとA2Aだけで推薦を返すことを確認します。このようにRAGを好きなときに落とせるのは、ホスティングされたPineconeインデックスにはできないことです。
test("works without RAG knowledge (graceful degradation)", async () => { const agent = new BuyerAgent({ sellerAgentUrl: sellerUrl, knowledgeBase: { apiKey: "mock-key", baseUrl: "http://localhost:1", // 到達不能 → フォールバック indexName: "product-knowledge", }, ragTimeoutMs: 500, });
const result = await agent.findProduct({ query: "I need a lightweight laptop for travel", });
// RAGが落ちてもエージェントはLLM + A2Aで動作する expect(result.topPick).toBeDefined(); expect(result.knowledgeUsed).toHaveLength(0);});llmock CLIでフィクスチャを録画する
記事の前半で「Record & Replay」の概念を説明しましたが、実際にやってみました。
llmockの起動
@copilotkit/aimock パッケージには llmock というCLIバイナリが同梱されています。--record フラグで録画モードのプロキシサーバーとして起動します。
# llmockを録画モードで起動(ポート4010でリッスン)pnpm mock:record# → llmock --record --provider-openai https://api.openai.com -f ./fixtures/llmアプリをllmock経由で実行
OPENAI_BASE_URL を llmock に向けるだけで、アプリのOpenAI SDK呼び出しはすべてllmockに送られます。アプリはこれまでどおり .env からAPIキーを読み込んでリクエストに付け、llmockはそのリクエストをキーごとそのままOpenAIに転送し、レスポンスをフィクスチャとして録画します。
OPENAI_BASE_URL=http://localhost:4010/v1 \SELLER_URL=https://burger-agent-XXXXXXXXXX.us-central1.run.app \pnpm dev録画されたフィクスチャ
fixtures/llm/recorded/ に以下のようなJSONが保存されます。
{ "fixtures": [{ "match": { "userMessage": "User request: \"I need a lightweight laptop...\"", "model": "gpt-4o-mini", "turnIndex": 0, "hasToolResult": false }, "response": { "content": "{\"refinedQuery\": \"lightweight travel laptop under $1200\", ...}" }, "metadata": { "systemHash": "a11524e7" } }]}match のフィールド(userMessage、model、turnIndex)がマッチング条件になります。次回以降、同じ条件のリクエストが来たらOpenAIを呼ばずにこのレスポンスを返します。
Record & Replayの実感
pnpm mock:recordでプロキシ起動OPENAI_BASE_URL=http://localhost:4010/v1 pnpm devで普通にアプリを動かすfixtures/llm/recorded/にフィクスチャが自動保存- 次回以降は
pnpm mock:startでフィクスチャを再生するだけ
コードの変更は一切不要。OPENAI_BASE_URL の向き先を変えるだけです。
LLMockのカオス注入機能を試す
Step 4のChaosとResilienceのグループには、setChaos() と nextRequestError() を使うテストが含まれています。これらはLLMockに組み込まれたプログラマティックなカオス注入APIを使っています。Chaos: Vector DB failures と Chaos: LLM failures のテストが500エラーやタイムアウトを再現するために手動でHTTPサーバーを立てているのに対し、こちらはテストサーバーを自作せずに済みます。ベクトルDBのテストはVectorMockにカオスAPIがないため手動サーバーしか選択肢がありませんが、LLMのテストは最初から setChaos() を使うこともできました。
setChaos():確率的フォールト注入
setChaos() で全リクエストに対する障害確率を設定します。
test("setChaos({ malformedRate: 1 }) — every response is garbled", async () => { const mock = new LLMock({ port: 0 });
// 正常なフィクスチャを登録(/.*/で全メッセージにマッチ) mock.onMessage(/.*/, { content: '{"refinedQuery": "test", "priorities": [], "priceRange": {"min": 0, "max": 100}}', });
// カオス設定: 100%の確率でレスポンスを破壊 mock.setChaos({ malformedRate: 1.0 });
await mock.start(); process.env.OPENAI_BASE_URL = `http://localhost:${mock.port}/v1`;
const reasoner = new Reasoner("gpt-4o-mini");
// フィクスチャはマッチするが、カオスが応答を壊す await expect( reasoner.buildSearchStrategy("laptop", []) ).rejects.toThrow();
await mock.stop();});ChaosConfig では障害の種類ごとに確率を指定します。
| パラメータ | 効果 | フィクスチャ不要 |
|---|---|---|
dropRate | 500エラーを返す | はい |
malformedRate | {malformed json: <<<chaos>>>} を返す | いいえ(要マッチ) |
disconnectRate | TCP接続を途中切断する | いいえ(要マッチ) |
注意点として、onMessage("*") はワイルドカードではなくリテラル文字列 * としてマッチします。全メッセージにマッチさせるには正規表現 /.*/ を使います。
clearChaos():カオスの解除
clearChaos() でカオス設定を解除すると、正常なフィクスチャ応答に戻ります。障害からの復旧をテストするのに便利です。
test("clearChaos() restores normal operation", async () => { const mock = new LLMock({ port: 0 }); mock.onMessage(/.*/, { content: validJson }); mock.setChaos({ malformedRate: 1.0 });
await mock.start(); // ... env setup ...
const reasoner = new Reasoner("gpt-4o-mini");
// カオスON — 失敗する await expect( reasoner.buildSearchStrategy("laptop", []) ).rejects.toThrow();
// カオス解除 — 正常に動作する mock.clearChaos();
const strategy = await reasoner.buildSearchStrategy("laptop", []); expect(strategy.refinedQuery).toBe("laptop"); // ✓ 正常なJSON});nextRequestError():ワンショットエラー注入
nextRequestError() は次の1リクエストだけにエラーを返し、その後は自動的に消費されます。「1回だけ失敗して、リトライで復旧する」シナリオのテストに最適です。
test("nextRequestError(400) — single request fails, next succeeds", async () => { const mock = new LLMock({ port: 0 }); mock.onMessage(/.*/, { content: validJson });
// ワンショット: 次の1リクエストだけ400を返す mock.nextRequestError(400, { message: "Bad Request" });
await mock.start(); // ... env setup ...
const reasoner = new Reasoner("gpt-4o-mini");
// 1回目: 400エラー await expect( reasoner.buildSearchStrategy("laptop", []) ).rejects.toThrow();
// 2回目: ワンショットが消費済み → 正常応答 const strategy = await reasoner.buildSearchStrategy("laptop", []); expect(strategy.refinedQuery).toBe("laptop"); // ✓});OpenAI SDKは5xxエラー(500、503等)を自動リトライするため、ワンショットのエラーテストにはリトライされない400番台を使います。
テスト実行結果
$ pnpm test
Test Files 2 passed (2) Tests 18 passed (18) Duration 2.2sどちらのアプローチも動作します。Chaos: Vector DB failures と Chaos: LLM failures のテストは手動で立てたHTTPサーバーを、setChaos() と nextRequestError() のテストはLLMockの組み込みカオスAPIを使っています。agent degrades gracefully はどちらにも属しません。LLMockのAPIを使う方がコードが少なく、意図が明確です。
まとめ
AIMockでLLM・ベクトルDB・A2Aのセラーエージェントをモックし、AIエージェントのテストスイートを構築しました。3秒以内に完了し、毎回同じ出力を返します。
AIMockが効果的なケース:
- LLM + ベクトルDB + 複数サービスを組み合わせたエージェントアプリのテスト
- CI/CDでの高速・低コスト・安定したテスト実行
- フォールト注入による耐障害性の検証
AIMockが適さないケース:
- OpenAI APIだけをモックしたい場合(VCR系のHTTPリプレイで十分)
- プロンプトの品質を評価したい場合(モックでは不可能)
AIMock実装上の注意点:
onMessage()はユーザーメッセージのみにマッチ。on({ systemMessage })でシステムプロンプトでの振り分けが可能onMessage("*")はワイルドカードではなくリテラル*にマッチ。全メッセージにマッチさせるにはonMessage(/.*/)を使う- フィクスチャの登録順序が重要(先にマッチしたものが返る)
- VectorMockの
QueryResultにtextフィールドはない。metadata内に格納する - VectorMockはLLMockとは別ポートで起動するのが安全
setChaos()のmalformedRateとdisconnectRateはフィクスチャのマッチが必要。dropRateのみフィクスチャ不要で動作する- OpenAI SDKは5xxエラーを自動リトライする。
nextRequestError()でエラーをテストする場合は400番台を使う


