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