당신의 AI 에이전트는 개발 환경에서는 잘 작동합니다. 톤(tone)을 개선하기 위해 프롬프트(prompt)를 변경합니다. 그런데 이제 결제 관련 질문을 제대로 라우팅(routing)하지 못합니다.

사용자가 불만을 제기할 때까지 이 사실을 알지 못합니다.

문제는 AI 에이전트는 비결정론적(non-deterministic)이라는 점입니다. 전통적인 단위 테스트(unit tests)는 작동하지 않습니다. expect(output).toBe("transfer to billing")는 올바른 동작임에도 30%의 확률로 실패하며, 에이전트가 미묘한 방식으로 고장 났을 때는 통과해 버립니다.

저는 이를 해결하기 위해 비결정론적인 AI 출력에 특화되어 설계된 테스트 프레임워크인 AgentSpec을 만들었습니다.

사용 모습

YAML에서 테스트를 정의합니다:

name: "billing-agent-tests"
tests:
  - name: "routes billing question"
...

테스트 실행:

npm install -g @ozperium/agentspec
agentspec init
agentspec run

출력 결과:

AgentSpec v1.2.0

  ✓ routes billing question (312ms)
...

왜 AI를 위한 어설션(assertions)이 필요한가

표준 테스트 어설션(test assertions)은 결정론적인(deterministic) 출력을 가정합니다. AI 출력은 그렇지 않습니다.

AgentSpec은 다음을 제공합니다:

• contains / not_contains — 부분 문자열 존재 여부 (의역(paraphrasing) 처리 가능)
• contains_any / contains_all — 유연한 다중 키워드 매칭
• semantically_similar — 정확한 일치가 아닌 단어 중첩 유사도 점수
• regex — 구조화된 출력을 위한 패턴 매칭 (정규 표현식)
• tool_called — 에이전트가 올바른 도구(tool)를 호출했는지 확인
• max_latency_ms — 응답 시간의 회귀(regressions) 감지
• llm_judge — 로컬 모델(Ollama)을 사용하여 자연어로 품질 평가

CI 통합

agentspec run --ci   # 실패 시 1로 종료, JUnit XML 출력

GitHub Actions에 추가하세요:

- name: Run AgentSpec
  run: agentspec run --ci

이제 프롬프트, 모델, 또는 도구를 변경하는 모든 PR(Pull Request)에 대해 동작 회귀 테스트(behavior regression tests)가 수행됩니다.

동작 차이 보고서 (Behavior diff reports)

--diff 옵션을 사용하여 이전 베이스라인(baseline)과 비교하여 실행하세요:

agentspec run --diff baseline.json

실행 간에 정확히 무엇이 변경되었는지 보여줍니다. 이는 모델을 교체하거나 프롬프트를 업데이트할 때 매우 유용합니다.

HTTP 에이전트

실행 중인 에이전트 엔드포인트(endpoint)를 지정하세요:

agentspec run --endpoint http://localhost:3000/chat

SDK 통합이 필요하지 않습니다.

설치 (Install)

npm install -g @ozperium/agentspec
agentspec init
agentspec run

GitHub: https://github.com/Ozperium/agentspec

스택 내 다른 도구: AI API 지출을 추적하기 위한 AICostTracker, 그리고 제한(rate limits)에 걸리기 전에 이를 모니터링하기 위한 quota.