software

‘한 번 통과했어’는 충분하지 않아서 AI 에이전트를 위한 pytest‑like 도구를 만들었습니다

발행: (2026년 2월 6일 오전 05:10 GMT+9)
5 min read
원문: Dev.to

Source: Dev.to

소개

AI 에이전트가 개발 단계에서는 완벽하게 동작하다가 프로덕션에서는 갑자기 깨지는 경험, 다들 아시죠? 같은 프롬프트, 같은 모델인데 결과가 달라지는 경우. 저는 에이전트가 가끔 실패할 때 디버깅에 너무 많은 시간을 쏟았습니다. 가장 힘든 부분은 실패 자체가 아니라 왜 그런지 모른다는 점이었습니다. 도구 선택 때문인가요? 프롬프트 때문인가요? 모델이 컨디션이 안 좋은 건가요?

기존 평가 도구들은 별 도움이 되지 않았습니다. 테스트를 한 번 실행하고, 출력을 확인하고 끝났거든요. 하지만 에이전트는 결정론적이지 않으니 한 번만 실행해서는 거의 아무것도 알 수 없습니다.

agentrial

저는 agentrial이라는 pytest‑스타일 프레임워크를 만들었습니다. 이 프레임워크는 각 테스트를 여러 번 실행하고 실제 통계치를 제공합니다.

설치

pip install agentrial

설정 (agentrial.yml)

suite: my-agent
agent: my_module.agent
trials: 10
threshold: 0.85

cases:
  - name: basic-math
    input:
      query: "What is 15 * 37?"
    expected:
      output_contains: ["555"]
      tool_calls:
        - tool: calculate

테스트 실행

agentrial run

출력

┌──────────────────────┬────────┬──────────────┬──────────┐
│ Test Case            │ Pass   │ 95% CI       │ Avg Cost │
├──────────────────────┼────────┼──────────────┼──────────┤
│ easy-multiply        │ 100.0% │ 72.2%-100.0% │ $0.0005  │
│ medium-population    │ 90.0%  │ 59.6%-98.2%  │ $0.0006  │
│ hard-multi-step      │ 70.0%  │ 39.7%-89.2%  │ $0.0011  │
└──────────────────────┴────────┴──────────────┴──────────┘

신뢰 구간

“95% CI” 열은 Wilson 점수 구간을 보여줍니다. 10번의 시도에서 100 % 통과율은 실제로 95 % 신뢰도로 72 %와 100 % 사이에 있다는 뜻입니다. “100 % (72‑100 %)”라는 표시가 “그냥 100 %”보다 에이전트 신뢰성을 평가하는 방식을 완전히 바꾸어 놓았습니다.

단계별 실패 원인 파악

테스트가 실패하면 agentrial은 어느 단계에서 차이가 났는지 알려줍니다:

Failures: medium-population (90% pass rate)
  Step 0 (tool_selection): called 'calculate' instead of 'lookup_country_info'

제 경우엔 모호한 질의에 대해 에이전트가 가끔 잘못된 도구를 선택하는 버그가 있었는데, 이를 수동으로 찾으려면 몇 시간이 걸렸을 것입니다.

실제 비용 추적

agentrial은 API 응답 메타데이터에서 토큰 사용량을 가져옵니다. 10개의 테스트 케이스에 대해 100번의 시도를 진행했을 때 총 비용은 6 센트에 불과했으며, 확장하기 전에 테스트당 정확한 비용 추정치를 제공했습니다.

CI 연동

GitHub Action을 사용해 모든 PR에 신뢰성 임계값을 적용할 수 있습니다:

- uses: alepot55/agentrial@v0.1.4
  with:
    trials: 10
    threshold: 0.80

통과율이 80 % 이하로 떨어지면 PR이 차단됩니다. 이 덕분에 지난 주에 두 번의 회귀가 배포되는 것을 막을 수 있었습니다.

현재 제한 사항

  • 현재는 LangGraph만 지원합니다. CrewAI와 AutoGen용 어댑터는 추후 계획에 있습니다.
  • CLI 전용이며, 아직 그래픽 UI는 없습니다.
  • 의미론적 평가를 위한 LLM‑as‑judge 기능이 없습니다(추후 제공 예정).

오픈 소스

agentrial은 MIT 라이선스로 제공되며 , 에서 확인할 수 있습니다.

마무리 생각

전체를 약 일주일 만에 Claude Code를 이용해 만들었습니다. 통계적 요소(윌슨 구간, 회귀 탐지를 위한 피셔 정확 검정, Benjamini‑Hochberg 보정)는 가장 재미있는 부분이었죠. 에이전트를 만들면서 “내 환경에서는 잘 돌아가”는 상황에 지치셨다면 agentrial을 한 번 써보세요. 아직 어떤 메트릭이 가장 유용한지 고민 중이니, 아이디어가 있으면 언제든 공유해 주세요!

Back to Blog

관련 글

더 보기 »