Em sistemas multiagente, um agente orquestrador delega tarefas a agentes e ferramentas de destino especializados. Esses agentes de destino se tornam subagentes do sistema ou aplicativo multiagente.
Com o Registro de Agente, seu agente
orquestrador pode procurar endpoints Agent2Agent (A2A) e do Protocolo de Contexto de Modelo (MCP)
dinamicamente no ambiente de execução sem codificar
URLs de serviço no código do aplicativo. É possível recuperar
agentes registrados e
servidores MCP para criar agentes orquestradores
usando o cliente AgentRegistry no
Kit de Desenvolvimento de Agente (ADK) ou as bibliotecas padrão
HTTP e google-auth.
Quando um agente orquestrador chama o endpoint de um agente de destino, ele envia a solicitação diretamente ao ambiente de execução do agente de destino ou ao servidor MCP. Para aplicar políticas de segurança, realizar mediação de protocolo e aplicar filtragem de conteúdo nos endpoints do agente de destino, é possível rotear as chamadas do agente pelo Gateway de Agente.
Antes de começar
Antes de procurar URLs de Agent Endpoint de destino ou chamar agentes A2A pelo Agent Registry, siga estas etapas:
- Configure o Agent Registry.
Para uma configuração de projeto único, use o ID do projeto da governança em que o Agent Registry está ativado. Se você configurou um limite de gerenciamento para vários projetos, use o ID do projeto de gerenciamento para descoberta e registro em todo o limite ou especifique um ID de projeto de membro para operações em um único projeto.
Instale as dependências do cliente para seu framework:
ADK (pip)
pip install --upgrade "google-adk[a2a,agent-identity,mcp]"É preciso instalar pelo menos
google-adk>=1.29.0.ADK (uv)
uv add "google-adk[a2a,agent-identity,mcp]"É preciso instalar pelo menos
google-adk>=1.29.0.Python sem ADK
pip install --upgrade google-auth requests httpxConfigure o Application Default Credentials (ADC) para desenvolvimento local. Caso contrário, anexe uma conta de serviço ou uma configuração de credencial da federação de identidade da carga de trabalho em ambientes externos:
gcloud auth application-default loginConfigure as seguintes variáveis de ambiente:
export GOOGLE_CLOUD_PROJECT=PROJECT_ID export GOOGLE_CLOUD_LOCATION=LOCATIONSubstitua:
PROJECT_ID: o ID do projeto do seu projeto de governança.LOCATION: o local do Agent Registry em que os agentes e servidores MCP estão registrados, comoglobalouus-central1.
Funções exigidas
É possível usar sua conta de usuário para desenvolvimento local ou uma conta de serviço ou principal do agente para que o agente orquestrador descubra componentes registrados e chame agentes A2A de destino. A conta de usuário, a conta de serviço ou o principal do agente precisa ter os papéis adequados para descobrir componentes e chamar agentes A2A de destino.
Para garantir que sua conta de usuário, conta de serviço ou principal do agente tenha as permissões necessárias para descobrir componentes registrados e chamar agentes A2A de destino, peça ao administrador para conceder os seguintes papéis do IAM à sua conta de usuário, conta de serviço ou principal do agente no projeto de governança em que o Agent Registry está ativado:
-
Para descobrir agentes e servidores MCP registrados:
Leitor da API Agent Registry (
roles/agentregistry.viewer) -
Para chamar um agente A2A de destino no ambiente de execução:
o papel de ambiente de execução ou gateway do serviço que hospeda o agente de destino, necessário para chamar esse agente. Por exemplo, se o agente de destino for executado no Cloud Run, a conta ou o principal precisará ter o papel de invocador do Cloud Run (
roles/run.invoker).
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
O administrador também pode conceder à sua conta de usuário, conta de serviço ou principal do agente as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.
Escolher credenciais para Agent Endpoints A2A de destino
A busca de um componente no Agent Registry e a chamada do Agent Endpoint do agente A2A de destino exigem tokens de autenticação separados. Quando o agente orquestrador chama um endpoint de agente A2A de destino, ele precisa anexar o tipo de token do portador esperado por esse endpoint:
| Endpoint do agente A2A de destino | Token do portador obrigatório | Origem e guias de credenciais |
|---|---|---|
Google Cloud Endpoints do agente da API
(https://*.googleapis.com) |
Token de acesso do OAuth 2.0 com o escopo https://www.googleapis.com/auth/cloud-platform ou um escopo de serviço mais restrito. Ao usar o Application Default Credentials
(ADC) que não tem um
projeto de cota padrão configurado,
inclua o cabeçalho X-Goog-User-Project para especificar o
projeto faturado para a cota da API. Para detalhes, consulte
Definir o projeto de cota com uma solicitação REST. |
google.auth.default() usando o
Application
Default Credentials (ADC), uma conta de serviço anexada ou uma
configuração de credencial da
federação de identidade da carga de trabalho. Para restringir as permissões por chamada, consulte
Usar
a identidade temporária de conta de serviço. |
Endpoints de agente HTTPS do Cloud Run ou do Identity-Aware Proxy (IAP) (https://*.run.app ou domínios personalizados) |
Token de ID
com uma declaração aud que corresponde ao URL do serviço de destino
ou ao ID do cliente OAuth 2.0 do IAP. |
google.oauth2.id_token.fetch_id_token() usando uma conta de serviço ou o servidor de metadados de computação. Para instruções de configuração, consulte
Receber um token de ID,
Autenticação de serviço a serviço
no Cloud Run e
Autenticação programática para
IAP. |
| Agentes externos ou SaaS vinculados ao OAuth | Token do OAuth 2.0 de duas etapas, token do OAuth 2.0 de três etapas ou chave de API. | Gerenciado automaticamente no ADK quando uma vinculação do gerenciador de autenticação de Identidade do Agente é anexada ao agente. Para instruções de configuração, consulte Autenticar em ferramentas e recursos. |
Inicializar o cliente AgentRegistry no ADK
Para interagir com o Agent Registry pelo ADK, inicialize
o cliente AgentRegistry no código Python com o ID do projeto de governança
e o local do Agent Registry:
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,
)
Depois de inicializar o cliente AgentRegistry do ADK, é possível
recuperar agentes A2A remotos e ferramentas MCP remotas do Agent Registry. No
ADK, os agentes A2A registrados são encapsulados como instâncias
RemoteA2aAgent. Essas instâncias são chamadas de agentes remotos porque
o ADK delega tarefas a elas pela rede, em vez de executá-las
no processo local. Da mesma forma, os servidores MCP remotos registrados são encapsulados
como instâncias McpToolset.
Criar um sistema multiagente com o ADK
Para recuperar subagentes remotos de A2A e conjuntos de ferramentas MCP remotos do
Agent Registry e incluí-los em uma definição de agente orquestrador do LlmAgent,
use o cliente AgentRegistry inicializado:
- Para recuperar um agente A2A remoto: chame
registry.get_remote_a2a_agent()com o nome de recurso relativo do subagente. Esse nome de recurso pode ser um nome de recurso relativo no formatoagents/AGENT_ID, que usa o ID do projeto e o local configurado no clienteAgentRegistry, ou o nome completo do recurso no formatoprojects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID. Quando um gerenciador de autenticaçãoBindingexiste para o agente, oget_remote_a2a_agent()configura as credenciais de solicitação automaticamente. Quando não houverBinding, transmita umhttpx_clientpersonalizado configurado com um gerenciadorhttpx.Auth. - Para recuperar um conjunto de ferramentas MCP remoto: chame
registry.get_mcp_toolset()com o nome de recurso relativo do servidor MCP (mcpServers/SERVER_ID) ou o nome de recurso completo (projects/PROJECT_ID/locations/LOCATION/mcpServers/SERVER_ID).
O exemplo a seguir mostra como definir um agente orquestrador em um
arquivo agent.py do ADK. Neste exemplo, considere o seguinte:
A classe
GoogleApiAuthimplementa um gerenciadorhttpx.Authpara chamar um subagente A2A da APIGoogle Cloud (https://*.googleapis.com). Ele usagoogle.auth.default()para carregar o Application Default Credentials, a conta de serviço anexada ou as credenciais da federação de identidade da carga de trabalho e define os cabeçalhosAuthorizationeX-Goog-User-Projectem cada solicitação.O cliente
registryrecupera o subagente A2A remoto e o conjunto de ferramentas MCP remoto do Agent Registry e os transmite paraLlmAgentusando os parâmetrossub_agentsetools.
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],
)
Substitua:
QUOTA_PROJECT_ID: o ID do projeto usado para atribuição de cota e faturamento em solicitações para endpoints do agente da APIGoogle Cloud .AGENT_ID: o ID do subagente A2A registrado que você quer que o agente orquestrador chame, por exemplo,agentregistry-01234456-7890-abcd-1234-567890abcdef.SERVER_ID: o ID do servidor MCP registrado que você quer que o agente orquestrador use.MODEL_ID: o ID do modelo do agente orquestrador, por exemplo,gemini-2.5-flash.
Depois de salvar root_agent no arquivo agent.py do seu projeto do ADK,
você pode testar e executar o agente orquestrador localmente usando os comandos da CLI adk run ou
adk web ou implantá-lo no
Agent Runtime na Gemini Enterprise Agent Platform. Para ver a estrutura completa do projeto e
as instruções de execução, consulte o
guia de início rápido do ADK para Python
e o
exemplo de registro de agente do ADK no GitHub.
Chamar um agente A2A de um cliente que não é do ADK
Se você criar um agente ou cliente orquestrador personalizado sem o ADK, seu aplicativo vai realizar duas etapas autenticadas:
- Descoberta: autentique-se na API Agent Registry com um token de acesso do OAuth 2.0
para recuperar o recurso
Agentdo subagente de destino e inspecionar o Card do Agente. - Chamada de ambiente de execução: anexe o token do portador exigido pelo Agent Endpoint de destino, que é um token de acesso do OAuth 2.0 para Agent Endpoints
*.googleapis.comou um token de ID do OIDC para Agent Endpoints do Cloud Run e do IAP. Em seguida, envie uma solicitação A2ASendMessage. A saída retorna um objeto JSONSendMessageResponse, que contém um campotaskoumessageno formato{"task": ...}ou{"message": ...}. Esse campo contém a resposta do subagente, que o agente orquestrador pode analisar e usar no fluxo de trabalho.
Para procurar e chamar um subagente A2A registrado usando google-auth e httpx,
siga estas etapas:
Faça a autenticação no Agent Registry com um token de acesso do OAuth 2.0 e busque o recurso
Agentdo subagente na API Agent Registry: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()Substitua
AGENT_IDpelo ID do subagente A2A registrado que você quer chamar, por exemplo,agentregistry-01234456-7890-abcd-1234-567890abcdef.Extraia a interface A2A baseada em HTTP do card de agente no recurso
Agent: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", "")Prepare os cabeçalhos da solicitação com um token de acesso do OAuth 2.0 para endpoints de agente do
*.googleapis.comou um token de ID do OIDC para endpoints de agente do Cloud Run ou do IAP: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}"Formate e envie a solicitação A2A
SendMessageusando a vinculação de protocolo do card do agente e analise a resposta do subagente: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()Esta etapa formata uma solicitação
SendMessagepara a versão1.0de A2A. Se você precisar negociar entre as versões1.0e0.3do protocolo A2A automaticamente, use o ADK ou o cliente Pythona2a-sdk.
Reutilizar agentes remotos em agentes de orquestração no ADK
Para minimizar a latência da rede, recupere os agentes remotos e os conjuntos de ferramentas do
Agent Registry uma vez na inicialização do aplicativo, em vez de chamar
get_remote_a2a_agent() em cada solicitação.
No ADK, uma instância de RemoteA2aAgent só pode ter um agente orquestrador pai por vez. Continuando a partir da
configuração de inicialização, chame .clone() para criar uma
cópia independente para cada agente orquestrador pai:
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()],
)
Substitua AGENT_ID pelo ID do subagente de A2A registrado que você quer que os agentes de orquestração chamem.
A seguir
- Consulte o protocolo A2A para vinculações de transporte e estados do ciclo de vida da tarefa.
- Saiba como configurar o Gateway de Agente para rotear e governar o tráfego dos endpoints de agente de destino.
- Saiba como autenticar ferramentas e recursos e definir o escopo das credenciais em chamadas de agente.
- Saiba como registrar e gerenciar habilidades no Agent Registry.