DEV Community

Cover image for 에이전트 거짓말, Apidog AI 에이전트 디버거로 해결!
Rihpig
Rihpig

Posted on • Originally published at apidog.com

에이전트 거짓말, Apidog AI 에이전트 디버거로 해결!

#ai #agents #mcp #api

어느 화요일 오후, 디버그 세션이 시작된 지 12분 만에 에이전트는 /users 엔드포인트가 47초 만에 응답한다고 자신 있게 말했습니다. 실제 수치는 47밀리초였습니다.

지금 Apidog 사용해보기

저는 이 버그를 이틀 동안 쫓고 있었습니다. MCP 서버에 print 문을 추가할 때마다 에이전트의 답변은 조금씩 달라졌고, 시스템 프롬프트를 수정할 때마다 응답은 더 그럴듯해졌습니다. 하지만 정답은 아니었습니다.

문제는 로그가 아니라 모델과 도구 사이에 실제로 무엇이 오갔는지를 보지 않았다는 점이었습니다. Apidog의 AI Agent Debugger에서 실행 추적을 열자, 버그를 찾는 데 12분이 걸렸습니다.

내가 쫓던 버그

구성은 단순했습니다.

  • GPT-5.5 기반 에이전트
  • 주말에 작성한 MCP 서버
  • MCP 서버가 노출한 도구: get_response_time(endpoint)
  • 짧은 시스템 프롬프트
  • 사용자 프롬프트: "/users 엔드포인트는 얼마나 빠른가요?"

에이전트는 빠르게 답했지만 매번 다르게 틀렸습니다.

예를 들면:

엔드포인트가 47초 만에 응답하고 있습니다.
Enter fullscreen mode Exit fullscreen mode

또는:

약 0.05초 정도입니다.
Enter fullscreen mode Exit fullscreen mode

한 번은 이렇게만 답했습니다.

성능은 허용 가능한 수준입니다.
Enter fullscreen mode Exit fullscreen mode

처음에는 늘 하던 방식으로 접근했습니다.

  1. MCP 서버에 로깅 추가
  2. 모델 응답을 토큰 단위로 확인
  3. 시스템 프롬프트 비교
  4. 도구 정의 수정
  5. 다시 실행

하지만 에이전트 디버깅에서 버그는 한 곳에만 있지 않습니다. 보통 아래 중 하나입니다.

  • 시스템 프롬프트
  • 모델 선택
  • 도구 정의
  • 모델이 도구에 전달한 매개변수
  • 도구가 반환한 데이터
  • 모델이 데이터를 해석하는 방식

콘솔 로그는 이 중 일부만 보여줍니다. 필요한 것은 전체 실행 흐름입니다.

Traces 패널에서 확인해야 할 것

Apidog 디버거는 세 개의 패널로 구성됩니다.

  • 왼쪽: 세션 목록
  • 가운데: 대화 턴
  • 오른쪽: 실행 추적

세션을 클릭하면 가운데 패널에서 사용자 메시지, 모델 응답, 도구 호출, 도구 반환, 후속 모델 응답을 볼 수 있습니다. 특정 턴을 클릭하면 오른쪽 패널에 전체 실행 트리가 펼쳐집니다.

실행 트리에서 확인할 수 있는 항목은 다음과 같습니다.

  • 모델이 받은 시스템 프롬프트
  • 모델이 받은 사용자 프롬프트
  • 모델이 생성한 도구 호출 이름과 JSON 매개변수
  • 도구가 반환한 JSON 결과
  • 모델 응답
  • 턴별 타이밍
  • 토큰 사용량

제가 실패한 세션을 열었을 때 도구 호출은 정상처럼 보였습니다.

get_response_time(endpoint="/users")
Enter fullscreen mode Exit fullscreen mode

모델은 올바른 도구를 선택했고, 인수도 맞았습니다.

문제는 도구 결과에 있었습니다.

{
  "value": 47,
  "p95": 89,
  "samples": 1240
}
Enter fullscreen mode Exit fullscreen mode

메트릭 파이프라인은 값을 밀리초(ms) 단위로 반환하고 있었습니다. 하지만 모델은 이를 초(s) 단위로 해석했습니다.

즉, 47은 47ms였지만 모델은 단위가 없다는 이유로 47초라고 답한 것입니다.

도구 호출은 맞았습니다. 도구 결과도 데이터 자체는 맞았습니다. 문제는 응답 스키마와 프롬프트가 단위를 명시하지 않았다는 점이었습니다.

수정은 여섯 줄로 끝났습니다

MCP 서버의 응답 형식을 아래처럼 바꿨습니다.

{
  "value": { "amount": 47, "unit": "ms" },
  "p95": { "amount": 89, "unit": "ms" },
  "samples": 1240
}
Enter fullscreen mode Exit fullscreen mode

그리고 시스템 프롬프트에 한 문장을 추가했습니다.

도구 결과는 단위를 명시적으로 반환합니다. 주의 깊게 읽으세요.
Enter fullscreen mode Exit fullscreen mode

같은 /users 프롬프트를 세 번 더 실행했습니다. 세 번 모두 모델은 다음과 같이 답했습니다.

엔드포인트가 약 47ms로 응답하고 있습니다.
Enter fullscreen mode Exit fullscreen mode

이전 실패 실행보다 토큰 비용도 18% 낮았습니다. 모델이 잘못된 가정을 설명하거나 복구하려는 장황한 텍스트를 생성하지 않았기 때문으로 보입니다.

그다음 같은 프롬프트를 Claude Opus 4.7에서도 실행했습니다. 결과는 같았지만 비용은 두 배였고 응답은 더 장황했습니다. 프로덕션에 어떤 모델을 사용할지 판단하기 쉬워졌습니다.

이 지점에서 중요한 기능은 단순히 “버그를 찾는 것”이 아니었습니다. 왼쪽 세션 패널에서 다음 메트릭을 기준으로 모델 실행을 비교할 수 있다는 점이었습니다.

  • 턴 수
  • 단계 수
  • 실행 시간
  • 토큰 사용량
  • 비용

이전에는 이런 비교를 스프레드시트로 관리했습니다. 이제는 같은 구성으로 여러 모델을 실행하고 세션 목록에서 바로 비교할 수 있었습니다.

내가 잘못 알고 있던 것

AI Agent Debugger를 단순한 로깅 도구로 생각하기 쉽습니다. 하지만 로깅과 디버깅은 다릅니다.

로그는 “무슨 일이 일어났는지”를 보여줍니다.

디버거는 “모델과 도구가 실제로 무엇을 주고받았는지”를 보여줍니다.

에이전트를 디버깅할 때 모델 출력만 읽고 실패 원인을 추측한다면, 실제로는 에이전트를 디버깅하는 것이 아닙니다. 에이전트에 대한 가설을 디버깅하는 것입니다.

에이전트는 보통 다음 네 가지로 구성된 닫힌 시스템입니다.

  1. 모델
  2. 프롬프트
  3. 도구
  4. 도구 응답

버그는 대부분 이 네 가지 사이의 경계에서 발생합니다. 이 네 가지를 동시에 볼 수 있으면 12분 만에 찾을 수 있습니다. 볼 수 없으면 며칠을 소비할 수 있습니다.

반복 실행으로 비결정성 확인하기

수정 후 같은 프롬프트를 다섯 번 실행했습니다.

결과는 다음과 같았습니다.

  • 세 번은 get_response_time을 한 번만 호출
  • 두 번은 같은 도구를 두 번 호출
  • 두 번째 호출에서는 엔드포인트 경로의 대소문자가 달라짐

제 도구 스키마는 대소문자를 구분하고 있었습니다. 실패한 테스트 케이스가 모두 소문자였기 때문에 놓치고 있던 문제였습니다.

에이전트 테스트에서는 한 번의 성공만으로 충분하지 않습니다. 같은 입력을 여러 번 실행하고 차이를 봐야 합니다.

실행마다 달라지는 부분은 에이전트의 취약점입니다.

직접 해보기: 설정 가이드

아래는 같은 방식으로 Apidog AI Agent Debugger를 설정하고 실행하는 절차입니다.

단계 1: 새 에이전트 디버그 세션 생성

Apidog를 열고 상단 탭에서 AI Agent Debugger를 클릭합니다. 상단 영역에서 모델과 실행 환경을 설정합니다.

  1. 왼쪽에서 모델 제공업체를 선택합니다. 예: OpenAI, Anthropic
  2. 가운데에서 모델을 선택합니다. 예: gpt-5.5
  3. 제공업체를 선택하면 기본 URL은 자동으로 채워집니다.
  4. Run을 클릭해 세션을 시작합니다.

AI 에이전트 디버거 탭. 상단에는 모델 제공업체 및 모델 선택기가 있고, 기본 URL은 자동으로 채워지며, 오른쪽 상단에는 실행 버튼이 있습니다.

단계 2: 프롬프트 구성

Prompts 탭에는 두 개의 입력 영역이 있습니다.

  • System Prompt: 에이전트의 역할, 목표, 제약 조건, 도구 사용 규칙을 정의합니다.
  • User Prompt: 이번 세션에서 테스트할 입력입니다. 예: Apidog는 무엇인가요?

실행하려면 오른쪽 상단의 Run을 클릭합니다.

실행 후 입력 상자를 자동으로 비우고 싶다면 Clear after Send를 선택합니다.

프롬프트를 작성할 때는 도구 결과를 어떻게 해석해야 하는지 명확히 적는 것이 좋습니다.

예:

도구 결과의 단위와 필드명을 반드시 확인한 뒤 답변하세요.
도구 결과에 단위가 포함되어 있으면 변환하지 말고 그대로 설명하세요.
Enter fullscreen mode Exit fullscreen mode

단계 3: 도구 구성

Tools 탭에는 에이전트가 런타임에 호출할 수 있는 도구가 표시됩니다. 탭의 숫자는 현재 사용 가능하거나 구성된 도구 수를 의미합니다.

내장 도구

필요한 도구만 켜고 나머지는 끄는 것이 좋습니다.

도구 기능
bash 지속적인 셸 세션에서 명령 실행
web_fetch 웹 콘텐츠를 가져와 Markdown, 텍스트 또는 HTML로 변환
read 텍스트, 이미지 또는 PDF 파일 읽기
edit 파일에 정밀한 문자열 바꾸기 적용
write 파일 생성 또는 덮어쓰기
grep 정규 표현식으로 파일 내용 검색
glob glob 패턴을 사용하여 파일 찾기
kill_shell 현재 셸 세션 재설정

MCP 도구

MCP 도구는 MCP 서버를 통해 외부 시스템 또는 사용자 지정 기능을 에이전트에 연결합니다.

지원되는 연결 방식은 다음과 같습니다.

  • STDIO: 로컬 MCP 서버 프로세스 시작
  • HTTP: 스트리밍 가능한 HTTP를 지원하는 MCP 서버에 연결
  • SSE: Server-Sent Events 기반 MCP 서버에 연결

인증이 필요한 MCP 서버는 요청 헤더 또는 OAuth 2.0 흐름을 사용할 수 있습니다. 연결에 성공하면 해당 서버가 에이전트에 노출하는 도구를 선택합니다.

AI Agent Debugger Tools 탭

도구 응답 스키마를 설계할 때는 가능한 한 모호한 값을 피하세요.

좋지 않은 예:

{
  "value": 47
}
Enter fullscreen mode Exit fullscreen mode

더 나은 예:

{
  "value": {
    "amount": 47,
    "unit": "ms"
  }
}
Enter fullscreen mode Exit fullscreen mode

단계 4: 스킬, 인증 및 모델 매개변수 구성

나머지 설정은 세 개의 탭에서 구성합니다.

Skills

Skills는 에이전트의 재사용 가능한 워크플로입니다.

다음과 같은 경우 유용합니다.

  • 프로젝트별 고정 워크플로
  • 반복되는 작업 지시
  • 시스템 프롬프트에 매번 넣기에는 긴 작업 규칙
  • 런타임에 필요할 때만 로드할 지식 또는 절차

AI Agent Debugger Skills 탭

Authentication

Authentication 탭에서는 모델 서비스 또는 MCP 서비스에 필요한 자격 증명을 설정합니다.

Settings

Settings 탭에서는 모델 런타임 매개변수를 설정합니다.

예:

  • Temperature
  • Max Tokens
  • Top P

지원되는 매개변수는 제공업체마다 다릅니다. 사용하는 모델이 실제로 어떤 값을 지원하는지 확인해야 합니다.

AI Agent Debugger Settings 탭

단계 5: 세 패널 읽기

실행을 클릭하면 새 세션이 왼쪽 패널에 나타납니다.

예:

Session 3
1 turn · 1 step · 10s · 3.1k tokens · $0.02
gpt-5.5
Enter fullscreen mode Exit fullscreen mode

각 패널에서 확인할 내용은 다음과 같습니다.

세션 패널

왼쪽 패널입니다. 모든 실행 기록과 요약 메트릭을 보여줍니다.

확인할 항목:

  • 턴 수
  • 단계 수
  • 실행 시간
  • 토큰 수
  • 비용
  • 사용 모델

턴 패널

가운데 패널입니다. 사용자와 모델 간 대화의 각 라운드를 보여줍니다.

특정 턴을 클릭하면 오른쪽 추적 패널에서 상세 실행 정보를 확인할 수 있습니다.

추적 패널

오른쪽 패널입니다. 에이전트의 전체 실행 체인을 보여줍니다.

확인할 수 있는 항목:

  • 시스템 프롬프트
  • 사용자 프롬프트
  • 모델 호출
  • 모델이 노출하는 경우 사고 과정
  • MCP 도구 호출
  • 사용자 지정 스킬 실행
  • 도구 입력 매개변수
  • 도구 결과
  • 소요 시간
  • 오류 메시지
  • 최종 출력

도구 호출이 실패하거나 모델이 예외를 반환하면 실패한 단계가 입력 및 출력과 함께 바로 표시됩니다. 로그 파일을 뒤질 필요가 없습니다.

AI Agent Debugger Traces 패널

단계 6: 모델 성능 비교

같은 프롬프트와 같은 도구 구성으로 여러 모델을 실행하면 각 실행이 별도 세션으로 생성됩니다.

비교할 때는 다음 항목을 봅니다.

  • 동일 작업을 완료하는 데 필요한 단계 수
  • 어떤 모델이 올바른 도구를 더 안정적으로 선택하는지
  • 응답 시간이 더 낮은 모델은 무엇인지
  • 토큰 사용량과 비용이 더 예측 가능한 모델은 무엇인지
  • 같은 입력을 여러 번 실행했을 때 결과가 얼마나 일관적인지

실무에서는 아래처럼 테스트하는 것이 좋습니다.

  1. 동일 프롬프트로 같은 모델을 5회 실행
  2. 세션별 도구 호출 차이 확인
  3. 도구 매개변수 차이 확인
  4. 응답 품질과 비용 비교
  5. 다른 모델로 동일 테스트 반복

핵심 요점

이 버그의 원인은 복잡하지 않았습니다. 도구는 숫자를 반환했고, 모델은 단위를 추측했습니다.

문제는 제가 그 경계를 제대로 보지 못했다는 점입니다.

에이전트를 디버깅할 때는 모델 출력만 보면 부족합니다. 반드시 다음을 함께 봐야 합니다.

  • 모델이 받은 프롬프트
  • 모델이 선택한 도구
  • 모델이 전달한 매개변수
  • 도구가 반환한 JSON
  • 모델이 결과를 해석한 방식

Apidog AI Agent Debugger는 이 흐름을 하나의 추적 화면에서 보여줍니다.

하나 이상의 에이전트를 만들고 있다면, 다음에 출시할 에이전트에도 모델과 도구 사이의 경계에서 발생하는 버그가 있을 가능성이 높습니다. 그 버그를 로그와 추측으로 찾을 수도 있지만, 실행 추적을 열면 훨씬 빠르게 찾을 수 있습니다.

Apidog를 다운로드하고 다음 에이전트 디버깅에 사용해보세요. 47초가 아니라 47밀리초였다는 것을 확인하는 데 필요한 것은 전체 실행 추적이었습니다.

MCP 전송 설정 및 요금제 가용성을 포함한 전체 기능 참조는 Apidog AI Agent Debugger: 가용성, 범위 및 설정에서 확인할 수 있습니다.

Top comments (0)