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

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

저는 이 버그를 이틀 동안 쫓고 있었습니다. MCP 서버에 print 문을 추가할 때마다 에이전트의 답변이 제가 뭔가 알아내고 있다고 생각할 만큼 충분히 달라졌습니다. 시스템 프롬프트를 다시 작성할 때마다 응답은 더 그럴듯하게 들렸습니다. 하지만 그 어떤 것도 옳지 않았습니다.

그날 오후가 되어서야 제가 하지 않았던 것은 실제 실행 추적을 열어 모델과 도구 사이에 어떤 것이 전달되고 있는지 확인하는 것이었습니다. 그것이 바로 Apidog의 AI Agent Debugger가 하는 일입니다. 저는 3주 전에 그것을 설치하고 잊어버리고 있었습니다. 버그를 찾는 데 12분이 걸렸습니다.

이것이 저를 놀라게 한 점입니다.

내가 쫓던 버그

설정은 간단했습니다. GPT-5.5 기반으로 구축된 에이전트. 제가 주말에 작성한 MCP 서버 하나는 우리 메트릭 파이프라인을 쿼리하는 get_response_time(endpoint) 도구를 노출했습니다. 약 40단어 정도의 시스템 프롬프트. 사용자 프롬프트: "/users 엔드포인트는 얼마나 빠른가요?"

에이전트는 빠르게 답변했습니다. 자신 있게 답변했습니다. 매번 다른 방식으로, 틀린 답변을 했습니다. 때로는 "엔드포인트가 47초 만에 응답하고 있습니다." 때로는 "약 0.05초 정도입니다." 한 번은 기억에 남게도 "성능은 허용 가능한 수준입니다."라고 했습니다.

저는 늘 하던 일들을 하고 있었습니다. MCP 서버에 로깅을 추가하고, 모델의 응답을 토큰 단위로 읽고, 시스템 프롬프트를 비교하고, 욕을 했습니다. 화요일 아침까지 터미널 창 세 개가 열려 있었고, 실패한 가설들로 가득 찬 노션 페이지가 있었습니다.

에이전트 디버깅의 특징은 버그가 처음 찾아보는 곳에 거의 없다는 것입니다. 시스템 프롬프트, 모델 선택, 도구 정의, 모델이 도구에 전달한 매개변수, 도구가 반환한 데이터, 또는 모델이 그 데이터를 해석하는 방식에 있을 수 있습니다. 여섯 군데. 콘솔 로그는 그중 하나만 보여줍니다.

Traces 패널이 실제로 보여주는 것

Apidog 디버거는 세 개의 열로 열립니다. 왼쪽에 세션. 가운데에 턴. 오른쪽에 추적. 세션을 클릭하면 가운데 열에 대화가 표시됩니다: 사용자 메시지, 모델 응답, 도구 호출, 도구 반환, 다음 모델 응답. 턴을 클릭하면 오른쪽 열에 그 아래의 전체 실행 트리가 확장됩니다.

실행 트리는 제가 놓치고 있던 부분이었습니다. 모든 단계가 순서대로 표시됩니다:

• 모델이 받은 시스템 프롬프트
• 모델이 받은 사용자 프롬프트
• 모델이 내보낸 JSON 형식의 도구 호출 이름과 매개변수
• 도구가 반환한 JSON 형식의 도구 결과 페이로드
• 턴에 대한 타이밍과 토큰이 포함된 모델 응답

저는 실패한 세션을 열었습니다. 도구 호출은 괜찮아 보였습니다: get_response_time(endpoint="/users"). 모델은 올바른 인수로 올바른 도구를 선택했습니다.

그런 다음 도구 결과를 확장했습니다.

{"value": 47, "p95": 89, "samples": 1240}

바로 거기에 있었습니다. 메트릭 파이프라인은 값을 밀리초 단위로 반환했습니다. 모델은 초 단위로 가정했습니다. 47은 단위에 대해 의문을 제기하지 않고 자신감 있는 환각을 통해 "47초"가 되었습니다. 도구는 옳았고, 모델이 틀렸습니다. 제 시스템 프롬프트에는 단위에 대한 지시가 없었고, 도구 응답에도 단위 주석이 없었습니다.

디버거를 연 지 12분 만에. 시스템 프롬프트 탓을 하던 이틀간의 삽질이 끝났습니다.

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

저는 두 가지를 변경했습니다. MCP 서버에서 응답 형식을 업데이트했습니다:

{
  "value": { "amount": 47, "unit": "ms" },
  "p95": { "amount": 89, "unit": "ms" },
  "samples": 1240
}

그런 다음 시스템 프롬프트에 한 문장을 추가했습니다: "도구 결과는 단위를 명시적으로 반환합니다. 주의 깊게 읽으세요."

같은 /users 프롬프트를 세 번 더 실행했습니다. 왼쪽 패널에 세 개의 다른 세션이 나타났습니다. 세 번 모두 "엔드포인트가 약 47ms로 응답하고 있습니다"라는 정확한 답변과 함께 모델의 추론에서 밀리초-백분위수 분석을 제공했습니다. 토큰 비용은 이전 실패한 실행보다 18% 낮았습니다. 아마 모델이 자신의 잘못된 가정을 복구하기 위한 산문을 생성하지 않았기 때문일 것입니다.

두 번째 세션에서 Claude Opus 4.7으로 같은 프롬프트를 나란히 실행했습니다. 결과는 같았지만, 비용은 두 배였고, 응답은 약간 더 장황했습니다. 어떤 모델이 프로덕션에 투입될지 알 수 있었습니다.

이것이 제가 이 도구에 존경심을 갖게 된 부분입니다. 어떤 괜찮은 디버거도 할 수 있는 버그 찾기 기능이 아니라, 왼쪽 패널에 요약 메트릭(턴 수, 단계 수, 시간, 토큰, 비용)과 함께 동일한 구성에서 실행되는 모델 비교 기능이었습니다. 저는 6개월 동안 구글 시트에서 이 비교를 해왔습니다. 이제는 세 번의 클릭으로 해결되었습니다.

내가 무엇을 잘못 알고 있었는가

쉽게 생각하면 AI Agent Debugger는 로깅 도구입니다. 하지만 그렇지 않습니다. 로깅 도구는 무엇이 일어났는지 보여줍니다. 디버거는 모델과 도구가 실제로 무엇을 주고받았는지 보여주는데, 이것은 다른 계층입니다.

만약 여러분이 에이전트를 작성하고 제가 하던 방식대로, 즉 모델 출력을 읽고 실패의 원인을 추측하고 있었다면, 제가 반박하고 싶은 점은 다음과 같습니다. 여러분은 에이전트를 디버깅하는 것이 아닙니다. 에이전트에 대한 여러분의 가설을 디버깅하는 것입니다. 이것들은 다른 것이고, 그중 하나만이 여러분을 해결책으로 이끌 것입니다.

제가 6개월 동안 받아들이지 못했던 것은 에이전트가 모델, 프롬프트, 도구, 도구 응답 사이의 닫힌 시스템이라는 것이었습니다. 버그는 항상 이 네 가지 중 하나에 있습니다. 이 네 가지를 동시에 볼 수 있다면 12분 만에 버그를 찾을 수 있습니다. 볼 수 없다면 일주일 내내 쫓아다닐 수 있습니다.

디버거가 예상치 못하게 드러낸 또 다른 사실은 제 에이전트의 비결정성이었습니다. 수정 후 동일한 프롬프트를 다섯 번 실행하여 확인했습니다. 세 번의 실행은 get_response_time을 한 번 호출했습니다. 두 번의 실행은 두 번 호출했는데, 두 번째 호출에서는 엔드포인트 경로의 대소문자가 달랐습니다. 제 도구 스키마는 대소문자를 구분했습니다. 실패한 테스트 케이스들이 모두 소문자를 사용했기 때문에 저는 알아차리지 못했습니다. 이것은 제가 보지 못하고 출시했을 두 번째 버그였습니다.

다중 실행 분석은 앞으로 제가 가장 많이 사용할 기능입니다. 실행 버튼을 다섯 번 클릭하세요. 세션 패널을 보세요. 실행마다 달라지는 모든 것은 여러분의 에이전트가 취약한 부분입니다.

직접 해보기: 전체 설정 가이드

버그 사냥 중에 제가 사용했던 것과 동일한 설정을 원한다면, 새로 설치하는 것부터 실행 중인 디버그 세션까지의 경로를 안내합니다. 순서대로 다섯 개의 화면입니다.

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

Apidog를 열고 상단 탭 바에서 AI Agent Debugger를 클릭합니다. 페이지의 상단 섹션에서 모델과 실행 상태를 구성합니다.

• 왼쪽에서 모델 제공업체를 선택합니다 (OpenAI, Anthropic 등)
• 가운데에서 특정 모델을 선택합니다. 예를 들어 gpt-5.5
• 제공업체를 선택하면 기본 URL은 자동으로 채워지므로 수동 입력이 필요 없습니다.
• 세션을 시작하려면 Run을 클릭합니다.

단계 2: 프롬프트 구성

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

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

둘 다 설정되면 오른쪽 상단의 Run을 클릭합니다. 각 실행 후 입력 상자를 자동으로 지우려면 Clear after Send를 선택합니다.

단계 3: 도구 구성

Tools 탭에는 에이전트가 런타임에 호출할 수 있는 모든 항목이 나열됩니다. 탭의 숫자는 현재 사용 가능하거나 구성된 도구의 개수입니다.

내장 도구는 디버거와 함께 제공됩니다. 필요에 따라 켜거나 끕니다.

MCP 도구는 MCP 서버를 통해 외부 시스템 또는 사용자 지정 기능을 추가합니다. 세 가지 연결 방법:

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

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

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

세 개의 작은 탭으로 설정이 완료됩니다.

• Skills: 에이전트의 재사용 가능한 워크플로. 고정된 프로젝트 워크플로, 일반적인 작업 사양 및 시스템 프롬프트에서 반복적인 긴 텍스트를 줄이는 데 유용합니다. 스킬은 런타임에 필요에 따라 로드됩니다.

• Authentication: 모델 서비스 또는 MCP 서비스에 필요한 자격 증명.
• Settings: 온도(Temperature), 최대 토큰(Max Tokens), Top P와 같은 모델 런타임 매개변수. 지원되는 매개변수는 제공업체마다 다르므로 모델이 실제로 무엇을 허용하는지 확인하세요.

단계 5: 세 패널 읽기

실행을 클릭하면 방금 생성한 세션이 왼쪽 패널에 나타납니다. 각 세션은 한 줄 요약을 표시합니다:

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

• 세션 패널 (왼쪽): 요약 메트릭이 포함된 모든 실행 기록
• 턴 패널 (가운데): 사용자/모델 대화의 각 라운드. 라운드를 클릭하여 오른쪽에서 실행 세부 정보를 로드합니다.
• 추적 패널 (오른쪽): 시스템 및 사용자 프롬프트, 모든 모델 호출, 모델이 노출하는 경우 모델의 사고 과정, MCP 도구 호출 및 사용자 지정 스킬 실행, 도구 입력 매개변수, 결과, 소요 시간, 오류 메시지, 최종 출력을 포함한 에이전트의 전체 실행 체인.

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

단계 6: 모델 성능 비교

동일한 프롬프트, 동일한 도구 구성, 다른 모델. 각 실행은 새 세션을 생성하며, 왼쪽 패널에서 이를 나란히 비교할 수 있습니다.

비교할 유용한 메트릭:

• 동일한 작업을 위한 실행 단계 수
• 어떤 모델이 도구를 더 정확하게 선택하는지
• 어떤 모델이 응답 시간이 더 낮은지
• 어떤 모델이 토큰 소비량과 비용을 더 예측 가능하게 유지하는지

핵심 요점

이틀간의 디버깅이 한 오후로 압축되었지만, 저는 버그에 대한 교훈을 얻은 것이 아니었습니다. 저는 도구에 대한 교훈을 얻었습니다. 제가 잘못된 해결책을 쫓고 있었던 이유는 제가 사용하던 도구들이 제가 봐야 할 것을 보여주지 않았기 때문입니다. 저는 모델 출력과 도구 출력을 가지고 있었지만, 그것들을 함께 볼 수 있는 공유 프레임이 없었습니다. 공유 프레임이 바로 핵심입니다.

만약 여러분이 하나 이상의 에이전트를 작성했고 아직 Apidog의 AI Agent Debugger를 열어보지 않았다면, 여러분이 다음에 출시할 에이전트에는 모델과 도구 사이에 존재하는 버그가 있을 것입니다. 여러분은 그것에 일주일을 보낼 것입니다. 실패한 가설들로 가득 찬 노션 페이지를 작성할 것입니다. 그 버그는 디버거가 첫날에 보여주었을 바로 그곳에 있을 것입니다.

Apidog를 다운로드하고 자신감 있는 목소리로 잘못된 답변을 내놓는 다음 에이전트에 대해 사용해보세요. 12분. 47초가 아닌 47밀리초.

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