AgentInspect를 사용하면 개발자가 AI 에이전트의 단계별 동작을 JSONL 로그로 캡처할 수 있어, 스택에 OpenTelemetry를 연결하지 않고도 필요한 도구가 실행되었는지 확인할 수 있습니다.
Vercel AI SDK를 기반으로 구축된 날씨 확인 예제로 간단한 테스트를 진행한 결과, AgentInspect는 "조용한 실패(silent failure)"를 포착했습니다. 최종 답변은 정확했지만, 날씨 도구(weather-tool) 호출이 전혀 이루어지지 않았던 것입니다. 이 라이브러리의 프로세스 수준 체크는 단순한 출력 테스트로는 놓쳤을 문제를 잡아냈습니다.
실행 경로가 중요한 이유
AI 에이전트의 응답은 여러 번의 모델 호출과 외부 도구 호출을 포함하는 체인의 최종 결과물입니다. 프롬프트가 실시간 데이터를 가져와야 하는 경우, 텍스트가 올바르게 보이더라도 데이터 호출이 누락되면 리스크 프로필이 달라집니다. 답변 수준의 테스트만으로는 중요한 단계를 건너뛰는 버그가 인지되지 않은 채 운영 환경에 배포될 수 있습니다.
AgentInspect의 기능
- 경량 기록(Lightweight recording) – TypeScript 어댑터가 에이전트 코드에 연결되어 각 모델 호출, 도구 호출 및 그 순서를 줄 단위 JSON(JSONL) 파일에 기록합니다.
- 규칙 엔진(Rule engine) – 개발자는 "날씨 도구가 반드시 호출되어야 함" 또는 "금융 API를 사용해서는 안 됨"과 같은 간단한 서술어를 선언합니다. 라이브러리는 매 실행 후 이러한 규칙을 평가합니다.
- CLI 검사(CLI inspection) – 실패한 실행은 파일로 저장되며, 내장된 명령줄 도구를 통해 실행 트레이스를 사람이 읽기 쉬운 형태로 재생하여 확인할 수 있습니다.
로그가 로컬 파일로 저장되므로 트레이싱 백엔드, 네트워크 설정 또는 별도의 관측성(observability) 서비스가 필요하지 않습니다.
테스트 설정 방법
- 프로세스 체크(Process checks) – 규칙을 통해 날씨 도구 엔드포인트가 호출되었는지 확인했습니다.
- 답변 체크(Answer checks) – 별도의 어설션(assertion)을 통해 생성된 텍스트를 예상된 실내 관광 추천 내용과 비교했습니다.
두 가지 시나리오를 실행했습니다:
| 시나리오 | 답변 체크 | 프로세스 체크 |
|---|---|---|
| 정상 경로 (날씨 데이터 가져옴) | 통과 | 통과 |
| 날씨 건너뜀 (도구 미호출) | 통과 | 실패 |
두 번째 실행은 프로세스 체크의 가치를 잘 보여줍니다. 답변은 정상적으로 보였지만, 도구 호출이 누락된 것을 통해 숨겨진 결함을 찾아낼 수 있었습니다.
AgentInspect vs. Promptfoo
보다 정립된 테스트 프레임워크인 Promptfoo는 OpenTelemetry를 통해 트레이스를 캡처합니다. 이 방식은 이미 텔레메트리 데이터를 수집기(collector)로 전송하는 팀에게는 적합하지만, 설정 오버헤드가 발생하고 트레이싱 인프라에 대한 의존성이 생깁니다.
AgentInspect는 개발 초기 단계에 더 적합한 느낌을 주지만, 설정이 매우 간단합니다.
이런 분들께 추천합니다
- CI 파이프라인 – AgentInspect를 실행하고 규칙 위반 시 빌드를 실패하게 하는 단계를 추가하면, 조용한 버그를 확실한 중단 지점으로 바꿀 수 있습니다.
- 디버깅 – JSONL 로그를 로컬에서 열어 정확한 호출 순서를 재생해 볼 수 있어, 원격 트레이스 대시보드를 뒤지는 것보다 시간을 절약할 수 있습니다.
- 제품 팀 – 기능을 출시하기 전에 중요한 데이터 호출이 실제로 이루어졌는지 확인함으로써, 이후 발생할 수 있는 사용자 불만 리스크를 줄일 수 있습니다.
요약하자면: AI 에이전트의 정확성이 단순히 최종 텍스트뿐만 아니라 수행하는 동작에 달려 있을 때, AgentInspect와 같은 경량 기록 도구는 전체 트레이싱 스택의 오버헤드 없이도 숨겨진 프로세스 버그를 눈에 보이고 테스트 가능한 실패로 전환해 줍니다.