Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Herramientas del protocolo A2A

El protocolo Agent-to-Agent (A2A) es un estándar de mensajería abierto que permite que los agentes autónomos de IA se comuniquen y coordinen tareas en diferentes sistemas.

En CX Agent Studio, las herramientas del protocolo A2A permiten que tu aplicación de agente delegue tareas a agentes remotos externos o que las aplicaciones y los orquestadores externos invoquen a tus agentes de CX Agent Studio con mensajería estandarizada.

Cómo funciona A2A

El protocolo A2A en CX Agent Studio opera con un modelo de delegación.

Modelo de delegación

En el modelo de delegación, el agente iniciador de CX Agent Studio actúa como el organizador principal y conserva el control general de la sesión:

Propiedad de la sesión: El agente principal mantiene la sesión de conversación del usuario. Cuando se requiere una subtarea especializada, el agente principal invoca al agente remoto como una herramienta.
Flujo de control: El agente remoto procesa la solicitud y devuelve datos de respuesta estructurados. El control vuelve inmediatamente al agente principal, que resume o incorpora los resultados para el usuario final.
Transferencia de contexto: El agente principal transmite solo los parámetros y el contexto conversacional necesarios para la tarea delegada.

Diagrama de secuencia de delegación de A2A

Comunicación basada en texto

Toda la comunicación entre agentes en el protocolo A2A se basa en texto:

Si un usuario final interactúa con un agente principal a través de un canal de voz (como telefonía o WebRTC), primero se convierte el discurso en texto.
El agente principal envía la transcripción de texto y los parámetros al subagente remoto en una carga útil de solicitud HTTP.
Los flujos de audio sin procesar y las incorporaciones no se transmiten a través de la interfaz de red de A2A.

Compatibilidad con modalidades

La compatibilidad con la modalidad (texto o voz) del protocolo A2A depende de la dirección de la comunicación:

Agente remoto a CX Agent Studio: Solo admite la modalidad de texto.
CX Agent Studio al agente remoto: Es independiente de la modalidad para CX Agent Studio, lo que significa que la sesión de CX Agent Studio puede usar cualquier modalidad compatible, como voz o texto, pero el agente remoto solo recibe texto.

Facturación

Si tanto la sesión principal como la remota se encuentran en CX Agent Studio y en el mismo proyecto, se te facturará 1 sesión.

De lo contrario, se te facturarán 2 sesiones para las sesiones principales y remotas en varios proyectos o sistemas de terceros.

Autenticación y control de acceso

Los requisitos de autenticación dependen de la dirección de la comunicación y del servicio de destino.

Dirección	Destino objetivo	Mecanismo de autenticación	Rol de IAM requerido	Descripción
Entrante (externo a CX Agent Studio)	Aplicación de agente de CX Agent Studio	Token de acceso de OAuth 2.0	`roles/ces.client`	Se requiere para que los llamadores externos invoquen el endpoint entrante de CX Agent Studio.
Saliente (de CX Agent Studio a CX Agent Studio)	Agente de CX Agent Studio en otro proyecto	Agente de servicio	`roles/ces.client`	Se otorga al agente de servicio del proyecto de llamada en el proyecto de destino.
Saliente (de CX Agent Studio a Cloud Run)	Servicio de Cloud Run	Token de ID del agente de servicio	`roles/run.invoker`	Se otorga al agente de servicio del proyecto que realiza la llamada en el servicio de Cloud Run.
Saliente (de CX Agent Studio a Vertex AI)	Vertex AI Agent Engine	OAuth del agente de servicio	`roles/aiplatform.user`	Se otorga al agente de servicio del proyecto de llamada en el proyecto de destino.
Saliente (de CX Agent Studio a terceros)	Extremo externo (como ServiceNow o Salesforce)	Clave de API o OAuth	Se administra con Secret Manager	Son las credenciales almacenadas que se insertan durante la ejecución de la herramienta.

Identidad del agente de servicio

Las solicitudes salientes de CX Agent Studio usan el agente de servicio de CX Agent Studio:

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

Reemplaza PROJECT_NUMBER por el número de proyecto de Google Cloud .

Autenticación entrante

Cuando una aplicación externa, un agente personalizado o un orquestador llaman a CX Agent Studio, deben pasar un token de acceso de OAuth 2.0 válido emitido por Google en el encabezado Authorization:

Pruebas: Genera un token de acceso temporal para tu cuenta activa:
```
gcloud auth print-access-token
```
Clientes programáticos: Usa las credenciales predeterminadas de la aplicación (ADC):
```
gcloud auth application-default print-access-token
```
Producción: Usa una cuenta de servicio de Google dedicada con el rol roles/ces.client (Customer Engagement Suite Client).

Requisitos previos

Antes de configurar las herramientas del protocolo A2A, haz lo siguiente:

Habilita la API de Gemini Enterprise for Customer Experience (ces.googleapis.com) en tu proyecto:
```
gcloud services enable ces.googleapis.com --project=PROJECT_ID
```
Asegúrate de que a la principal o a la cuenta de servicio que realiza la llamada se le haya otorgado el rol Customer Engagement Suite Client (roles/ces.client).

Configura una herramienta de protocolo A2A

Para conectar tu agente principal a un agente remoto externo, haz lo siguiente:

Abre la consola de CX Agent Studio.
Selecciona tu proyecto y abre la aplicación del agente.
En el compilador de agentes, haz clic en el ícono de Herramientas.
Haz clic en el botón + (Agregar) para crear una herramienta nueva.
Selecciona la tarjeta de herramienta A2A Protocol.
Configura la tarjeta del agente con el formulario de la IU o el editor JSON.
En el campo URL, ingresa la URL del extremo base del agente remoto (por ejemplo, https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/apps/APP_ID o la URL de tu servicio de Cloud Run). No agregues /message:send a la URL, ya que CX Agent Studio lo agrega automáticamente /message:send durante el tiempo de ejecución.
Selecciona el tipo de autenticación adecuado para el extremo.
Haz clic en Crear.

Ejemplo de tarjeta de agente

En el siguiente ejemplo de JSON, se define una tarjeta de agente para un agente meteorológico 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": []
    }
  ]
}

Agrega instrucciones de ruta

Indica a tu agente principal cuándo delegar en la herramienta de A2A. Por ejemplo:

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.

Mensajería entrante

Los sistemas externos pueden enviar mensajes directamente a una aplicación de agente de CX Agent Studio a través del extremo de mensajería A2A entrante.

URL del extremo entrante

Envía solicitudes HTTP POST al siguiente extremo:

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

Reemplaza lo siguiente:

PROJECT_ID: Es el ID del proyecto de Google Cloud .
LOCATION: Es la región que aloja la aplicación del agente (como us-central1).
APP_ID: Es el identificador único de la aplicación del agente de CX Agent Studio.

Esquema de la carga útil de la solicitud

Estructura de la carga útil de JSON para enviar un mensaje entrante:

{
  "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"
    }
  }
}

Nota: En CX Agent Studio, la carga útil del mensaje usa el campo content para contener partes de texto del mensaje.

Ejemplo de solicitud con curl

Puedes probar la mensajería entrante con 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"

Administración de contexto y estado

El protocolo A2A usa el mensaje AgentContext para administrar variables y estados de sesión entre agentes. El contexto se pasa en los metadatos de SendMessageRequest con la clave gecx_a2a_agent_context.

Asignación de variables

Cuando delegas una tarea, puedes asignar variables entre los agentes principales y remotos:

Asignación de salida: RemoteAgentTool.input_variable_mapping calcula el AgentContext.variables que se envía al agente remoto.
Asignación entrante: RemoteAgentTool.output_variable_mapping actualiza las variables del agente principal cuando responde el agente remoto.

En el caso de las solicitudes entrantes (cliente externo a CX Agent Studio), la aplicación deserializa los metadatos de gecx_a2a_agent_context y escribe el AgentContext.variables directamente en la sesión actual. Las variables actualizadas se vuelven a escribir en AgentContext.variables cuando se responde al cliente.

Cierre de sesión

El agente principal supervisa AgentContext.session_metadata.closed para determinar cuándo finaliza una sesión remota:

Las solicitudes salientes siempre establecen closed en false. Si la respuesta del agente remoto establece closed en true, se cierra la conexión A2A.
En el caso de las respuestas entrantes al cliente, la app de CX Agent Studio establece closed en true si la sesión finalizó.

Modo con estado

Las sesiones remotas con apps de CXAS siempre tienen estado. Las sesiones de CXAS principales y remotas compartirán el mismo ID de sesión, y las sesiones remotas conservarán el historial de conversaciones entre los agentes principales y remotos.

En el caso de las sesiones remotas con sistemas de terceros, estas serán sin estado de forma predeterminada, y el agente remoto recibirá cada mensaje del agente principal como una sesión nueva (es decir, un ID de contexto nuevo).

Puedes habilitar el campo RemoteAgentTool.stateful_agent para almacenar en caché y reutilizar automáticamente el primer ID de contexto que devuelve el agente remoto.

Este ID de contexto almacenado en caché se usa durante el resto de la sesión, a menos que el agente remoto responda con AgentContext.session_metadata.closed == true. Si se cierra la sesión, se restablece la caché y se almacenará en caché un nuevo ID de contexto en la siguiente llamada a la herramienta.

Implementa un subagente remoto

Puedes implementar agentes remotos personalizados en Google Cloud servicios para que actúen como subagentes de CX Agent Studio.

Implementa en Cloud Run

Para alojar un agente creado con el Kit de desarrollo de agentes (ADK) en Cloud Run, haz lo siguiente:

Crea un archivo Dockerfile en el directorio de tu proyecto de 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"]

Implementar el contenedor en Cloud Run:

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

Otorga el rol roles/run.invoker en el servicio de Cloud Run al agente de servicio de CX Agent Studio de tu proyecto de llamada.
Sigue los pasos que se indican en Configura una herramienta de protocolo A2A para adjuntar la URL del servicio de Cloud Run a CX Agent Studio.

Implementación en Vertex AI Agent Engine

Para implementar un agente del ADK en Vertex AI Agent Engine, haz lo siguiente:

Define tus dependencias en requirements.txt:

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

Implementa el motor con el SDK de 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}")

Otorga el rol roles/aiplatform.user en el proyecto de destino al agente de servicio de CX Agent Studio de tu proyecto de llamada.
Sigue los pasos que se indican en Cómo configurar una herramienta de protocolo A2A para adjuntar el endpoint de Agent Engine a CX Agent Studio.

Conéctate a extremos de terceros

CX Agent Studio puede delegar tareas a extremos externos de terceros, como ServiceNow o Salesforce.

Cuando configures la herramienta en la consola, haz lo siguiente:

Sigue los pasos que se indican en Cómo configurar una herramienta de protocolo A2A.
Selecciona el método de autenticación que requiere el extremo externo (como la clave de API o OAuth).
Almacenar credenciales de forma segura con Secret Manager

Comparación de las herramientas del protocolo A2A con el agente como herramienta

CX Agent Studio proporciona varios métodos para coordinar flujos de trabajo multiagente.

Función	Agente como herramienta	Herramienta de protocolo A2A
Permiso	Dentro de la aplicación (agentes dentro de la misma app de CX Agent Studio)	Entre aplicaciones (agentes externos, servicios remotos o plataformas de terceros)
Comunicación	Ejecución interna o en memoria directa.	Solicitudes HTTP de red con el estándar de mensajería de A2A.
Casos de uso	Reutilizar subagentes internos sin transferir la sesión	Llamar a agentes personalizados del ADK en Cloud Run, Vertex AI o APIs externas
Protocolo	Ejecución de herramientas internas de la plataforma.	Es una carga útil de JSON de A2A estandarizada a través de REST.

Ejecución de herramientas de LLM

De forma interna, las llamadas al protocolo A2A operan a través de la llamada a herramientas estándar del LLM:

Cuando se asigna una herramienta de A2A a un agente, las definiciones de habilidades y la descripción de la herramienta se proporcionan al modelo como declaraciones de funciones.
Cuando el modelo decide delegar una subtarea, genera un evento de llamada a función.
El tiempo de ejecución de CX Agent Studio intercepta la llamada a la función, traduce los parámetros en una solicitud HTTP de A2A y la envía al extremo remoto configurado.
La respuesta que devuelve el agente remoto se pasa al modelo para que siga generando la respuesta de la conversación.

Para obtener más información sobre cómo se encapsulan los agentes como herramientas invocables, consulta la implementación de AgentTool del ADK en GitHub.

Herramientas del protocolo A2A Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Cómo funciona A2A

Modelo de delegación

Comunicación basada en texto

Compatibilidad con modalidades

Facturación

Autenticación y control de acceso

Identidad del agente de servicio

Autenticación entrante

Requisitos previos

Configura una herramienta de protocolo A2A

Ejemplo de tarjeta de agente

Agrega instrucciones de ruta

Mensajería entrante

URL del extremo entrante

Esquema de la carga útil de la solicitud

Ejemplo de solicitud con curl

Administración de contexto y estado

Asignación de variables

Cierre de sesión

Modo con estado

Implementa un subagente remoto

Implementa en Cloud Run

Implementación en Vertex AI Agent Engine

Conéctate a extremos de terceros

Comparación de las herramientas del protocolo A2A con el agente como herramienta

Ejecución de herramientas de LLM

Herramientas del protocolo A2A