다른 AI 에이전트와 대화하는 AI 에이전트를 구축한다면, 다른 모든 사람들이 겪었던 것과 똑같은 난관에 부딪혔을 것입니다. 한 에이전트가 다른 에이전트에게 무엇을 보내는지 깔끔하게 검사할 방법이 없기 때문입니다. 콘솔 로그는 거짓말을 하고, 네트워크 탭은 구조화된 필드를 숨기며, 맞춤형 테스트 스크립트는 빠르게 부패합니다. Apidog의 A2A 디버거는 Agent2Agent(A2A) 프로토콜에 대한 이러한 문제를 해결합니다. 에이전트 카드 URL을 붙여넣고, 연결을 클릭하고, 메시지를 보내고, 세 가지 보기로 응답을 읽어보세요.
이 가이드는 A2A 디버거가 하는 일, 첫 번째 에이전트를 연결하는 방법, 요청 및 응답이 내부적으로 어떻게 보이는지, 그리고 Apidog의 기존 MCP 서버 테스트 도구 옆에서 어떻게 작동하는지에 대해 설명합니다. 먼저 상위 프로토콜 컨텍스트가 필요하다면, Apidog의 MCP vs A2A에 대한 심층 분석 글이 이 게시물과 잘 어울립니다.
A2A란 무엇인가 (한 단락으로)
A2A는 Agent2Agent의 약자로, 에이전트 간 통신을 위한 개방형 프로토콜입니다. 이는 한 에이전트가 자신의 기능(에이전트 카드)을 광고하는 방법, 다른 에이전트가 해당 에이전트에 연결하는 방법, 메시지 및 파일 첨부 파일이 교환되는 방법, 그리고 작업 상태가 다시 보고되는 방법을 정의합니다. 에이전트 간 트래픽을 위한 HTTP라고 생각하시면 됩니다. 이는 얇고 벤더 중립적인 사양으로, 데이터 파이프라인의 LangGraph 에이전트가 다른 팀 소유의 CrewAI 에이전트에 서로의 내부를 알지 못한 채 통신할 수 있도록 합니다.
이는 단일 에이전트에게 도구 및 리소스에 대한 액세스를 제공하는 MCP(Model Context Protocol)와는 다릅니다. A2A는 에이전트가 다른 에이전트와 대화하는 것에 관한 것입니다. MCP와 A2A의 차이점에 대한 분석은 그 차이를 가장 명확하게 설명합니다.
A2A 디버거가 제공하는 것
A2A 디버거는 Apidog 내부에 있습니다. 이는 A2A 엔드포인트를 프로덕션 워크플로에 연결하기 전에 테스트하기 위한 시각적 작업 공간입니다. 주요 기능은 다음과 같습니다.
- 에이전트 카드 연결. URL을 붙여넣고, 연결을 클릭하면 에이전트의 이름, 설명, 기능, 선언된 기술 및 프로토콜 버전을 볼 수 있습니다. 카드가 잘못 구성된 경우 연결이 크게 실패하므로, 불필요한 문제를 쫓는 대신 매니페스트를 수정할 수 있습니다.
- 메시지 전송. 일반 텍스트를 작성하고, 파일(에이전트의 선언된 입력 유형이 지원하는 경우)을 첨부하며, 사용자 정의 메타데이터 키-값 쌍을 추가할 수 있습니다.
- 세 가지 응답 보기. 미리보기(Preview)는 구조화된 출력을 렌더링하고, 내용(Content)은 사람이 읽을 수 있는 페이로드를 표시하며, 원본 데이터(Raw Data)는 필드 이름이나 이스케이프 문자를 확인해야 할 때 전체 JSON을 덤프합니다.
- 인증. 베어러 토큰, 기본 인증, 사용자 정의 헤더를 통한 API 키 등 모든 것이 UI에서 지원됩니다.
- 사용자 정의 헤더. 게이트웨이 인증, 비즈니스 매개변수 또는 A2A 엔드포인트가 예상하는 미들웨어를 추가할 수 있습니다.
- 세션 기록. 보내는 모든 메시지는 세션 로그에 기록됩니다. 새 테스트를 시작할 때 이를 지울 수 있습니다.
curl 명령어를 전혀 작성할 필요가 없습니다. Apidog가 JSON-RPC 엔벨로프, SSE 스트리밍(에이전트가 지원하는 경우), 그리고 응답 파싱을 처리합니다.
1단계: 첫 번째 A2A 에이전트에 연결하기
디버거를 열기 전에 세 가지가 필요합니다.
- Apidog 설치 및 업데이트. 최신 클라이언트가 필요합니다. 이전 버전에는 A2A 디버거가 포함되어 있지 않습니다. 아직 Apidog가 없다면 Apidog를 다운로드하세요.
- 에이전트 카드 URL. 이는 모든 A2A 호환 에이전트의 표준 진입점입니다. 로컬 개발의 경우 일반적으로
http://localhost:3000/.well-known/agent.json과 같으며, 호스팅된 에이전트의 경우 플랫폼 공급업체가 경로를 제공할 것입니다. - 자격 증명 (에이전트가 요구하는 경우). 베어러 토큰, API 키 또는 기본 인증.
Apidog를 열고 A2A 디버거 페이지로 이동하여 상단에 에이전트 카드 URL을 붙여넣으세요. 연결(Connect)을 클릭하세요. 에이전트가 유효한 에이전트 카드로 응답하면 상태가 연결됨(Connected)으로 바뀌고 패널에 에이전트의 메타데이터(이름, 설명, 기능, 선언된 기술, 프로토콜 버전)가 채워집니다.
실패하는 경우 가장 흔한 원인은 다음과 같습니다.
- URL이 잘못되었거나 에이전트가 실행되고 있지 않습니다. 브라우저에서 URL을 호출하여 JSON 페이로드가 반환되는지 확인하세요.
- 에이전트 카드에 필수 필드가 누락되었습니다. GitHub의 A2A 프로토콜 사양과 비교하여 확인하세요.
- 에이전트가 검색 엔드포인트에 인증을 요구합니다. 연결을 클릭하기 전에 Apidog에 인증 정보를 추가하세요.
2단계: 테스트 메시지 보내기
연결되면 메시지(Messages) 탭을 여세요. 일반적인 채팅 인터페이스에서처럼 프롬프트를 입력하세요. 예를 들어:
공유 지식 기반에서 최근 세 가지 고객 피드백 노트를 요약한 다음, 지원 팀을 위한 한 단락의 답장을 작성해 줘.
보내기 전에 추가할 수 있는 선택 사항:
- 파일 첨부. 종이 클립 아이콘을 클릭하고 파일을 선택합니다. 디버거는 에이전트의 선언된 입력 유형을 확인하고 지원되지 않는 파일 유형을 사전에 거부하여, 415 오류로 인한 왕복 전송을 낭비하지 않도록 합니다.
- 사용자 정의 메타데이터.
priority: high또는tenant: acme-corp와 같은 키-값 쌍을 추가합니다. 이들은 A2A 요청 엔벨로프에 포함되어 에이전트 핸들러가 이를 읽는다면 에이전트에게 표시됩니다.
보내기(Send)를 클릭합니다. Apidog는 프롬프트를 A2A 메시지 구조로 래핑하고, 에이전트로 전송하며, 응답을 기다립니다.
3단계: 세 가지 보기로 응답 읽기
A2A 응답은 일반 문자열, 구조화된 JSON, 파일 참조 또는 이들의 혼합일 수 있습니다. 디버거는 동일한 페이로드를 세 가지 관점에서 볼 수 있도록 합니다.
- 미리보기(Preview). Apidog는 구조화된 필드를 트리 형태로 렌더링합니다. 에이전트가 중첩된 객체(작업 ID, 상태, 아티팩트, 기록)를 반환할 때 유용합니다.
- 내용(Content). 사람이 읽을 수 있는 본문입니다. 에이전트가 텍스트를 반환했다면, 이것이 사용자에게 보여줄 내용입니다.
text/plain부분을 포함하는 구조화된 아티팩트를 반환했다면, 이것이 추출된 텍스트입니다. - 원본 데이터(Raw Data). 전체 JSON-RPC 페이로드입니다. 뭔가 잘못되었을 때 버그 보고서에 복사할 내용이며, 규정 준수를 확인할 때 사양과 비교할 내용입니다.
세 가지 보기 사이를 전환해보세요. 미리보기가 제대로 보이지만 내용이 비어 있다면, 에이전트가 Apidog가 렌더링할 수 있지만 평면화하는 방법을 모르는 유형화된 아티팩트를 반환하고 있을 가능성이 높습니다. 원본 데이터에 오류 코드가 표시되면 에이전트가 요청을 거부한 것이며, error.message의 메시지가 문제 해결의 시작점입니다.
세션 기록은 왼쪽 패널에 있습니다. 모든 전송은 되돌아 볼 수 있는 차례가 됩니다. 새 테스트를 시작하고 오래된 컨텍스트가 에이전트를 혼란스럽게 하는 것을 원치 않을 때 지우기(Clear)를 누르세요.
인증: 세 가지 일반적인 패턴
대부분의 프로덕션 A2A 엔드포인트는 어떤 종류의 인증 뒤에 있습니다. 디버거는 즉시 세 가지 패턴을 처리합니다.
베어러 토큰
호스팅된 에이전트에서 가장 흔한 패턴입니다. 인증 패널에서 베어러 토큰(Bearer Token)을 선택하고 토큰을 붙여넣으세요. Apidog는 모든 요청에 Authorization: Bearer <token>을 추가합니다.
Authorization: Bearer sk-agent-7f3e9a...
기본 인증
사용자 이름과 비밀번호로 보호되는 에이전트(내부/레거시 시스템에서 흔함)의 경우입니다. 기본 인증(Basic Auth)을 선택하고 두 값을 모두 입력하면 Apidog가 base64로 인코딩된 Authorization: Basic ... 헤더를 계산합니다.
사용자 정의 헤더를 통한 API 키
에이전트가 X-Agent-Key와 같은 비표준 헤더 이름을 예상하는 경우, 헤더(Headers) 섹션으로 이동하여 수동으로 추가합니다. 게이트웨이 특정 헤더(CSRF 토큰, 테넌트 ID, 요청 서명)에도 동일하게 적용됩니다.
에이전트 자격 증명 관리의 장기적인 관점에 대해서는, Apidog AI 에이전트 자격 증명 가이드에서 무엇을 순환하고, 무엇을 범위화하며, 무엇을 절대 커밋하지 말아야 하는지에 대해 다룹니다.
사용자 정의 헤더와 메타데이터: 언제 무엇을 사용해야 하는가
A2A 요청에는 "추가" 데이터를 담는 두 가지 위치가 있습니다. 비슷하게 들리지만 서로 다른 계층으로 전달됩니다.
| 채널 | 위치 | 사용 용도 |
|---|---|---|
| 사용자 정의 헤더 | HTTP 요청 헤더 | 게이트웨이 인증, 관찰 가능성(X-Request-Id), 기능 플래그 |
| 메타데이터 | A2A 메시지 페이로드 | 에이전트가 읽는 메시지별 컨텍스트(우선순위, 테넌트, 로케일) |
일반적인 규칙: 리버스 프록시 또는 API 게이트웨이가 이를 봐야 한다면 헤더에 넣으세요. 에이전트의 작업 핸들러가 필요로 한다면 메타데이터에 넣으세요. 이 둘을 혼동하는 것이 "왜 에이전트가 내 힌트를 무시했을까" 버그의 가장 큰 원인입니다.
Apidog의 A2A 디버거 vs MCP 서버 테스트
Apidog는 A2A 디버거와 MCP 테스트 흐름을 모두 제공합니다. 이들은 서로 다른 프로토콜을 위한 다른 도구입니다.
| 도구 | 프로토콜 | 테스트 | 사용 시점 |
|---|---|---|---|
| A2A 디버거 | Agent2Agent | 연결성, 메시지 교환, 작업 상태 | 에이전트가 다른 에이전트를 호출하는 다중 에이전트 시스템을 구축할 때 |
| MCP 서버 테스트 | 모델 컨텍스트 프로토콜 | 도구 호출, 리소스 액세스, 프롬프트 템플릿 | 도구/리소스를 에이전트에 노출하는 MCP 서버를 구축할 때 |
어떤 것이 필요한지 확실하지 않다면, MCP vs A2A 가이드가 결정 과정을 안내합니다. 간략히 말해: MCP는 에이전트가 외부 시스템에 접근하는 데 사용하는 것이고, A2A는 에이전트가 다른 에이전트와 대화하는 데 사용하는 것입니다.
워크플로의 MCP 측면을 위해, MCP 서버 테스트 플레이북은 Apidog에서 수동 및 자동 경로를 다룹니다. 많은 팀이 실제 에이전트 시스템이 A2A 조정과 MCP 도구 액세스를 결합하기 때문에 두 가지 표면을 모두 사용하게 됩니다.
일반적인 디버깅 패턴: 태스크 왕복
"에이전트가 예상대로 응답하지 않아" 막혔을 때, 다음 루프를 따라가 보세요.
- A2A 디버거를 엽니다.
- 에이전트에 연결합니다. 에이전트 카드가 예상하는 기술을 표시하는지 확인합니다.
- 해당 기술을 트리거해야 하는 가장 작은 메시지를 보냅니다. 먼저 일반 텍스트를 사용하고, 텍스트 경로가 작동한 후에만 파일과 메타데이터를 추가합니다.
- 처음에는 미리보기(Preview)가 아닌 원본 데이터(Raw Data)를 읽습니다. 에이전트가 정확히 무엇을 출력했는지 확인해야 합니다.
- 응답에 예상하는 필드가 누락되었다면, 그것은 전송 문제가 아니라 에이전트 코드의 문제입니다.
- 응답이 잘 구성되었지만 잘못되었다면, 그것은 프롬프트 또는 모델 문제이며, 이미 전송과 로직을 분리한 상태입니다.
이는 API를 호출하는 AI 에이전트를 테스트하는 방법 게시물에서 API 측면에 적용된 것과 동일한 "책임 전 분리" 루프입니다. 동일한 원칙: 먼저 연결을 확인하고, 그 다음 두뇌를 디버그하세요.
AI 워크플로우에서 A2A 디버거의 위치
다중 에이전트 시스템은 2026년에 많은 중요한 AI 작업이 출시되는 방식입니다. AI 에이전트는 새로운 API 소비자라는 게시물은 에이전트 트래픽을 일급 시민으로 취급해야 하는 이유를 설명합니다. AI 에이전트를 위한 API 설계 후속 게시물은 소비자가 인간 개발자가 아닌 LLM 기반 에이전트일 때 API 계약에서 무엇이 바뀌는지 다룹니다.
A2A 디버거는 Apidog의 MCP 클라이언트 비주얼 디버거와 동일한 계층에 있습니다. 둘 다 에이전트 SDK 내부에 숨겨져 있는 트래픽을 볼 수 있는 창을 제공하는 역할을 합니다. 에이전트를 연결하면, 에이전트가 무엇을 하는지 볼 수 있고, 프로덕션에 도달하기 전에 버그를 수정할 수 있습니다.
Apidog는 무료로 다운로드할 수 있으며, A2A 디버거는 표준 클라이언트에 포함되어 제공됩니다. 별도의 라이선스나 별도의 요금제가 필요 없습니다.
자주 묻는 질문
A2A 디버거는 무료인가요?
네, 그렇습니다. Apidog 표준 클라이언트에 포함되어 있습니다. Apidog를 다운로드하고 충분히 최신 버전이라면 A2A 디버거가 사이드 패널에 나타납니다.
어떤 프레임워크로 작성된 에이전트와도 작동하나요?
유효한 A2A 에이전트 카드를 노출하는 모든 에이전트와 작동합니다. 이 프로토콜은 프레임워크에 구애받지 않으므로, LangGraph, CrewAI, AutoGen, 그리고 사용자 정의 Python 또는 Go 에이전트 모두 A2A 사양을 준수하는 한 작동합니다.
나중에 재생을 위해 세션을 저장할 수 있나요?
세션은 디버거가 열려 있는 동안 유지됩니다. 장기 저장을 위해서는 원본 데이터(Raw Data) 출력을 복사하여 테스트 아티팩트에 저장하십시오. 전체 세션 내보내기는 로드맵에 있습니다.
스트리밍 응답은 어떻게 처리하나요?
에이전트가 SSE 스트리밍(A2A 사양에 따라)을 지원하는 경우, 디버거는 도착하는 청크를 읽고 미리보기(Preview)와 내용(Content)을 실시간으로 업데이트합니다. 원본 데이터(Raw Data)는 스트림이 닫힐 때 조립된 응답을 표시합니다.
메타데이터 필드와 헤더 섹션의 차이점은 무엇인가요?
헤더는 HTTP 계층이고, 메타데이터는 A2A 메시지 계층입니다. 헤더는 게이트웨이 및 리버스 프록시에 도달하며, 메타데이터는 에이전트의 작업 핸들러에 도달합니다. 이 게시물 앞부분의 표를 참조하십시오.
Apidog가 에이전트의 응답을 자체 서버에 로깅하나요?
아니요. Apidog는 로컬 클라이언트로 작동합니다. 사용자 기기와 에이전트 간의 트래픽은 Apidog 인프라를 통과하지 않습니다.
A2A 디버거를 사용하여 다른 네트워크에 호스팅된 에이전트를 테스트할 수 있나요?
네, 네트워크 경로가 열려 있는 한 가능합니다. 디버거는 일반적인 HTTP 클라이언트처럼 아웃바운드 HTTPS 요청을 합니다. 에이전트가 VPN 뒤에 있다면, 해당 VPN을 활성화해야 합니다.
버그를 보고하거나 기능을 요청하려면 어디로 가야 하나요?
Apidog 피드백 채널이 주요 경로이며, A2A 프로토콜 GitHub 저장소는 상위 사양이 발전하는 곳이므로 사양 수준 요청은 그곳에 제출해야 합니다.
지금 바로 시도해 보세요
접근할 수 있는 가장 간단한 A2A 에이전트를 선택하세요. 아직 없다면, A2A 참조 구현에는 5분 이내에 로컬에서 실행할 수 있는 샘플 서버가 포함되어 있습니다. 해당 에이전트 카드 URL을 Apidog의 A2A 디버거에 붙여넣고, "hello" 메시지를 보낸 다음, 세 가지 응답 보기가 채워지는 것을 확인하세요. 이것이 가장 작은 엔드투엔드 루프이며, 거기서부터 실제 프롬프트, 파일 첨부 및 다중 에이전트 워크플로로 확장할 수 있습니다.
나머지 API 및 MCP 작업을 위해 디버거를 Apidog와 함께 사용하면, 에이전트 시스템이 실행되는 세 가지 프로토콜(HTTP, MCP, A2A)을 위한 단일 인터페이스를 갖게 됩니다.
버튼