멀티테넌시와 멀티 에이전트 라우팅

멀티테넌시와 멀티 에이전트 라우팅 (Multi-Tenancy)

하나의 A2A 엔드포인트가 여러 에이전트 또는 테넌트를 서빙할 수 있어요. A2A 프로토콜은 특정 라우팅 구현을 규정하지 않아요. 운영자는 자신의 인프라에 가장 잘 맞는 방식을 자유롭게 선택할 수 있죠. 이 문서는 프로토콜이 지원하는 라우팅 메커니즘과, Agent Card에 라우팅 식별자가 공개되었을 때 클라이언트가 따라야 하는 규칙을 설명해요.

출처: 문서

본문

개요

일반적인 배포 패턴은 여러 에이전트를 단일 호스트나 리버스 프록시 뒤에 두는 것이에요. 외부에서 에이전트는 같은 도메인에서 접근 가능하지만, 요청이 올바른 백엔드로 전달되도록 각 개별 에이전트를 구분해야 해요. 세 가지 보완적인 접근 방식이 있어요.

1. URL 기반 라우팅(하위 경로)

각 에이전트에 고유한 URL 접두사를 할당해요. 각 에이전트의 Agent Card는 supportedInterfaces에서 자신의 url을 공개하므로, 클라이언트는 자동으로 올바른 경로로 요청을 보내요.

"billing" 에이전트의 Agent Card:

{
  "name": "Billing Agent",
  "supportedInterfaces": [
    {
      "url": "https://agents.example.com/billing",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0"
    }
  ]
}

"support" 에이전트의 Agent Card:

{
  "name": "Support Agent",
  "supportedInterfaces": [
    {
      "url": "https://agents.example.com/support",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0"
    }
  ]
}

게이트웨이나 리버스 프록시는 /billing/*와 /support/*를 적절한 백엔드로 라우팅해요. 이는 가장 단순한 접근 방식이고, Agent Card를 읽는 것 외에 클라이언트의 특별한 인지가 필요 없어요.

2. 인증 헤더 기반 라우팅

여러 에이전트가 같은 URL을 공유할 때, 게이트웨이는 요청에 이미 있는 인증 자격 증명을 사용해 어느 에이전트로 라우팅할지 결정할 수 있어요. 인증 요구사항은 Agent Card의 securitySchemes와 security 필드에 선언되므로, 이 접근 방식을 클라이언트가 완전히 발견할 수 있어요. 예를 들어:

  • 클레임(예: audience 또는 scope)이 대상 에이전트를 식별하는 bearer 토큰.
  • 게이트웨이 구성에서 특정 에이전트에 매핑되는 API 키.

게이트웨이는 자격 증명을 검사하고 A2A 프로토콜 메시지 자체를 변경하지 않고 요청을 적절한 백엔드로 전달해요.

3. tenant 필드를 사용한 본문 기반 라우팅

모든 A2A 요청 메시지에는 선택적 tenant 필드가 포함돼요. 이는 그 값이 서버 운영자가 전적으로 정의하는 불투명한 문자열이에요. 프로토콜은 그에 어떤 형식이나 의미도 부과하지 않아요. 게이트웨이나 에이전트 구현이 이 필드를 검사해 요청을 적절한 백엔드로 전달할 수 있어요. 특정 에이전트에 대해 클라이언트가 사용해야 하는 tenant 값은 supportedInterfaces 안의 AgentInterface 항목에 게시돼요:

{
  "name": "Billing Agent",
  "supportedInterfaces": [
    {
      "url": "https://agents.example.com/a2a",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0",
      "tenant": "billing"
    }
  ]
}
  • 클라이언트 요구사항: 클라이언트는 선택한 AgentInterface 항목의 tenant 값을 모든 요청 메시지에서 반드시 그대로 반영(echo)해야 해요. AgentInterface가 tenant를 설정하지 않으면 이 필드는 요청에서 반드시 생략돼야 해요. 규범적 규칙은 스펙의 8.3.2절을 참고하세요.
  • 서버는 tenant 필드를 배포에 맞는 어떤 라우팅 키 — 에이전트 식별자, 워크스페이스 슬러그, 조직 ID, 또는 기타 불투명한 구분자 — 를 나타내는 데 사용할 수 있어요.

접근 방식 결합하기

세 접근 방식은 상호 배타적이지 않아요. 예를 들어 배포는 주요 제품 라인을 구분하는 데 URL 기반 라우팅을, 각 제품 라인 내 개별 고객을 구분하는 데 tenant 필드를 사용할 수 있어요. 적절한 조합은 운영자의 아키텍처와 사용 중인 게이트웨이의 역량에 따라 달라져요.

여러 에이전트 발견하기

여러 에이전트가 공유 도메인 뒤에 배포될 때, 각 에이전트는 적절한 위치에 자신의 Agent Card를 게시해야 해요(Agent Discovery 참고). 클라이언트는 각 에이전트의 카드를 독립적으로 가져오고, 그 안의 supportedInterfaces 정보 — tenant 값 포함 — 를 사용해 올바른 에이전트와 통신해요.

더 알아보기 (Learn more)