我用 AIMock 在單一連接埠模擬 LLM、向量資料庫、MCP 與 A2A,讓 AI 代理測試每次結果都相同
AIMock 在單一連接埠上模擬整個 AI 技術堆疊(LLM、向量資料庫、MCP、A2A)。這樣一來,AI 代理的測試套件能夠在三秒內執行完畢,而且每次的輸出都相同。

本頁目錄
引言
測試建立在 LLM 之上的應用程式時,會遇到一個麻煩的問題:同一個提示詞送兩次,回來的內容會稍有不同。週一通過的測試,到了週二卻失敗了,即使程式碼完全沒有改動。這是因為模型本身是非決定性的。
2026 年的 AI 代理應用程式讓這個問題變得更嚴重。單一請求會用到六、七個服務:除了 LLM 之外,還有用於檢索增強生成(RAG)的向量資料庫、Model Context Protocol(MCP)工具,以及 AI 代理之間透過 Agent2Agent(A2A)協定傳遞的流量。因此真正的問題變成了:這些服務要怎麼一個一個模擬?
AIMock 是 CopilotKit 在 2026 年 4 月釋出的開源模擬伺服器,只要一個連接埠就能模擬 LLM、向量資料庫、MCP 與 A2A 這些服務。本文建立的測試套件會對模擬的 LLM、向量資料庫與 A2A 服務執行 18 個測試案例,總共只花 2.35 秒,而且每次的輸出在位元組層級都完全相同。
本文會先建立這套測試套件,接著用 llmock CLI 錄製真實的測試固件,最後用 LLMock 的混沌 API 注入故障。
AIMock 是什麼
AIMock 是一個 npm 套件,能夠模擬 AI 應用程式會串接的所有服務。
- 11 種以上的 LLM 供應商(OpenAI、Claude、Gemini、Bedrock、Azure、Vertex AI、Ollama、Cohere 等)
- 完整支援 MCP JSON-RPC 2.0
- 支援 A2A 的 Agent Card 探索,以及 server-sent events(SSE)串流
- 向量資料庫模擬(Pinecone、Qdrant、ChromaDB)
- 混沌測試:能夠注入 500 錯誤、格式錯誤的 JSON,以及串流中途斷線。可以自行實作伺服器來注入,也可以透過
setChaos()API 來注入 - 零相依套件,只用 Node.js 內建模組
AIMock 的核心概念是:只用一個設定檔、一個連接埠,就能涵蓋整個 AI 技術堆疊。
AIMock 在同類工具中的定位
我找了一下 AIMock 的競爭產品,發現這個領域幾乎沒有直接的對手。
| 工具 | 定位 | 與 AIMock 的重疊 |
|---|---|---|
| Keploy | 錄製真實流量並產生測試,以通用 API 為對象 | 不支援 AI 專屬協定(MCP、A2A、SSE 串流) |
| VCR.py / Polly.js | 傳統的 HTTP 錄製與重播 | 可以用來模擬 LLM,但沒有工具呼叫這類 AI 專屬功能 |
| Portkey / Helicone | 具備快取與重播的 LLM 閘道 | 以 production 環境為主,沒有故障注入,也不模擬 MCP |
如果要測試包含 MCP 與 A2A 的 AI 代理應用程式,AIMock 是目前唯一的選擇。如果只需要模擬 OpenAI API 的話,VCR 式的 HTTP 重播就夠用了。
為什麼要錄製與重播測試固件?
錄製與重播是 AIMock 的核心功能之一:先擷取一次真實的 API 回應,之後在測試中原封不動地重播。
錄製與重播能夠解決下面這種問題:
# 週一:測試通過assert response.includes("SQL injection risk") ✅
# 週二:同樣的程式碼、同樣的提示詞,OpenAI 換了說法assert response.includes("SQL injection risk") ❌# 回傳的是 "potential SQL vulnerability"有了測試固件之後,LLM 呼叫的行為就會像純函式一樣:只要輸入相同,每次得到的輸出也會相同。
| 面向 | 沒有測試固件 | 有測試固件 |
|---|---|---|
| 成本 | 每執行一次測試就呼叫一次真實 API | 零 |
| 速度 | 每次 LLM 呼叫 2–30 秒 | 1 毫秒以內 |
| 決定性 | 每次輸出都不同 | 位元組層級完全相同 |
| CI 穩定度 | 會因網路、速率限制、API 變更而不穩定 | 穩定 |
| 邊界情況 | 無法重現 | 可以永久保留 |
在 CI 裡用模擬 LLM 的回應,是不是在逃避問題?
CI 裡的模擬測試檢查的是程式邏輯。至於提示詞的品質,還是得用真實 API 來驗證:
| 要測試的項目 | 需要真實 API 嗎? |
|---|---|
| JSON 解析器能處理這種回應結構嗎? | 不需要,測試固件就夠了 |
| 遇到 500 錯誤時,重試邏輯有效嗎? | 不需要,混沌注入更合適 |
| 提示詞能不能產出好的輸出? | 需要,用模擬無法驗證 |
| UI 有正確算繪出回應嗎? | 不需要,測試固件就夠了 |
實務上最好的做法是採用兩層的 CI 工作流:
- 每個 PR:執行快速的模擬測試,驗證處理 AI 回應的程式邏輯
- 每晚或每週:對真實 API 執行整合測試,偵測偏移並驗證提示詞的品質
AIMock 的偏移偵測功能正好可以搭配兩層 CI 工作流使用。只要每天在 CI 裡執行一次,偏移偵測就會比對三樣東西:SDK 的型別定義、真實 API 的回應,以及 AIMock 本身的輸出。這樣一來,供應商一旦變更了 API,就能在使用者發現之前先察覺。
製作 demo:智慧採購助理
為了實際試用 AIMock 的主要功能,我為一個採購 AI 代理寫了測試。
架構
處理一次請求時,AI 代理會向外發出四次呼叫,而每一次都是由 localhost 上執行的模擬服務回應。
圖中的每一次呼叫,都是由下列其中一個模擬服務回應:
- LLMock:模擬 OpenAI API(
@copilotkit/aimock的LLMock類別) - VectorMock:與 Pinecone 相容的向量資料庫模擬(
VectorMock類別) - A2A 模擬:我用
http.createServer自行實作的賣家 AI 代理
專案結構
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.json步驟 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 不只一次(這個 demo 呼叫了兩次,一次用來規劃搜尋策略,一次用來評估報價),相似的使用者訊息就可能比對到預期之外的測試固件。兩次呼叫的使用者訊息都帶著同一個購物需求,但各自的系統提示詞不同。因此,改用 on({ systemMessage: "..." }) 依系統提示詞的內容來分派,才是比較可靠的做法。
兩次呼叫的使用者訊息相同,所以只能透過系統提示詞來區分這兩次呼叫。
LLMock 會回傳第一個比對成功的測試固件,所以要先註冊比較明確的模式,最後才註冊比對所有訊息的 onMessage(/.*/)。
步驟 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 掛載到 LLMock 的連接埠上。但是 mount() 在轉交請求之前不會去掉路徑前綴,所以實際可行的做法是讓 VectorMock 在自己的連接埠上執行。
掛載時,/vector 前綴會原封不動地傳到 VectorMock;讓 VectorMock 在自己的連接埠上執行時,查詢路徑就會符合它的端點。
步驟 3:模擬 A2A 協定
A2A 是 Google 與 Linux Foundation 推出的開放協定,用於 AI 代理之間的通訊。版本為 v1.2,參與的組織超過 150 個。
A2A 是為跨組織的 AI 代理通訊而設計的:讓自己的 AI 代理和另一家公司的 AI 代理對話,例如金流業者或物流業者的 AI 代理。如果只是在同一個應用程式內部的子 AI 代理之間溝通,用 A2A 就是殺雞用牛刀了,因為直接用函式呼叫就夠了。
在這個 demo 裡,買家 AI 代理與賣家 AI 代理之間是透過 A2A 溝通的。這兩個 AI 代理設定上分屬不同組織,所以用 A2A 連接這兩個 AI 代理是合理的。
買家 AI 代理與賣家 AI 代理分屬不同公司,這兩個 AI 代理之間的每一次往來,都是透過 HTTP 傳遞的 A2A 請求與回應。
我用 http.createServer 自行實作了 A2A 模擬,並讓這個模擬符合 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, }, }, })); } }});買家 AI 代理的 A2A 用戶端,跟這個模擬溝通時和跟真實的 A2A v1.0 AI 代理溝通時完全一樣。因此,改成連到真實的 AI 代理時,只需要換一個 URL。我把 Google codelab 的 AI 代理部署到 Cloud Run 並實際連線的過程,寫在另一篇文章裡。
步驟 4:執行測試
18 個測試案例全部在三秒內執行完畢。這些測試案例分成四組:
| 測試群組 | 案例數 | 驗證的內容 |
|---|---|---|
| A2A: Seller Agent Discovery | 3 | 買家 AI 代理能夠讀取賣家的 Agent Card,並透過 SendMessage 取得報價 |
| Vector DB: Knowledge Base | 3 | 相同的查詢會得到相同的結果,連不到伺服器時則回傳空結果 |
| Integration: Full Purchasing Flow | 2 | 查詢 → RAG → LLM → A2A → LLM 的完整流程,不論有沒有 RAG 都能運作 |
| Chaos 與 Resilience | 10 | 故意讓向量資料庫與 LLM 失敗,AI 代理會依照測試預期的方式處理 |
$ pnpm test
Test Files 2 passed (2) Tests 18 passed (18) Duration 2.35s決定性:
這個測試用相同的輸入查詢知識庫兩次,並驗證兩次的結果完全相同。使用 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 呼叫都失敗。接著驗證 AI 代理仍然能夠只靠 LLM 與 A2A 回傳推薦結果。如果用的是託管的 Pinecone 索引,就沒辦法像這樣隨時讓 RAG 停擺。
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 停擺,AI 代理仍能靠 LLM + A2A 運作 expect(result.topPick).toBeDefined(); expect(result.knowledgeUsed).toHaveLength(0);});用 llmock CLI 錄製測試固件
前面只從概念上介紹了錄製與重播,接下來我實際操作了一次。
啟動 llmock
@copilotkit/aimock 套件附帶一個名為 llmock 的 CLI 執行檔。加上 --record flag 啟動時,llmock 會作為錄製用的代理伺服器運行。
# 以錄製模式啟動 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)就是重播時比對的條件。之後只要請求符合同樣的條件,llmock 就會直接回傳這份回應,不會再呼叫 OpenAI。
實際的使用流程
- 用
pnpm mock:record啟動代理伺服器 - 用
OPENAI_BASE_URL=http://localhost:4010/v1 pnpm dev照常執行應用程式 - llmock 自動把測試固件存進
fixtures/llm/recorded/ - 之後執行
pnpm mock:start,就會重播這些測試固件
整個過程完全不用修改程式碼,唯一要改的只有 OPENAI_BASE_URL 的指向。
LLMock 的混沌注入
步驟 4 的 Chaos 與 Resilience 這一組裡,有幾個測試用到了 setChaos() 與 nextRequestError()。這些測試用的是 LLMock 的程式化混沌注入 API,能夠重現 LLM 的失敗情境。Chaos: Vector DB failures 與 Chaos: LLM failures 那幾個測試,是自行架設 HTTP 伺服器來偽造 500 錯誤或逾時;改用這個 API 的話就不必這麼做。向量資料庫的測試別無選擇,因為 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() 會移除混沌設定,讓 LLMock 恢復回傳正常的測試固件回應。這個方法很適合用來測試系統能否從失敗中恢復。
test("clearChaos() restores normal operation", async () => { const mock = new LLMock({ port: 0 }); mock.onMessage(/.*/, { content: validJson }); mock.setChaos({ malformedRate: 1.0 });
await mock.start(); // ... 環境設定 ...
const reasoner = new Reasoner("gpt-4o-mini");
// 開啟混沌:失敗 await expect( reasoner.buildSearchStrategy("laptop", []) ).rejects.toThrow();
// 關閉混沌:正常運作 mock.clearChaos();
const strategy = await reasoner.buildSearchStrategy("laptop", []); expect(strategy.refinedQuery).toBe("laptop"); // ✓ 有效的 JSON});nextRequestError():一次性的錯誤注入
nextRequestError() 只會讓下一個請求回傳錯誤,用過一次就失效,很適合「失敗一次、重試就成功」的情境。
test("nextRequestError(400) — single request fails, next succeeds", async () => { const mock = new LLMock({ port: 0 }); mock.onMessage(/.*/, { content: validJson });
// 一次性:只有下一個請求回傳 400 mock.nextRequestError(400, { message: "Bad Request" });
await mock.start(); // ... 環境設定 ...
const reasoner = new Reasoner("gpt-4o-mini");
// 第一次呼叫:400 await expect( reasoner.buildSearchStrategy("laptop", []) ).rejects.toThrow();
// 第二次呼叫:一次性錯誤已用掉 → 正常回應 const strategy = await reasoner.buildSearchStrategy("laptop", []); expect(strategy.refinedQuery).toBe("laptop"); // ✓});OpenAI SDK 會自動重試 5xx 錯誤(500、503 等),所以一次性的錯誤測試要用 SDK 不會重試的 4xx。
測試執行結果
$ 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 這個測試則兩種做法都沒有用到。用 API 的話程式碼比較少,意圖也比較清楚。
總結
我用 AIMock 模擬了 LLM、向量資料庫與 A2A 賣家 AI 代理,為 AI 代理建立了一套測試套件。這套測試能夠在三秒內執行完畢,而且每次的輸出都相同。
AIMock 值得用的場合:
- 測試同時結合 LLM、向量資料庫與其他數個服務的 AI 代理應用程式
- 在 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()測試錯誤時要用 4xx


