멀티 에이전트 시스템에서 조정자 에이전트는 전문 대상 에이전트와 도구에 작업을 위임합니다. 이러한 대상 에이전트는 멀티 에이전트 시스템 또는 애플리케이션의 하위 에이전트가 됩니다.
Agent Registry를 사용하면 조정자 에이전트가 애플리케이션 코드에 서비스 URL을 하드코딩하지 않고도 런타임에 Agent2Agent(A2A) 및 모델 컨텍스트 프로토콜(MCP) 엔드포인트를 동적으로 조회할 수 있습니다. 에이전트 개발 키트(ADK)의 AgentRegistry 클라이언트 또는 표준 HTTP 및 google-auth 라이브러리를 사용하여 등록된 에이전트 및 MCP 서버를 검색하여 조정자 에이전트를 빌드할 수 있습니다.
오케스트레이터 에이전트가 대상 에이전트의 엔드포인트를 호출하면 요청을 대상 에이전트 런타임 또는 MCP 서버로 직접 전송합니다. 보안 정책을 시행하고, 프로토콜 조정을 수행하고, 대상 Agent Endpoint에 콘텐츠 필터링을 적용하려면 Agent Gateway를 통해 에이전트 호출을 라우팅하면 됩니다.
시작하기 전에
Agent Registry를 통해 대상 Agent Endpoint URL을 조회하거나 A2A 에이전트를 호출하기 전에 다음 단계를 완료하세요.
- Agent Registry 설정
단일 프로젝트 설정의 경우 Agent Registry가 사용 설정된 거버넌스 프로젝트의 프로젝트 ID를 가져옵니다. 여러 프로젝트에 대해 관리 경계를 구성한 경우 경계 전체 검색 및 등록에 관리 프로젝트 ID를 사용하거나 단일 프로젝트 작업에 구성원 프로젝트 ID를 지정합니다.
프레임워크의 클라이언트 종속 항목을 설치합니다.
ADK (pip)
pip install --upgrade "google-adk[a2a,agent-identity,mcp]"google-adk>=1.29.0이상을 설치해야 합니다.ADK (uv)
uv add "google-adk[a2a,agent-identity,mcp]"google-adk>=1.29.0이상을 설치해야 합니다.ADK가 아닌 Python
pip install --upgrade google-auth requests httpx로컬 개발을 위해 애플리케이션 기본 사용자 인증 정보(ADC)를 구성합니다. 그렇지 않으면 외부 환경에서 서비스 계정 또는 워크로드 아이덴티티 제휴 사용자 인증 정보 구성을 연결합니다.
gcloud auth application-default login다음 환경 변수를 설정합니다.
export GOOGLE_CLOUD_PROJECT=PROJECT_ID export GOOGLE_CLOUD_LOCATION=LOCATION다음을 바꿉니다.
PROJECT_ID: 거버넌스 프로젝트의 프로젝트 ID입니다.LOCATION: 에이전트와 MCP 서버가 등록된 에이전트 레지스트리 위치입니다(예:global또는us-central1).
필요한 역할
로컬 개발에 사용자 계정을 사용하거나 오케스트레이터 에이전트에 서비스 계정 또는 에이전트 보안 주체를 사용하여 등록된 구성요소를 검색하고 대상 A2A 에이전트를 호출할 수 있습니다. 사용자 계정, 서비스 계정 또는 에이전트 보안 주체에게는 구성요소를 검색하고 대상 A2A 에이전트를 호출할 수 있는 적절한 역할이 있어야 합니다.
사용자 계정, 서비스 계정 또는 에이전트 보안 주체에 등록된 구성요소를 검색하고 대상 A2A 에이전트를 호출하는 데 필요한 권한이 있는지 확인하려면 관리자에게 Agent Registry가 사용 설정된 거버넌스 프로젝트에서 사용자 계정, 서비스 계정 또는 에이전트 보안 주체에 다음 IAM 역할을 부여해 달라고 요청하세요.
-
등록된 에이전트 및 MCP 서버 검색: Agent Registry API 뷰어(
roles/agentregistry.viewer) -
런타임에 대상 A2A 에이전트를 호출하려면 대상 에이전트를 호스팅하는 서비스의 런타임 또는 게이트웨이 역할이 필요합니다. 예를 들어 대상 에이전트가 Cloud Run에서 실행되는 경우 계정 또는 주 구성원에 Cloud Run 호출자 역할(
roles/run.invoker)이 있어야 합니다.
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
관리자는 커스텀 역할이나 다른 사전 정의된 역할을 통해 사용자 계정, 서비스 계정 또는 에이전트 보안 주체에 필요한 권한을 부여할 수도 있습니다.
대상 A2A 에이전트 엔드포인트의 사용자 인증 정보 선택
에이전트 레지스트리에서 구성요소를 조회하고 대상 A2A 에이전트 엔드포인트를 호출하려면 별도의 인증 토큰이 필요합니다. 오케스트레이터 에이전트가 대상 A2A 에이전트 Agent Endpoint를 호출할 때 해당 Agent Endpoint에서 예상하는 Bearer 토큰 유형을 연결해야 합니다.
| 대상 A2A 에이전트 엔드포인트 | 필수 Bearer 토큰 | 사용자 인증 정보 소스 및 가이드 |
|---|---|---|
Google Cloud API 에이전트 엔드포인트(https://*.googleapis.com) |
https://www.googleapis.com/auth/cloud-platform 범위 또는 더 좁은 서비스 범위가 있는 OAuth 2.0 액세스 토큰 기본 할당량 프로젝트가 구성되지 않은 애플리케이션 기본 사용자 인증 정보(ADC)를 사용하는 경우 X-Goog-User-Project 헤더를 포함하여 API 할당량에 대해 청구되는 프로젝트를 지정합니다. 자세한 내용은 REST 요청으로 할당량 프로젝트 설정을 참조하세요. |
애플리케이션 기본 사용자 인증 정보(ADC), 연결된 서비스 계정 또는 워크로드 아이덴티티 제휴 사용자 인증 정보 구성을 사용하는 google.auth.default() 호출당 권한을 제한하려면 서비스 계정 가장 사용을 참조하세요. |
Cloud Run 또는 IAP(Identity-Aware Proxy) HTTPS 에이전트 엔드포인트(https://*.run.app 또는 커스텀 도메인) |
aud 클레임이 대상 서비스 URL 또는 IAP OAuth 2.0 클라이언트 ID와 일치하는 ID 토큰 |
서비스 계정 또는 컴퓨팅 메타데이터 서버를 사용하는 google.oauth2.id_token.fetch_id_token() 설정 안내는 ID 토큰 가져오기, Cloud Run의 서비스 간 인증, IAP의 프로그래매틱 인증을 참조하세요. |
| OAuth 바인딩 외부 또는 SaaS 에이전트 | 2-legged OAuth 2.0 토큰, 3-legged OAuth 2.0 토큰 또는 API 키. | 에이전트 아이덴티티 인증 관리자 바인딩이 에이전트에 연결되면 ADK에서 자동으로 관리됩니다. 설정 안내는 도구 및 리소스에 인증을 참조하세요. |
ADK에서 AgentRegistry 클라이언트 초기화
ADK를 통해 Agent Registry와 상호작용하려면 Python 코드에서 거버넌스 프로젝트 ID와 Agent Registry 위치를 사용하여 AgentRegistry 클라이언트를 초기화합니다.
import os
from google.adk.integrations.agent_registry import AgentRegistry
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global")
if not project_id:
raise ValueError("GOOGLE_CLOUD_PROJECT environment variable not set.")
registry = AgentRegistry(
project_id=project_id,
location=location,
)
ADK AgentRegistry 클라이언트를 초기화한 후 Agent Registry에서 원격 A2A 에이전트와 원격 MCP 도구를 가져올 수 있습니다. ADK에서 등록된 A2A 에이전트는 RemoteA2aAgent 인스턴스로 래핑됩니다. 이러한 인스턴스는 ADK가 로컬 프로세스에서 실행하는 대신 네트워크를 통해 작업을 위임하므로 원격 에이전트라고 합니다. 마찬가지로 등록된 원격 MCP 서버는 McpToolset 인스턴스로 래핑됩니다.
ADK로 멀티 에이전트 시스템 구성
Agent Registry에서 원격 A2A 하위 에이전트와 원격 MCP 도구 모음을 가져와 LlmAgent 조정자 에이전트 정의에 포함하려면 초기화된 AgentRegistry 클라이언트를 사용합니다.
- 원격 A2A 에이전트 검색: 하위 에이전트의 상대적 리소스 이름으로
registry.get_remote_a2a_agent()를 호출합니다. 이 리소스 이름은AgentRegistry클라이언트에 구성된 프로젝트 ID 및 위치를 사용하는agents/AGENT_ID형식의 상대적 리소스 이름이거나projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID형식의 전체 리소스 이름일 수 있습니다. 에이전트에 인증 관리자Binding가 있으면get_remote_a2a_agent()가 요청 사용자 인증 정보를 자동으로 구성합니다.Binding가 없으면httpx.Auth핸들러로 구성된 맞춤httpx_client를 전달합니다. - 원격 MCP 도구 세트를 가져오려면 MCP 서버의 상대 리소스 이름(
mcpServers/SERVER_ID) 또는 전체 리소스 이름(projects/PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID)을 사용하여registry.get_mcp_toolset()를 호출합니다.
다음 예시에서는 ADK agent.py 파일에서 조정자 에이전트를 정의하는 방법을 보여줍니다. 이 샘플에서는 다음 사항을 고려하세요.
GoogleApiAuth클래스는Google Cloud API(https://*.googleapis.com) A2A 하위 에이전트를 호출하기 위한httpx.Auth핸들러를 구현합니다.google.auth.default()를 사용하여 애플리케이션 기본 사용자 인증 정보, 연결된 서비스 계정 또는 워크로드 아이덴티티 제휴 사용자 인증 정보를 로드하고 각 요청에Authorization및X-Goog-User-Project헤더를 설정합니다.registry클라이언트는 Agent Registry에서 원격 A2A 하위 에이전트와 원격 MCP 도구 모음을 가져와sub_agents및tools매개변수를 통해LlmAgent에 전달합니다.
import httpx
import google.auth
from google.auth.transport.requests import Request
from google.adk.agents.llm_agent import LlmAgent
class GoogleApiAuth(httpx.Auth):
def __init__(self, user_project_id: str):
self.user_project_id = user_project_id
self.creds, _ = google.auth.default(
scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
def auth_flow(self, request):
if not self.creds.valid:
self.creds.refresh(Request())
request.headers["Authorization"] = f"Bearer {self.creds.token}"
request.headers["X-Goog-User-Project"] = self.user_project_id
yield request
quota_project_id = "QUOTA_PROJECT_ID"
agent_name = "agents/AGENT_ID"
httpx_client = httpx.AsyncClient(
auth=GoogleApiAuth(quota_project_id),
timeout=httpx.Timeout(60.0),
)
my_remote_agent = registry.get_remote_a2a_agent(
agent_name=agent_name,
httpx_client=httpx_client,
)
mcp_server_name = "mcpServers/SERVER_ID"
my_mcp_toolset = registry.get_mcp_toolset(mcp_server_name=mcp_server_name)
root_agent = LlmAgent(
model="MODEL_ID",
name="travel_orchestrator",
instruction=(
"You are a travel coordinator. Use your subagents to book travel "
"and your tools to query historical travel data."
),
tools=[my_mcp_toolset],
sub_agents=[my_remote_agent],
)
다음을 바꿉니다.
QUOTA_PROJECT_ID:Google Cloud API Agent Endpoint에 대한 요청에서 할당량 및 결제 기여 분석에 사용되는 프로젝트 ID입니다.AGENT_ID: 조정자 에이전트가 호출할 등록된 A2A 하위 에이전트의 ID입니다(예:agentregistry-01234456-7890-abcd-1234-567890abcdef).SERVER_ID: 조정자 에이전트가 사용할 등록된 MCP 서버의 ID입니다.MODEL_ID: 조정자 에이전트의 모델 ID입니다(예:gemini-2.5-flash).
ADK 프로젝트의 agent.py 파일에 root_agent를 저장한 후 adk run 또는 adk web CLI 명령어를 사용하여 오케스트레이터 에이전트를 로컬에서 테스트하고 실행하거나 Gemini Enterprise Agent Platform의 Agent Runtime에 배포할 수 있습니다. 전체 프로젝트 구조 및 실행 안내는 ADK Python 빠른 시작 및 GitHub의 ADK 에이전트 레지스트리 샘플을 참고하세요.
ADK가 아닌 클라이언트에서 A2A 에이전트 호출
ADK 없이 커스텀 조정자 에이전트 또는 클라이언트를 빌드하는 경우 애플리케이션은 다음 두 가지 인증 단계를 수행합니다.
- 검색: OAuth 2.0 액세스 토큰을 사용하여 Agent Registry API에 인증하여 대상 하위 에이전트의
Agent리소스를 검색하고 에이전트 카드를 검사합니다. - 런타임 호출: 대상 에이전트 엔드포인트에 필요한 Bearer 토큰을 연결합니다. 이 토큰은
*.googleapis.com에이전트 엔드포인트의 OAuth 2.0 액세스 토큰 또는 Cloud Run 및 IAP 에이전트 엔드포인트의 OIDC ID 토큰입니다. 그런 다음 A2ASendMessage요청을 보냅니다. 출력은SendMessageResponseJSON 객체를 반환하며, 여기에는{"task": ...}또는{"message": ...}형식의task또는message필드가 포함됩니다. 이 필드에는 오케스트레이터 에이전트가 워크플로에서 파싱하고 사용할 수 있는 하위 에이전트의 대답이 포함됩니다.
google-auth 및 httpx를 사용하여 등록된 A2A 하위 에이전트를 조회하고 호출하려면 다음 단계를 완료하세요.
OAuth 2.0 액세스 토큰을 사용하여 Agent Registry에 인증하고 Agent Registry API에서 하위 에이전트의
Agent리소스를 가져옵니다.import os import uuid from urllib.parse import urlparse import google.auth from google.auth.transport.requests import Request from google.oauth2 import id_token import httpx project_id = os.environ["GOOGLE_CLOUD_PROJECT"] location = os.environ.get("GOOGLE_CLOUD_LOCATION", "global") agent_id = "AGENT_ID" creds, _ = google.auth.default( scopes=["https://www.googleapis.com/auth/cloud-platform"] ) creds.refresh(Request()) registry_url = ( f"https://agentregistry.googleapis.com/v1/projects/{project_id}" f"/locations/{location}/agents/{agent_id}" ) client = httpx.Client(timeout=60.0) reg_response = client.get( registry_url, headers={ "Authorization": f"Bearer {creds.token}", "X-Goog-User-Project": project_id, }, ) reg_response.raise_for_status() agent_resource = reg_response.json()AGENT_ID을 호출하려는 등록된 A2A 하위 에이전트의 ID로 바꿉니다(예:agentregistry-01234456-7890-abcd-1234-567890abcdef).Agent리소스의 에이전트 카드에서 HTTP 기반 A2A 인터페이스를 추출합니다.card = agent_resource.get("card", {}).get("content", {}) interfaces = card.get("supportedInterfaces") or ( (agent_resource.get("protocols") or [{}])[0].get("interfaces", []) ) iface = next( i for i in interfaces if i.get("protocolBinding", "HTTP+JSON") in ("HTTP+JSON", "HTTP_JSON", "JSONRPC") ) endpoint_url = iface["url"] binding = iface.get("protocolBinding", "HTTP+JSON") tenant = iface.get("tenant", "")*.googleapis.comAgent Endpoint의 OAuth 2.0 액세스 토큰 또는 Cloud Run 또는 IAP Agent Endpoint의 OIDC ID 토큰을 사용하여 요청 헤더를 준비합니다.host = urlparse(endpoint_url).hostname or "" headers = {"Content-Type": "application/json", "A2A-Version": "1.0"} if host == "googleapis.com" or host.endswith(".googleapis.com"): headers["Authorization"] = f"Bearer {creds.token}" headers["X-Goog-User-Project"] = project_id else: oidc_audience = f"https://{host}" oidc_jwt = id_token.fetch_id_token(Request(), oidc_audience) headers["Authorization"] = f"Bearer {oidc_jwt}"에이전트 카드의 프로토콜 바인딩을 사용하여 A2A
SendMessage요청의 형식을 지정하고 전송한 후 하위 에이전트의 응답을 파싱합니다.message = { "messageId": str(uuid.uuid4()), "role": "ROLE_USER", "parts": [{"text": "Summarize recent deployment status."}], } if binding == "JSONRPC": params = {"message": message} if tenant: params["tenant"] = tenant payload = { "jsonrpc": "2.0", "id": str(uuid.uuid4()), "method": "SendMessage", "params": params, } target_url = endpoint_url else: payload = {"message": message} prefix = f"/{tenant.strip('/')}" if tenant else "" target_url = f"{endpoint_url.rstrip('/')}{prefix}/message:send" response = client.post(target_url, headers=headers, json=payload) response.raise_for_status() body = response.json() if binding == "JSONRPC": if "error" in body: raise RuntimeError(f"JSON-RPC error: {body['error']}") send_message_response = body["result"] else: send_message_response = body print(send_message_response) client.close()이 단계에서는 A2A 버전
1.0의SendMessage요청 형식을 지정합니다. A2A 프로토콜 버전1.0과0.3간에 자동으로 협상해야 하는 경우 ADK 또는a2a-sdkPython 클라이언트를 사용하세요.
ADK의 조정자 에이전트 간에 원격 에이전트 재사용
네트워크 지연 시간을 최소화하려면 모든 요청에서 get_remote_a2a_agent()를 호출하는 대신 애플리케이션 시작 시 Agent Registry에서 원격 에이전트와 도구 모음을 한 번 가져옵니다.
ADK에서 RemoteA2aAgent 인스턴스는 한 번에 하나의 상위 조정자 에이전트만 가질 수 있습니다. 초기화 설정에 이어 .clone()를 호출하여 각 상위 조정자 에이전트의 독립적인 사본을 만듭니다.
agent_path = (
f"projects/{project_id}/locations/{location}"
"/agents/AGENT_ID"
)
base_remote_agent = registry.get_remote_a2a_agent(
agent_name=agent_path,
httpx_client=httpx_client,
)
flight_orchestrator = LlmAgent(
model="gemini-2.5-flash",
name="flight_orchestrator",
sub_agents=[base_remote_agent.clone()],
)
hotel_orchestrator = LlmAgent(
model="gemini-2.5-flash",
name="hotel_orchestrator",
sub_agents=[base_remote_agent.clone()],
)
AGENT_ID를 조정자 에이전트가 호출할 등록된 A2A 하위 에이전트의 ID로 바꿉니다.
다음 단계
- 전송 바인딩 및 작업 수명 주기 상태에 관한 A2A 프로토콜을 검토합니다.
- 대상 Agent Endpoint의 트래픽을 라우팅하고 제어하도록 Agent Gateway를 설정하는 방법을 알아보세요.
- 도구 및 리소스에 인증하고 에이전트 호출 전반에서 사용자 인증 정보의 범위를 지정하는 방법을 알아봅니다.
- Agent Registry에서 스킬을 등록하고 스킬을 관리하는 방법을 알아보세요.