CopilotKit/aimock

Mock everything your AI app talks to — LLM APIs, MCP, A2A, AG-UI, vector DBs, search. One package, one port, zero dependencies.

aimock – AIアプリケーションテスト用の決定論的モックサーバー

何であるか – aimock（旧称 llmock）は、単一パッケージでゼロ依存のNode.jsサーバーであり、アプリが呼び出す可能性のあるすべての主要なLLM、ビジュアル、音声、動画、埋め込み、ベクトルDB、エージェント間エンドポイントを擬似的に実装します。SDKを提供されるローカルポートに接続することで、完全に決定論的な応答を得られ、実際のAPIキーもネットワークトラフィックも不要です。これにより、予期せぬ請求を回避し、エンドツーエンドテストの信頼性が向上します。

なぜ重要か – 実際のAIサービスは高価で、リクエスト制限があり、時間とともに変更されることがあります。aimockは、一度だけ実際の相互作用を記録し、それを永続的に再生できるようにします。また、混沌テスト、ドリフト検出、細かいフィクスチャルーティングもサポートしており、CIパイプラインを高速化・低コスト化・再現可能にします。

コアコンポーネント（「aimockスイート」）

コンポーネント	モック対象	一般的な使用例
LLMock	OpenAI（チャット、リアルタイム、画像、音声、動画）、Claude、Gemini、Bedrock、Azure、Vertex AI、Ollama、Cohere、OpenRouter、ElevenLabs TTS、BytePlus Ark、Grokなど	単体／統合テストで任意のLLMまたはマルチモーダルプロバイダーを置き換えます。
MCPMock	Copilot-Kit MCPツール、リソース、プロンプト、セッション処理	ライブサーバーなしでプロンプト管理バックエンドをテストします。
A2AMock	エージェント間SSEストリーミングプロトコル	マルチエージェント連携ロジックを検証します。
AGUIMock	AG-UIイベントストリーム（エージェント→UI）	UI駆動型エージェントのフロントエンドテスト。
VectorMock	Pinecone、Qdrant、ChromaDB互換のベクトルストアAPI	検索拡張生成パイプラインをテストします。
Services	Tavily検索、Cohere再ランク、OpenAIモデレーション、ElevenLabs TTS	複数のエージェントが依存する補助サービスをモックします。

これらのすべては1つのポート（npx @copilotkit/aimock --config aimock.json）で実行可能、またはテストハーネスに密接に統合するためにプログラム的に起動できます。

主な機能

記録＆再生 – 実際のAPIをプロキシし、正確なJSONペイロード（フレーム単位のタイムスタンプ含む）を保存し、永続的に再生可能。再生速度は --replay-speed で調整可能。
タイミング対応再生 – 最初のトークン遅延（ttft）と全体のトークン/秒のペースを保持。UIのロード状態テストに有用。
正確なトークン使用量とコスト – 記録された使用フレームを再生することで、請求関連コードが現実的な prompt_tokens、completion_tokens、プロバイダー固有のコスト分解を認識します。
マルチターン会話対応 – フィクスチャは特定のターン、ツール呼び出し、システムメッセージ、カスタム述語にスコープ可能。現実的なツール使用シナリオを実現。
混沌テスト – ランダムな500エラー、不正なJSON、中間切断、設定可能なレートリミットヘッダーで、リトライ/バックオフロジックを検証可能。
厳密 vs. 余裕あるマッチング – グローバル --strict フラグまたはリクエストごとの X-AIMock-Strict ヘッダーで、一致しないリクエストがエラーになるか否かを制御。
コンテキストベースのフィクスチャルーティング – X-AIMock-Context ヘッダーで各統合ごとにフィクスチャセットを分離し、テスト間の汚染を回避。
ドリフト検出 – CIジョブは記録されたフィクスチャをライブAPIと自動比較し、プロバイダーの変更を検出可能。
ストリーミング物理 – ttft、トークン/秒、ジッターを調整し、現実的なストリーミング動作をシミュレート。
メトリクス – Prometheus互換エンドポイント（/metrics）でリクエスト数、遅延、フィクスチャヒット率を報告。
Docker & Helm – CI/CDパイプラインでの容易なデプロイのための公式コンテナイメージとHelmチャート。
テストフレームワークプラグイン – VitestとJestヘルパー（useAimock()）はサーバーの自動起動/停止と環境変数のパッチを実行。

一般的なワークフロー

インストール – npm i @copilotkit/aimock。
記録（オプション） – 実際のプロバイダーと通信しているアプリを実行しながら、npx @copilotkit/aimock llmock --record --provider-openai https://api.openai.com を実行。フィクスチャはJSONとして保存されます。
再生 – これらのフィクスチャでモックサーバーを起動：npx @copilotkit/aimock --config aimock.json（またはプログラム的に new LLMock({port:0}) で）。
SDKの設定 – OPENAI_BASE_URL（他のプロバイダーも同様）を http://localhost:<port>/v1 に設定し、ダミーAPIキーを指定。
テスト実行 – テストスイートはモックサーバーにアクセスし、決定論的な応答を受け取り、ヘッダーまたはCLIフラグでエラー/遅延シナリオも実行可能。

インストールとクイックスタート（READMEからのコードスニペット）

npm install @copilotkit/aimock

import { LLMock } from "@copilotkit/aimock";

const mock = new LLMock({ port: 0 });
mock.onMessage("hello", { content: "Hi there!" });
await mock.start();

process.env.OPENAI_BASE_URL = `${mock.url}/v1`;
process.env.OPENAI_API_KEY = "mock"; // 多くのSDKで必須

// … アプリケーション／テストを実行 …
await mock.stop();

統合ポイント

LangChain、CrewAI、LlamaIndex、Mastra、Google ADK、Microsoft Agent Framework – 専用ガイドで aimock にプロバイダーURLを切り替える方法を紹介。
GitHub Action – CopilotKit/aimock@v1 はフィクスチャを事前読み込みし、次のステップにモックURLを公開可能。
CLIユーティリティ – llmock（互換エイリアス）でフラグ駆動実行、aimock convert で他のモックツールからのフィクスチャインポート、Dockerコマンドでコンテナ化CI用。

誰が使っているか？

AG-UIプロジェクトは、複数のLLMプロバイダーを用いてフィクスチャ駆動応答でエージェント動作を検証するエンドツーエンドテストスイートで aimock を引用しています。

ライセンス

MIT – 商用およびオープンソース利用に自由。

結論 – aimock は、現代の生成AIサービスの全スタックをカバーする包括的でゼロ依存のモックサーバーです。LLM、マルチモーダルモデル、ベクトルストア、エージェントプロトコルと通信するあらゆるアプリケーションの、低コスト・高速・決定論的なテストを可能にします。