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)는 단일 패키지로, 모든 주요 LLM, 비전, 음성, 비디오, 임베딩, 벡터 DB, 에이전트 간 에ンド포인트를 모방하는 Zero-Dependency Node.js 서버입니다. 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	많은 에이전트가 의존하는 보조 서비스를 모킹합니다.

이 모든 구성 요소는 하나의 포트 (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로 다른 모크 도구에서 피처 가져오기, 컨테이너화된 CI용 Docker 명령어 제공.

누가 사용하고 있나요?

AG-UI 프로젝트는 여러 LLM 프로바이더를 사용하여 피처 기반 응답으로 에이전트 동작을 검증하는 엔드투엔드 테스트 스위트에서 aimock를 사용하고 있습니다.

라이선스

MIT – 상용 및 오픈소스 사용에 자유롭게 사용 가능합니다.

결론 – aimock는 현대 생성형 AI 서비스의 전체 스택을 커버하는 포괄적이고 Zero-Dependency 모크 서버입니다. LLM, 멀티모달 모델, 벡터 스토어, 에이전트 프로토콜과 통신하는 모든 애플리케이션의 저비용, 빠르고 결정론적인 테스트를 가능하게 합니다.