커스텀 프로토콜 바인딩

커스텀 프로토콜 바인딩 (Custom Protocol Bindings)

A2A 프로토콜은 대부분의 배포 시나리오를 다루는 세 가지 표준 바인딩(JSON-RPC, gRPC, HTTP+JSON/REST)과 함께 제공돼요. 커스텀 프로토콜 바인딩은 구현자가 표준 집합으로 다루지 못하는 추가 전송 메커니즘 위에서 A2A 연산을 노출할 수 있게 해요. 커스텀 프로토콜 바인딩은 확장(Extensions)과 보완적이지만 구별되는 개념이에요. 확장은 기존 전송 위에 새 데이터, 메서드, 상태 전이를 추가해 프로토콜 상호작용의 동작을 수정해요. 커스텀 프로토콜 바인딩은 전송 계층 자체를 변경해요. 예를 들어 저지연 양방향 통신을 위해 WebSockets로 A2A를 노출하거나, 연결이 제한된 IoT 환경을 위해 MQTT로 노출하는 방식이에요.

출처: 문서

본문

Agent Card에서의 선언

커스텀 프로토콜 바인딩은 Agent Card의 supportedInterfaces 목록에 선언돼요. 각 항목은 전송을 URI로, 엔드포인트 URL로, 구현하는 A2A 프로토콜 버전으로 식별해요. protocolBinding 필드는 바인딩을 고유하게 식별하는 URI여야 해요(규범적 요구사항과 버전 관리 지침은 스펙 5.8절 참고).

{
  "supportedInterfaces": [
    {
      "url": "wss://agent.example.com/a2a/websocket",
      "protocolBinding": "https://a2a-protocol.org/bindings/websocket",
      "protocolVersion": "1.0"
    }
  ]
}

여러 바인딩을 지원하는 에이전트는 모두 나열해요. 클라이언트는 supportedInterfaces를 순서대로 파싱하고 자신이 지원하는 첫 번째 전송을 선택하므로, 항목은 선호 순서로 나열해야 해요.

요구사항(Requirements)

커스텀 프로토콜 바인딩은 스펙의 Protocol Binding Requirements and Interoperability 섹션의 모든 요구사항을 준수해야 해요. 특히:

  • 모든 핵심 연산 지원: 바인딩은 추상 연산 계층에 정의된 모든 연산(메시지 전송, 태스크 가져오기, 태스크 취소, 스트리밍, 푸시 알림 등)을 노출해야 해요.
  • 데이터 모델 보존: 모든 데이터 구조는 표준 Protocol Buffer 정의와 기능적으로 동등해야 해요. JSON 직렬화는 camelCase 필드 이름을 사용해야 하고, 타임스탬프는 UTC의 ISO 8601 문자열이어야 해요.
  • 동작 일관성: 의미적으로 동등한 요청은 어떤 바인딩을 쓰든 의미적으로 동등한 결과를 내야 해요.

지정해야 할 핵심 영역

커스텀 바인딩 스펙은 다음 각 영역을 다뤄야 해요.

데이터 타입 매핑

각 Protocol Buffer 타입이 커스텀 전송에서 어떻게 표현되는지 문서화해요. 다음을 포함해요.

  • 이진 데이터 인코딩(예: 텍스트 기반 전송의 base64)
  • Enum 표현(문자열, 정수, 또는 명명된 상수)
  • 타임스탬프 형식(핵심 규약에 따른 UTC의 ISO 8601 문자열)

서비스 매개변수

서비스 매개변수는 트레이싱 식별자나 인증 힌트 같은 수평 적용 컨텍스트를 전달하는 데 쓰는 키-값 쌍이에요. 바인딩 스펙은 다음을 명시해야 해요.

  • 서비스 매개변수를 전달하는 메커니즘(예: 커스텀 메시지 헤더, 최상위 metadata 필드)
  • 키와 값에 대한 문자 인코딩 또는 크기 제약
  • 바인딩 자체가 예약한 이름

네이티브 헤더 지원이 없는 전송에서는 서비스 매개변수를 전용 metadata 필드(예: a2a-service-parameters)의 JSON 객체로 임베드하는 일반적인 패턴이 있어요.

오류 매핑

바인딩은 모든 A2A 오류 유형을 그 의미를 보존하면서 전송 네이티브 오류 표현으로 매핑해야 해요. 스펙의 Error Code Mappings 섹션에 있는 매핑 테이블과 동등한 테이블을 제공해서, 각 A2A 오류 유형(예: TaskNotFoundError, UnsupportedOperationError)이 커스텀 바인딩의 네이티브 오류 형식에서 어떻게 표현되는지 보여줘야 해요.

스트리밍

전송이 스트리밍을 지원하면 다음을 문서화해요.

  • 스트림 메커니즘(예: WebSocket 프레임, 청크 인코딩, 롱 폴링)
  • 순서 보장(이벤트는 생성된 순서대로 전달되어야 함)
  • 연결이 끊겼을 때의 재연결 동작
  • 스트림 완료 또는 종료가 클라이언트에 어떻게 신호되는지

전송이 스트리밍을 지원하지 않으면, 이 제한을 Agent Card에 명확히 명시해서 클라이언트가 폴링으로 폴백할 수 있게 해요.

인증과 권한 부여

Agent Card에 선언된 인증 자격 증명이 커스텀 전송으로 어떻게 전송되는지 문서화해요. 인증 챌린지가 클라이언트에 어떻게 전달되는지 정의하고, 커스텀 바인딩이 에이전트의 주요 보안 제어를 우연히 우회하지 않도록 해요.

상호운용성 테스트

커스텀 바인딩을 게시하기 전에 다음을 검증해요.

  • 모든 연산이 동일한 논리 요청에 대해 표준 바인딩과 동일하게 동작하는지
  • 오류 조건, 큰 페이로드, 장기 실행 태스크가 올바르게 처리되는지
  • 표준 바인딩 동작에서 의도적인 이탈이 명확히 문서화되었는지
  • 구현자를 돕기 위해 스펙에 샘플 요청과 응답이 포함되었는지

거버넌스(Governance)

A2A 조직은 커스텀 프로토콜 바인딩이 어떻게 제안, 개발, 승격, 유지되는지에 대한 공식 거버넌스 프레임워크를 사용해요. 공식 바인딩은 https://a2a-protocol.org/bindings/ URI 접두사를 사용하고, a2aproject 조직 아래 cpb- 저장소 접두사로 호스팅돼요(실험 바인딩은 experimental-cpb-를 사용). A2A SDK는 공식 커스텀 프로토콜 바인딩을 구현해야 해요.

URI 네임스페이스 https://a2a-protocol.org/bindings/ 접두사는 Agent Card에서 사용되는 전역 고유 바인딩 식별자를 위한 표준 네임스페이스예요. 이 접두사 아래의 개별 URI, 예를 들어 https://a2a-protocol.org/bindings/{name}/v1은 특정 바인딩과 버전을 식별해요. 이 URI들은 식별자이며 HTTP 접근이 기대되지 않아요. 자세한 내용은 거버넌스 문서의 URI namespaces를 참고하세요.

전체 거버넌스 과정 — 계층(tiers), 수명주기, SDK 지원, 법적 요구사항 포함 — 은 Extension and Protocol Binding Governance 페이지를 참고하세요.

더 알아보기 (Learn more)