aimock: AI 앱 테스트에서 실제 API·도구·실패 상황을 어떻게 분리할까

LLM·MCP·벡터 검색을 연결한 AI 앱을 테스트하는 팀이라면 매번 실제 API를 호출해 결과·비용·네트워크에 영향을 받는 문제부터 줄여야 합니다. aimock은 모델 호출뿐 아니라 MCP, A2A, AG-UI, 벡터 저장소와 서비스 호출을 로컬 모의 응답으로 묶어, 같은 입력을 다시 시험하고 실패 상황을 의도적으로 만들 수 있게 하는 TypeScript 기반 오픈소스 도구입니다.

이 Pick의 핵심 질문은 “모델이 더 똑똑한가?”가 아닙니다. 실제 서비스에 연결하기 전, 애플리케이션의 호출 순서·도구 연결·오류 처리를 어떤 고정 조건에서 확인할지 정하는 방법입니다.

어떤 문제를 먼저 해결하나요?

AI 앱의 통합 테스트가 실제 공급자 API에만 의존하면 응답이 바뀌고, 네트워크가 흔들리며, 테스트마다 비용과 키 관리가 따라옵니다. 도구 호출이나 벡터 검색까지 연결한 에이전트는 모델 응답 하나만 고정해서는 전체 흐름을 재현하기 어렵습니다.

aimock은 로컬 서버와 fixture(테스트에 재사용할 고정 응답)를 두고 이 흐름을 분리하는 선택지입니다. 고정 fixture를 재생하는 테스트에서는 실제 공급자에 다시 연결하지 않으므로, 호출 순서와 애플리케이션의 분기 로직을 먼저 확인하기 좋습니다.

다만 모델 품질, 답변의 사실성, 최신 공급자 동작을 평가하는 도구는 아닙니다. 실제 공급자와 연결하는 별도의 통합·회귀 테스트는 남겨야 합니다.

어떤 호출을 한 테스트 범위로 묶을 수 있나요?

공식 문서가 안내하는 범위는 다음과 같습니다.

LLMock: OpenAI·Anthropic·Google·Mistral·xAI·Ollama 등 LLM API 표면
MCPMock: MCP 서버와 도구 호출
A2AMock: 에이전트 간 호출
AGUIMock: 에이전트와 UI 사이의 이벤트
VectorMock: 벡터 검색·저장소 호출
Services: 애플리케이션이 의존하는 일반 HTTP 서비스

모의 서버를 여러 개 띄우는 대신 하나의 포트와 설정으로 묶는 구조라서, “질문 → 모델 호출 → 도구 호출 → 검색 결과 → 화면 이벤트” 같은 흐름을 한 테스트 묶음으로 시작할 수 있습니다. 지원 표면이 넓다는 사실만으로 각 프로토콜의 모든 세부 동작을 보장한다고 해석해서는 안 됩니다.

기록·재생과 실패 주입은 어떻게 나누나요?

공식 시작 예시는 패키지를 설치한 뒤 LLMock을 애플리케이션의 테스트 코드에 연결하는 방식입니다.

npm install @copilotkit/aimock

처음에는 실제 키를 넣지 않은 단일 테스트로 로컬 서버가 의도한 주소를 바라보는지 확인하세요. 공급자에 연결해야 하는 기록 단계에서는 프록시가 실제 upstream 응답을 fixture로 저장하고, 이후 재생 단계에서는 저장한 응답을 돌려줍니다. 공식 문서는 기록된 fixture에 인증 헤더를 저장하지 않는다고 안내합니다.

실패 처리는 chaos 설정으로 따로 확인할 수 있습니다. 요청을 500 오류로 끝내는 drop, 잘못된 JSON을 돌려주는 malformed, 연결을 끊는 disconnect를 각각 시험하면, 정상 응답만 가정한 에이전트의 재시도·사용자 안내·사람 검토 경로를 확인할 수 있습니다. 요청별 설정, fixture 설정, 서버 설정 순으로 우선순위가 정해집니다.

기록과 재생을 같은 단계로 취급하지 않는 것이 중요합니다. 기록 모드는 upstream의 키·네트워크·응답 변화에 영향을 받고, 재생 모드는 fixture의 품질과 최신성에 영향을 받습니다.

선택 전에 확인할 한계는 무엇인가요?

모의 응답이 통과했다는 사실은 실제 모델의 정확도나 업무 결과를 증명하지 않습니다.
기록 단계에서는 실제 공급자 API를 호출할 수 있으므로, 비밀값·개인정보·비용 승인 범위를 먼저 정해야 합니다.
기본 설정은 요청을 허용하는 방향이므로, 공유 테스트 환경에서는 공식 문서의 API 키 검증 옵션을 켜는지 확인해야 합니다.
원격 fixture는 캐시·시간 초과·용량 제한과 사설 주소 차단 규칙이 있으므로, 사내망 주소를 쓸 때 별도 허용이 필요한지 점검해야 합니다.
프록시 모드의 일부 스트리밍 오류 주입은 적용 범위가 다를 수 있습니다. 특히 SSE 응답의 실패 경로를 실제 환경에서 다시 확인해야 합니다.
에이전트가 파일을 수정하거나 외부로 보내는 권한, 도구의 부작용, 사람 승인 절차는 aimock이 대신 설계하지 않습니다.

이 저장소에 aimock을 직접 설치해 성능·비용·정확도를 재현한 것은 아닙니다. 아래 내용은 공식 저장소와 문서가 설명하는 기능 범위에 대한 판단입니다.

처음에는 어떤 순서로 시험할까요?

비밀값과 실제 고객 데이터를 제거한 테스트 저장소에서 질문 하나와 도구 호출 하나를 고릅니다.
LLM 호출 주소를 로컬 aimock으로 바꾸고, 정상 응답 fixture 하나를 재생합니다.
같은 테스트를 CI에서 반복해 호출 순서·도구 인자·화면 이벤트가 고정되는지 확인합니다.
drop, malformed, disconnect를 각각 넣어 재시도·타임아웃·사람 검토 경로를 확인합니다.
모델이나 도구 버전을 올릴 때 실제 공급자와의 통합 테스트를 별도로 실행해 fixture와 차이를 검토합니다.

에이전트의 역할·참고 자료·도구·승인 단계를 함께 정리하려면 AI 에이전트 설정과 활용 과정에서 실습 범위를 확인할 수 있습니다. aimock은 그 설계를 자동으로 대신하는 도구가 아니라, 정한 흐름을 반복해서 검수하기 위한 테스트 경계로 보는 편이 적합합니다.