O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Ferramentas do protocolo A2A

O protocolo Agent-to-Agent (A2A) é um padrão de mensagens aberto que permite que agentes autônomos de IA se comuniquem e coordenem tarefas em sistemas diferentes.

No CX Agent Studio, as ferramentas do protocolo A2A permitem que seu aplicativo de agente delegue tarefas a agentes remotos externos ou que aplicativos e orquestradores externos invoquem seus agentes do CX Agent Studio usando mensagens padronizadas.

Como o A2A funciona

O protocolo A2A no CX Agent Studio opera usando um modelo de delegação.

Modelo de delegação

No modelo de delegação, o agente iniciador do CX Agent Studio atua como o orquestrador principal e mantém o controle geral da sessão:

Propriedade da sessão:o agente principal mantém a sessão de conversa do usuário. Quando uma subtarefa especializada é necessária, o agente principal invoca o agente remoto como uma ferramenta.
Fluxo de controle:o agente remoto processa a solicitação e retorna dados de resposta estruturados. O controle retorna imediatamente ao agente principal, que resume ou incorpora os resultados para o usuário final.
Transferência de contexto:o agente principal transmite apenas os parâmetros e o contexto da conversa necessários para a tarefa delegada.

Diagrama de sequência de delegação A2A

Comunicação baseada em texto

Toda a comunicação entre agentes no protocolo A2A é baseada em texto:

Se um usuário final interagir com um agente principal por um canal de voz (como telefonia ou WebRTC), a fala será convertida em texto primeiro.
O agente principal envia a transcrição de texto e os parâmetros para o subagente remoto em um payload de solicitação HTTP.
Streams de áudio bruto e incorporações não são transmitidos pela interface de rede A2A.

Suporte a modalidades

O suporte à modalidade (texto x voz) do protocolo A2A depende da direção da comunicação:

Agente remoto para CX Agent Studio:aceita apenas a modalidade de texto.
CX Agent Studio para agente remoto:independente da modalidade para o CX Agent Studio, ou seja, a sessão do CX Agent Studio pode usar qualquer modalidade compatível, como voz ou texto, mas o agente remoto só recebe texto.

Faturamento

Se as sessões primária e remota estiverem no CX Agent Studio e no mesmo projeto, você vai receber uma cobrança por uma sessão.

Caso contrário, para sessões principais e remotas em vários projetos ou sistemas de terceiros, você vai receber uma cobrança por duas sessões.

Autenticação e controle de acesso

Os requisitos de autenticação dependem da direção da comunicação e do serviço de destino.

Direção	Destino pretendido	Mecanismo de autenticação	Papel do IAM obrigatório	Descrição
Entrada (externa ao CX Agent Studio)	Aplicativo de agente do CX Agent Studio	Token de acesso do OAuth 2.0	`roles/ces.client`	Obrigatório para que chamadores externos invoquem o endpoint de entrada do CX Agent Studio.
Saída (do CX Agent Studio para o CX Agent Studio)	Agente do CX Agent Studio em outro projeto	Agente de serviço	`roles/ces.client`	Concedida ao agente de serviço do projeto de chamada no projeto de destino.
Saída (CX Agent Studio para Cloud Run)	Serviço do Cloud Run	Token de ID do agente de serviço	`roles/run.invoker`	Concedida ao agente de serviço do projeto de chamada no serviço do Cloud Run.
Saída (CX Agent Studio para Vertex AI)	Vertex AI Agent Engine	OAuth do agente de serviço	`roles/aiplatform.user`	Concedida ao agente de serviço do projeto de chamada no projeto de destino.
Saída (do CX Agent Studio para terceiros)	Endpoint externo (como ServiceNow ou Salesforce)	Chave de API ou OAuth	Gerenciada usando o Secret Manager	Credenciais armazenadas injetadas durante a execução da ferramenta.

Identidade do agente de serviço

As solicitações de saída do CX Agent Studio usam o agente de serviço do CX Agent Studio:

service-PROJECT_NUMBER@gcp-sa-ces.iam.gserviceaccount.com

Substitua PROJECT_NUMBER pelo número do projeto Google Cloud .

Autenticação de entrada

Quando um aplicativo externo, um agente personalizado ou um orquestrador faz uma chamada para o CX Agent Studio, ele precisa transmitir um token de acesso OAuth 2.0 válido emitido pelo Google no cabeçalho Authorization:

Teste:gere um token de acesso temporário para sua conta ativa:
```
gcloud auth print-access-token
```
Clientes programáticos:use o Application Default Credentials (ADC):
```
gcloud auth application-default print-access-token
```
Produção:use uma conta de serviço dedicada do Google com a função roles/ces.client (Customer Engagement Suite Client).

Pré-requisitos

Antes de configurar as ferramentas do protocolo A2A:

Ative a API Gemini Enterprise for Customer Experience (ces.googleapis.com) no seu projeto:
```
gcloud services enable ces.googleapis.com --project=PROJECT_ID
```
Verifique se o principal ou a conta de serviço de chamada recebeu o papel Customer Engagement Suite Client (roles/ces.client).

Configurar uma ferramenta do protocolo A2A

Para conectar seu agente principal a um agente remoto externo:

Abra o console do CX Agent Studio.
Selecione seu projeto e abra o aplicativo do agente.
No criador de agentes, clique no ícone Ferramentas.
Clique no botão + (Adicionar) para criar uma ferramenta.
Selecione o card da ferramenta Protocolo A2A.
Configure o card do agente usando o formulário da interface ou o editor JSON.
No campo URL, insira o URL do endpoint base do agente remoto (por exemplo, https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID ou o URL do serviço do Cloud Run). Não adicione /message:send ao URL. O CX Agent Studio adiciona /message:send automaticamente durante a execução.
Selecione o tipo de autenticação adequado para o endpoint.
Clique em Criar.

Exemplo de card do agente

O exemplo de JSON a seguir define um card de agente para um agente de clima remoto:

{
  "name": "weather_agent",
  "description": "Agent capable of querying weather conditions and local time for given locations.",
  "version": "0.1.0",
  "supportedInterfaces": [
    {
      "url": "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0"
    }
  ],
  "skills": [
    {
      "id": "get_weather",
      "name": "get_weather",
      "description": "Retrieves weather conditions for a specified location.",
      "tags": [
        "weather",
        "forecast"
      ],
      "examples": [],
      "inputModes": [],
      "outputModes": []
    },
    {
      "id": "get_current_time",
      "name": "get_current_time",
      "description": "Retrieves current local time for a specified city or timezone.",
      "tags": [
        "time",
        "clock"
      ],
      "examples": [],
      "inputModes": [],
      "outputModes": []
    }
  ]
}

Adicionar instruções de trajeto

Instrua seu agente principal sobre quando delegar à ferramenta A2A. Exemplo:

If the user asks for weather information or local time, use {@TOOL: weather_agent}.
Pass the city or location specified by the user.
If the tool returns an error, inform the user that weather details are temporarily unavailable.

Mensagens recebidas

Sistemas externos podem enviar mensagens diretamente para um aplicativo de agente do CX Agent Studio usando o endpoint de mensagens A2A de entrada.

URL do endpoint de entrada

Envie solicitações HTTP POST para o seguinte endpoint:

https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID/message:send

Substitua:

PROJECT_ID: o ID do projeto do Google Cloud .
LOCATION: a região que hospeda o aplicativo do seu agente (como us-central1).
APP_ID: o identificador exclusivo do aplicativo do agente do CX Agent Studio.

Esquema de payload da solicitação

A estrutura de payload JSON para enviar uma mensagem de entrada:

{
  "message": {
    "messageId": "msg-MY_UNIQUE_MESSAGE_UUID",
    "role": "ROLE_USER",
    "content": [
      {
        "text": "Hello! I would like help checking my account balance."
      }
    ],
    "metadata": {
      "gecx_a2a_agent_context": "MY_SERIALIZED_AGENT_CONTEXT_STRING"
    }
  }
}

Observação:no CX Agent Studio, a carga útil da mensagem usa o campo content para conter partes do texto da mensagem.

Exemplo de solicitação usando curl

É possível testar as mensagens recebidas usando curl:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "X-Goog-User-Project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "messageId": "msg-'"$(uuidgen)"'",
      "role": "ROLE_USER",
      "content": [
        {
          "text": "Hello!"
        }
      ]
    }
  }' \
  "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID/message:send"

Gerenciamento de contexto e estado

O protocolo A2A usa a mensagem AgentContext para gerenciar variáveis e estados de sessão entre agentes. O contexto é transmitido nos metadados do SendMessageRequest usando a chave gecx_a2a_agent_context.

Mapeamento de variáveis

Ao delegar uma tarefa, é possível mapear variáveis entre os agentes principal e remoto:

Mapeamento de saída:RemoteAgentTool.input_variable_mapping calcula o AgentContext.variables enviado ao agente remoto.
Mapeamento de entrada:RemoteAgentTool.output_variable_mapping atualiza as variáveis do agente principal quando o agente remoto responde.

Para solicitações de entrada (cliente externo para o CX Agent Studio), o aplicativo desserializa os metadados gecx_a2a_agent_context e grava o AgentContext.variables diretamente na sessão atual. As variáveis atualizadas são gravadas de volta no AgentContext.variables ao responder ao cliente.

Encerramento da sessão

O agente principal monitora AgentContext.session_metadata.closed para determinar quando uma sessão remota termina:

As solicitações de saída sempre definem closed como false. Se a resposta do agente remoto definir closed como true, a conexão A2A será encerrada.
Para respostas de entrada ao cliente, o app CX Agent Studio define closed como true se a sessão tiver terminado.

Modo com estado

As sessões remotas com apps do CXAS são sempre com estado. As sessões primárias e remotas do CXAS compartilham o mesmo ID de sessão, e as sessões remotas mantêm o histórico de conversas entre os agentes primários e remotos.

Para sessões remotas com sistemas de terceiros, as sessões remotas serão sem estado por padrão, e o agente remoto vai receber cada mensagem do agente principal como uma nova sessão (ou seja, um novo ID de contexto).

É possível ativar o campo RemoteAgentTool.stateful_agent para armazenar em cache e reutilizar automaticamente o primeiro ID de contexto retornado pelo agente remoto.

Esse ID de contexto armazenado em cache é usado durante o restante da sessão, a menos que o agente remoto responda com AgentContext.session_metadata.closed == true. Se a sessão for fechada, o cache será redefinido, e um novo ID de contexto será armazenado em cache na próxima chamada de ferramenta.

Implantar um subagente remoto

É possível implantar agentes remotos personalizados nos serviços do Google Cloud para atuarem como subagentes do CX Agent Studio.

Implantar no Cloud Run

Para hospedar um agente criado com o Kit de Desenvolvimento de Agente (ADK) no Cloud Run:

Crie um Dockerfile no diretório do projeto do agente:

FROM python:3.11-slim

WORKDIR /app

COPY pyproject.toml requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
RUN pip install --no-cache-dir "google-adk[a2a]==1.32.0" "a2a-sdk[all]==0.3.26"

COPY . .

ENV PORT=8080
ENV PYTHONUNBUFFERED=1

EXPOSE 8080

CMD ["python", "-m", "app.a2a_rest_server"]

Implantar o contêiner no Cloud Run:

gcloud run deploy my-adk-agent \
  --project=PROJECT_ID \
  --region=us-central1 \
  --source=. \
  --memory=4Gi \
  --no-cpu-throttling

Conceda o papel roles/run.invoker no serviço do Cloud Run ao agente de serviço do CX Agent Studio do projeto de chamada.
Siga as etapas em Configurar uma ferramenta de protocolo A2A para anexar o URL do serviço do Cloud Run ao CX Agent Studio.

Implantação no Vertex AI Agent Engine

Para implantar um agente do ADK no Vertex AI Agent Engine:

Defina as dependências em requirements.txt:

a2a-sdk==0.3.26
google-adk[a2a]>=1.15.0,<2.0.0

Implante o mecanismo usando o SDK da Vertex AI:

import os
import sys
from google.protobuf import json_format
import vertexai
from vertexai.agent_engines import _agent_engines

sys.path.append("./")
from app.agent_runtime_app import agent_runtime

client = vertexai.Client(project="PROJECT_ID", location="us-central1")

ops = agent_runtime.register_operations()
class_methods_proto = _agent_engines._generate_class_methods_spec_or_raise(
    agent_engine=agent_runtime,
    operations=ops
)
class_methods_list = [
    json_format.MessageToDict(cm, preserving_proto_field_name=True)
    for cm in class_methods_proto
]

agent_config = {
    "entrypoint_module": "app.agent_runtime_app",
    "entrypoint_object": "agent_runtime",
    "source_packages": ["app", "requirements.txt"],
    "requirements_file": "requirements.txt",
    "class_methods": class_methods_list,
    "agent_framework": "google-adk",
    "env_vars": {
        "GOOGLE_CLOUD_LOCATION": "us-central1",
    },
    "min_instances": 1,
    "max_instances": 10,
    "resource_limits": {"cpu": "4", "memory": "8Gi"},
}

engine = client.agent_engines.create(config=agent_config)
print(f"Deployed Engine Resource Name: {engine.api_resource.name}")

Conceda o papel roles/aiplatform.user no projeto de destino ao agente de serviço do CX Agent Studio do projeto de chamada.
Siga as etapas em Configurar uma ferramenta de protocolo A2A para anexar o endpoint do Agent Engine ao CX Agent Studio.

Conectar a endpoints de terceiros

O CX Agent Studio pode delegar tarefas a endpoints externos de terceiros, como ServiceNow ou Salesforce.

Ao configurar a ferramenta no console:

Siga as etapas em Configurar uma ferramenta de protocolo A2A.
Selecione o método de autenticação exigido pelo endpoint de terceiros, como chave de API ou OAuth.
Armazene credenciais com segurança usando o Secret Manager.

Comparação entre as ferramentas do protocolo A2A e o agente como uma ferramenta

O CX Agent Studio oferece vários métodos para coordenar fluxos de trabalho multiagente.

Recurso	Agente como ferramenta	Ferramenta do protocolo A2A
Scope	Intraaplicativo (agentes no mesmo app do CX Agent Studio).	Entre aplicativos (agentes externos, serviços remotos ou plataformas de terceiros).
Contato	Execução direta na memória / interna.	Solicitações HTTP de rede usando o padrão de mensagens A2A.
Casos de uso	Reutilizar subagentes internos sem transferir a sessão.	Chamar agentes personalizados do ADK no Cloud Run, na Vertex AI ou em APIs externas.
Protocolo	Execução de ferramentas internas da plataforma.	Payload JSON A2A padronizado em REST.

Execução de ferramentas de LLM

Internamente, as chamadas de protocolo A2A operam por meio da chamada de ferramenta padrão do LLM:

Quando uma ferramenta A2A é atribuída a um agente, a descrição da ferramenta e as definições de habilidade são fornecidas ao modelo como declarações de função.
Quando o modelo decide delegar uma subatividade, ele gera um evento de chamada de função.
O ambiente de execução do CX Agent Studio intercepta a chamada de função, traduz os parâmetros em uma solicitação HTTP A2A e a envia para o endpoint remoto configurado.
A resposta retornada pelo agente remoto é transmitida de volta ao modelo para continuar gerando a resposta da conversa.

Para saber mais sobre como os agentes são encapsulados como ferramentas chamáveis, consulte a implementação do AgentTool do ADK no GitHub.

Ferramentas do protocolo A2A Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Como o A2A funciona

Modelo de delegação

Comunicação baseada em texto

Suporte a modalidades

Faturamento

Autenticação e controle de acesso

Identidade do agente de serviço

Autenticação de entrada

Pré-requisitos

Configurar uma ferramenta do protocolo A2A

Exemplo de card do agente

Adicionar instruções de trajeto

Mensagens recebidas

URL do endpoint de entrada

Esquema de payload da solicitação

Exemplo de solicitação usando curl

Gerenciamento de contexto e estado

Mapeamento de variáveis

Encerramento da sessão

Modo com estado

Implantar um subagente remoto

Implantar no Cloud Run

Implantação no Vertex AI Agent Engine

Conectar a endpoints de terceiros

Comparação entre as ferramentas do protocolo A2A e o agente como uma ferramenta

Execução de ferramentas de LLM

Ferramentas do protocolo A2A