Criar sistemas multiagente e chamar agentes A2A

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:

  1. Configure o Agent Registry.
  2. 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.

  3. 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 httpx
    
  4. Configure 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 login
    
  5. Configure as seguintes variáveis de ambiente:

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID
    export GOOGLE_CLOUD_LOCATION=LOCATION
    

    Substitua:

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 formato agents/AGENT_ID, que usa o ID do projeto e o local configurado no cliente AgentRegistry, ou o nome completo do recurso no formato projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID. Quando um gerenciador de autenticação Binding existe para o agente, o get_remote_a2a_agent() configura as credenciais de solicitação automaticamente. Quando não houver Binding, transmita um httpx_client personalizado configurado com um gerenciador httpx.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 GoogleApiAuth implementa um gerenciador httpx.Auth para chamar um subagente A2A da APIGoogle Cloud (https://*.googleapis.com). Ele usa google.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çalhos Authorization e X-Goog-User-Project em cada solicitação.

  • O cliente registry recupera o subagente A2A remoto e o conjunto de ferramentas MCP remoto do Agent Registry e os transmite para LlmAgent usando os parâmetros sub_agents e tools.

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:

  1. Descoberta: autentique-se na API Agent Registry com um token de acesso do OAuth 2.0 para recuperar o recurso Agent do subagente de destino e inspecionar o Card do Agente.
  2. 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.com ou um token de ID do OIDC para Agent Endpoints do Cloud Run e do IAP. Em seguida, envie uma solicitação A2A SendMessage. A saída retorna um objeto JSON SendMessageResponse, que contém um campo task ou message no 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:

  1. Faça a autenticação no Agent Registry com um token de acesso do OAuth 2.0 e busque o recurso Agent do 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_ID pelo ID do subagente A2A registrado que você quer chamar, por exemplo, agentregistry-01234456-7890-abcd-1234-567890abcdef.

  2. 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", "")
    
  3. Prepare os cabeçalhos da solicitação com um token de acesso do OAuth 2.0 para endpoints de agente do *.googleapis.com ou 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}"
    
  4. Formate e envie a solicitação A2A SendMessage usando 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 SendMessage para a versão 1.0 de A2A. Se você precisar negociar entre as versões 1.0 e 0.3 do protocolo A2A automaticamente, use o ADK ou o cliente Python a2a-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