AX LABS
← 블로그 AX Ops 방법론

Agent Card는 계약이다

A2A v1 적합성은 실행 테스트로 증명한다

AX LABS 7분 읽기

A2A를 붙였다는 말은 현장에서 쉽게 나온다. 하지만 실제 점검에 들어가면 Agent Card는 예쁘게 노출돼 있고, 호출은 특정 SDK끼리만 맞고, 인증 헤더는 문서와 다르게 움직이며, streaming과 push는 장애 상황에서 조용히 빠진다. 이 상태는 연동 완료가 아니다. 운영 전에 깨뜨려야 할 계약이 남아 있는 상태다.

A2A v1 기준에서 Agent Card는 agent의 identity, capabilities, skills, supported communication methods, security requirements를 담는 self-describing manifest다. v1.0.0은 2026-03-12에 릴리스됐고, 2026-05-26에는 v1.0.1 버그픽스 릴리스가 나왔다. 그러므로 2026-07-06 기준 검증 기준은 “v1 계열 계약”으로 잡고, 세부 필드는 현재 spec과 release note를 같이 본다.

Agent Card 검증은 스키마 검사가 아니다

첫 번째 오류는 JSON schema validation에서 멈추는 것이다. supportedInterfaces가 배열이고 securitySchemes가 객체라는 사실은 중요하지만 충분하지 않다. TCK는 “선언한 대로 호출되는가”를 본다.

검증 단위는 세 겹이다.

계약 영역 Agent Card 선언 TCK에서 확인할 행동
interface supportedInterfaces[].url, protocolBinding, protocolVersion, tenant 선언된 binding별 실제 호출, version header 처리, tenant 전달
auth securitySchemes, securityRequirements 무인증 거절, 올바른 credential 수락, scheme별 header 위치
delivery capabilities.streaming, capabilities.pushNotifications SSE stream 또는 webhook POST가 선언과 일치하는지

A2A spec은 supportedInterfaces를 필수 필드로 두고, 첫 번째 entry를 preferred interface로 본다. protocolBinding의 core 값은 JSONRPC, GRPC, HTTP+JSON이다. 운영 검증은 이 우선순위와 binding별 동작을 그대로 따라가야 한다.

Agent Card가 거짓말하면 agent는 운영 자산이 아니라 장애 유발 endpoint다.

supportedInterfaces는 라우팅 계약으로 검증한다

url 하나가 열린다고 끝나지 않는다. v1 Agent Card는 같은 agent 기능을 여러 protocol binding으로 노출할 수 있다. TCK는 card를 읽고, 선언된 transport를 기준으로 suite를 실행해야 한다.

기본 실행은 단순하다.

./run_tck.py --sut-host http://localhost:9999
./run_tck.py --sut-host http://localhost:9999 --transport jsonrpc
./run_tck.py --sut-host http://localhost:9999 --level must

핵심은 fail 조건을 명확히 쓰는 것이다.

  • card에 없는 transport가 내부 설정으로만 동작하면 fail
  • card에 있는 transport가 실제 호출에서 죽으면 fail
  • protocolVersion 불일치에 VersionNotSupportedError를 주지 않으면 fail
  • tenant가 선언됐는데 request routing에 반영되지 않으면 fail

이 검증을 CI에 넣어야 한다. SDK 업그레이드, gateway rule 변경, 인증 프록시 교체 때 Agent Card는 가장 먼저 깨진다.

auth scheme은 문서가 아니라 거절 응답으로 확인한다

A2A는 identity를 protocol payload 안에서 교환하지 않는다. client는 Agent Card의 securitySchemes를 보고 credential을 out-of-band로 얻고, 각 요청의 header 또는 binding별 metadata로 전달한다. server는 선언한 requirement에 따라 모든 incoming request를 인증해야 한다.

따라서 auth conformance test는 성공 케이스보다 실패 케이스가 더 중요하다. 무인증 요청을 통과시키면 fail이다. Bearer를 선언했는데 query parameter API key를 받아들이면 fail이다. skill 단위 securityRequirements가 card 전체 requirement와 충돌하면 fail이다.

API key, HTTP auth, OAuth2, OIDC, mTLS는 각기 다른 운영 통제 지점을 만든다. TCK에는 scheme별 positive·negative fixture를 둔다. 보안팀 리뷰 문서가 아니라 실행 결과로 승인한다.

streaming과 push는 같은 이벤트 계약을 공유한다

A2A v1은 task update delivery를 polling, streaming, push notification으로 나눈다. streaming은 SendStreamingMessage와 SubscribeToTask에서 SSE를 사용하고, capabilities.streaming이 true일 때만 성립한다. push는 webhook POST 방식이며 capabilities.pushNotifications가 true일 때만 관련 config operation이 성립한다.

TCK의 포인트는 둘을 별개 기능으로 보지 않는 것이다. push payload는 streaming과 같은 StreamResponse 형식을 사용한다. 즉 task, message, statusUpdate, artifactUpdate 중 하나가 와야 한다. streaming에서 맞는 event가 push에서 다른 모양으로 오면 fail이다.

운영 전 최소 게이트는 네 가지다.

  1. streaming false에서 streaming method 호출 시 적절한 error 반환
  2. streaming true에서 SSE text/event-stream과 event 순서 확인
  3. push false에서 push config method 거절
  4. push true에서 webhook 인증 header, taskId, 2xx ack 처리 확인

TCK를 릴리스 게이트로 둔다

AX Ops 관점에서 A2A conformance는 개발팀의 선택 과제가 아니다. agent를 사내 플랫폼에 등록하는 입구 조건이다. Agent Card lint, TCK must suite, auth negative test, streaming·push contract replay를 하나의 promotion gate로 묶는다.

정리하면 단순하다. Agent Card를 쓰고, TCK로 읽고, 선언과 실행이 다르면 배포를 멈춘다. 이 규율이 있어야 agent registry가 목록이 아니라 운영 가능한 계약 저장소가 된다. AX 전환에서 이런 검증 체계를 설계하려면 AX Ops 방법론 →

참고