AI Agent Debugger

AI Agent Debugger는 AI Agent 개발자를 위한 시각적 디버깅 도구입니다.

모델 입력과 출력에만 집중하는 디버깅 방식과 달리, AI Agent Debugger는 디버깅 범위를 전체 Agent 실행 프로세스로 확장합니다. 각 대화 라운드, 모든 모델 호출, MCP 도구 호출, 사용자 지정 Skill 실행 및 최종 출력을 명확하게 표시하여, 개발자가 Agent의 작업 체인을 관찰하고 프롬프트, 모델 구성, 도구 호출 또는 비즈니스 로직의 문제를 신속하게 찾을 수 있도록 지원합니다.

AI Agent Debugger는 다음 시나리오에 적용할 수 있습니다.

AI 대형 모델 도구 호출 체인을 디버깅하고, 도구 매개변수, 실행 결과 또는 예외 원인을 문제 해결

동일한 작업을 실행하는 여러 모델의 성능을 비교하고, 응답 시간, Token 소비량, 비용과 같은 주요 지표를 평가

MCP Server와 AI 대형 모델의 통합이 기대에 부합하는지 확인

시스템 프롬프트를 반복적으로 최적화하고, 서로 다른 구성이 실행 결과에 미치는 영향을 관찰

AI Agent Debugger의 전체 기능을 경험하려면 최신 Apidog 클라이언트를 사용하시는 것을 권장합니다.

새 Agent 디버그 세션 생성

Apidog의 상단 탭 표시줄에서 AI Agent Debugger로 이동하십시오.

페이지의 상단 영역은 모델 및 실행 상태를 구성하는 데 사용됩니다.

왼쪽에서 OpenAI 또는 Anthropic과 같은 모델 제공자를 선택합니다.

가운데에서 gpt-5.5와 같은 모델을 선택합니다.

제공자와 모델을 선택하면 https://api.openai.com/v1과 같은 해당 Base URL이 자동으로 매칭되며, 수동 입력은 필요하지 않습니다.

Run을 클릭하여 디버깅을 시작합니다.

프롬프트 구성

Prompts 탭에서 Agent의 입력 콘텐츠를 구성하십시오.

페이지는 두 개의 입력 영역으로 나뉩니다.

System Prompt: Agent 구성에 속하며, Agent의 역할, 목표, 제약 조건 및 도구 사용 규칙을 정의하는 데 사용됩니다.

User Prompt: 이 세션의 테스트 입력을 입력하는 데 사용됩니다. 예: "What's Apidog?"

구성을 완료한 후 오른쪽 상단의 Run을 클릭하여 디버깅을 시작하십시오.

전송 후 입력 상자를 자동으로 지우려면 Clear after Send를 선택할 수 있습니다.

도구 구성

Tools 탭에서 런타임 중 Agent가 호출할 수 있는 도구를 선택할 수 있습니다. 탭의 숫자는 현재 사용 가능하거나 구성된 도구 수를 나타냅니다.

도구는 두 가지 범주로 나뉩니다.

기본 제공 도구

AI Agent Debugger는 AI 대형 모델이 파일을 읽고, 콘텐츠를 검색하고, 명령을 실행하거나, 웹 콘텐츠를 가져올 수 있도록 일반적으로 사용되는 기본 제공 도구를 제공합니다.

도구	설명
`bash`	지속적인 Shell 세션에서 명령을 실행합니다.
`web_fetch`	웹 콘텐츠를 가져와 Markdown, 텍스트 또는 HTML로 변환합니다.
`read`	텍스트, 이미지 또는 PDF 파일을 읽습니다.
`edit`	파일에서 정확한 문자열 치환을 수행합니다.
`write`	파일을 생성하거나 덮어씁니다.
`grep`	정규식을 사용하여 파일 콘텐츠를 검색합니다.
`glob`	glob 패턴을 사용하여 파일을 찾습니다.
`kill_shell`	현재 Shell 세션을 재설정합니다.

필요에 따라 개별 도구를 활성화하거나 비활성화할 수 있습니다. 비활성화된 경우, Agent는 런타임 중 해당 도구를 호출할 수 없습니다.

MCP 도구

Agent가 외부 시스템 또는 사용자 지정 기능을 호출해야 하는 경우, Tools 탭에서 MCP Servers를 추가할 수 있습니다.

AI Agent Debugger는 다음 MCP 연결 방식을 지원합니다.

STDIO: 로컬 MCP Server 프로세스를 실행합니다.

HTTP: Streamable HTTP를 지원하는 MCP Server에 연결합니다.

SSE: Server-Sent Events 기반 MCP Server에 연결합니다.

인증이 필요한 MCP Servers의 경우, 요청 Headers를 구성하거나 OAuth 2.0을 사용하여 인증을 완료할 수 있습니다. 연결에 성공한 후, 도구 목록에서 Agent에 노출할 도구를 선택할 수 있습니다.

Skills 구성

Skills 탭에서 Agent를 위한 재사용 가능한 Skills를 구성할 수 있습니다. 탭의 숫자는 현재 로드된 skill 수를 나타냅니다.

Skills는 다음 시나리오에 적용할 수 있습니다.

프로젝트 내에서 Agent에 고정된 워크플로 제공

일반적인 작업을 위한 작업 사양 재사용

시스템 프롬프트에서 반복되는 긴 텍스트 설명 감소

Agent 런타임 중 관련 Skills는 작업에 따라 필요 시 읽히며, 이를 통해 더 완전한 작업 지침을 얻을 수 있습니다.

인증 및 모델 매개변수 구성

Authentication 탭에서 모델 서비스 또는 MCP 서비스에 필요한 인증 정보를 구성하십시오.

Settings 탭에서 Temperature, Max Tokens, Top P 등과 같은 모델 런타임 매개변수를 구성할 수 있습니다. 모델 제공자마다 지원하는 매개변수가 다를 수 있으므로, 사용 중인 모델 제공자가 실제로 지원하는 매개변수를 참조하십시오.

세션 목록 보기

Run을 클릭할 때마다 왼쪽에 새 세션 기록이 생성됩니다.

세션 목록에는 해당 실행의 요약 정보가 표시됩니다. 예를 들면 다음과 같습니다.

대화 라운드 수

실행 단계 수

응답 시간

Token 소비량

예상 비용

사용된 모델

예:

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

왼쪽에서 다른 세션을 클릭하여 해당 turns 및 호출 traces를 볼 수 있습니다.

Turns 보기

가운데의 Turns 패널은 현재 세션의 다중 라운드 대화를 표시하는 데 사용됩니다.

세션에 여러 사용자 입력이 포함된 경우, 각 라운드는 독립적인 대화 라운드로 표시됩니다. 대화 라운드를 클릭하면 오른쪽에서 해당 호출 프로세스를 볼 수 있습니다.

Traces 보기

오른쪽의 Traces 패널은 Agent의 전체 실행 프로세스를 표시하는 데 사용됩니다.

호출 traces는 실행 순서대로 표시되며, 다음을 보여 줍니다.

사용자 프롬프트 및 시스템 프롬프트

모든 모델 호출

모델 사고 과정(모델이 지원하는 경우)

MCP 도구 호출 및 사용자 지정 Skill 실행

도구 입력 매개변수, 실행 결과, 소요 시간 및 오류 메시지

AI 대형 모델 최종 출력

도구 호출이 실패하거나 모델이 예외를 반환하는 경우, 호출 traces에서 특정 단계를 찾아 입력 매개변수와 반환된 콘텐츠를 확인할 수 있으므로 문제 해결에 도움이 됩니다.

모델 성능 비교

동일한 프롬프트와 도구 구성을 사용하여 서로 다른 모델을 선택해 작업을 실행하고, 세션 목록을 통해 모델 성능을 비교할 수 있습니다.

세션 요약에는 응답 시간, Token 소비량, 예상 비용과 같은 주요 지표가 표시되어, 효과, 성능 및 비용 측면에서 서로 다른 모델 간의 균형을 평가하는 데 도움이 됩니다.

예를 들어 다음을 비교할 수 있습니다.

서로 다른 모델에서 동일한 작업의 실행 단계 수가 달라지는지 여부

어떤 모델이 도구를 더 정확하게 선택할 수 있는지

어떤 모델의 응답 시간이 더 낮은지

어떤 모델의 Token 소비량과 비용이 더 제어 가능한지

FAQ

Agent가 예상한 도구를 호출하지 않았습니다. 어떻게 문제를 해결해야 합니까?

다음 구성을 확인하십시오.

Tools 탭에서 도구가 활성화되어 있는지 여부.

시스템 프롬프트가 도구의 사용 시나리오를 명확하게 설명하는지 여부.

MCP Server가 성공적으로 연결되었고 대상 도구가 비활성화되어 있지 않은지 여부.

호출 traces에 모델 사고 과정 또는 도구 호출 기록이 있는지 여부.

현재 사용 중인 AI 대형 모델이 도구 호출을 지원하는지 여부.

MCP 도구 호출이 실패하면 어떻게 해야 합니까?

호출 traces에서 실패한 도구 호출을 확인할 수 있으며, 입력 매개변수, 출력 결과 및 오류 메시지를 중점적으로 확인하십시오. 일반적인 원인은 다음과 같습니다.

MCP Server가 연결되지 않았거나 연결이 끊어짐

매개변수 형식이 도구 요구 사항을 충족하지 않음

OAuth, API Key 또는 Header 인증 구성이 올바르지 않음

로컬 STDIO 서비스 시작 명령을 사용할 수 없음

동일한 작업을 여러 번 실행하여 무엇을 평가할 수 있습니까?

Agents는 비결정적 시스템입니다. 동일한 프롬프트라도 서로 다른 모델, 서로 다른 매개변수 또는 서로 다른 도구 구성에서는 다른 실행 경로를 생성할 수 있습니다. 여러 번의 실행과 세션 비교를 통해 실행 단계, 호출 결과, 소요 시간, Token 소비량 및 최종 출력을 관찰하여 더 적합한 구성을 평가하는 것을 권장합니다.

새 Agent 디버그 세션 생성#

프롬프트 구성#

도구 구성#

기본 제공 도구#

MCP 도구#

Skills 구성#

인증 및 모델 매개변수 구성#

세션 목록 보기#

Turns 보기#

Traces 보기#

모델 성능 비교#

FAQ#

Agent가 예상한 도구를 호출하지 않았습니다. 어떻게 문제를 해결해야 합니까?#

MCP 도구 호출이 실패하면 어떻게 해야 합니까?#

동일한 작업을 여러 번 실행하여 무엇을 평가할 수 있습니까?#

새 Agent 디버그 세션 생성

프롬프트 구성

도구 구성

기본 제공 도구

MCP 도구

Skills 구성

인증 및 모델 매개변수 구성

세션 목록 보기

Turns 보기

Traces 보기

모델 성능 비교

FAQ

Agent가 예상한 도구를 호출하지 않았습니다. 어떻게 문제를 해결해야 합니까?

MCP 도구 호출이 실패하면 어떻게 해야 합니까?

동일한 작업을 여러 번 실행하여 무엇을 평가할 수 있습니까?