A2A (Agent-to-Agent)

A2A (Agent2Agent) es un protocolo abierto que permite que una plataforma de agentes llame a agentes alojados en otra. Se puede acceder a cualquier agente de VirtuAI mediante A2A. Quien llama encuentra el agente a través de su Agent Card y, luego, le envía mensajes con un token de OAuth 2.0 que tú controlas.

Usa A2A para agregar un agente de VirtuAI a Gemini Enterprise o para llamarlo desde tus propios servicios.

Qué admite VirtuAI


Versiones del protocolo	A2A 1.0 y 0.3, en el mismo extremo
Transporte	JSON-RPC 2.0 mediante HTTPS, con transmisión
Entrada y salida	Texto
Notificaciones push	No se admiten
Autenticación	Código de autorización de OAuth 2.0 (con PKCE opcional), credenciales de cliente y token de actualización
Alcance	`a2a:invoke`: enviar mensajes al agente y leer sus tareas

Las dos URLs

En la sección Integration URLs del agente, encontrarás lo siguiente:

Elemento	URL	Necesita un token
A2A Agent Card	`https://<your-virtuai-host>/a2a/<agent-id>/.well-known/agent-card.json`	No
A2A Endpoint (JSON-RPC)	`https://<your-virtuai-host>/a2a/<agent-id>`	Sí

La Agent Card es pública a propósito: quienes llaman la leen antes de autenticarse. Describe el nombre, la descripción y las habilidades del agente, y dónde obtener un token. Por sí sola, nunca otorga acceso.

La mayoría de las plataformas piden la URL de la tarjeta. Algunas piden el extremo.

1. Crea un cliente A2A

Cada servicio que llama a tus agentes tiene su propio cliente.

Abre Settings y busca A2A Clients.
Ingresa el nombre del servicio consumidor, por ejemplo, Gemini Enterprise, y selecciona Create client.
Copia el Client ID, el Client secret, la Token URL y los Scopes. Luego, selecciona I’ve copied the secret.

Un cliente creado aquí puede llamar a todos los agentes del espacio de trabajo. Sus redireccionamientos de inicio de sesión se limitan a las direcciones de redireccionamiento de Gemini Enterprise.

2. Registra el agente en la otra plataforma

Proporciona lo siguiente al servicio consumidor:

Campo	Valor
URL de la Agent Card	La URL de la A2A Agent Card del agente
URL de autorización	`https://<your-virtuai-host>/a2a/oauth/authorize`
URL del token	`https://<your-virtuai-host>/a2a/oauth/token`
ID y secreto del cliente	Del paso 1
Alcance	`a2a:invoke`

Para Gemini Enterprise, consulta la guía de Google para registrar un agente A2A.

Cómo se autentican quienes llaman

En nombre de una persona (código de autorización). Es lo que usa Gemini Enterprise. La primera vez que alguien usa el agente, se le redirecciona a VirtuAI para que inicie sesión. Una página Authorize access muestra qué servicio solicita el acceso y qué puede hacer. La persona selecciona Allow o Deny.

Si las herramientas del agente actúan sobre las cuentas propias de esa persona, como Gmail o Drive, la página las muestra en These agents also act on your accounts. La persona puede seleccionar Connect en cada una en ese momento o esperar hasta que el agente la necesite.

Después de que la persona permite el acceso, el agente se ejecuta como esa persona, con sus cuentas conectadas. Los tokens de acceso duran 1 hora. Los tokens de actualización duran 30 días y se reemplazan cada vez que se usan.

Como un servicio (credenciales de cliente). Un servicio de backend sin una persona detrás intercambia su ID y su secreto de cliente en la URL del token por un token de acceso de 1 hora. No necesita la URL de autorización ni PKCE.

Envía el token en cada llamada:

POST /a2a/<agent-id> HTTP/1.1
Host: <your-virtuai-host>
Authorization: Bearer <access-token>
Content-Type: application/json

Revoca el acceso

En Settings > A2A Clients, selecciona el ícono de papelera junto a un cliente y confirma. Sus tokens dejan de funcionar de inmediato, y cualquier servicio que lo use pierde el acceso.

Límites que debes tener en cuenta

Un token solo funciona con los agentes del espacio de trabajo que lo emitió.
No se aceptan archivos adjuntos. Envía texto.
El agente no puede pedirle a una persona que apruebe comandos mediante A2A, así que los ejecuta sin preguntar. Consulta Aprobaciones de comandos.

Solución de problemas

401 “Missing bearer credential” o “Invalid credential” : La llamada no tiene token, o el token venció o se revocó. Obtén uno nuevo.

403 “Credential is not authorized for this agent” : El token pertenece a un espacio de trabajo distinto del agente.

El servicio consumidor no puede completar el inicio de sesión : Su dirección de redireccionamiento no es una de las que VirtuAI permite para este cliente. Los clientes creados en Settings solo permiten las direcciones de Gemini Enterprise. Comunícate con Soporte para otras plataformas.

404 “Agent not found” : Verifica el ID del agente en la URL y que el agente esté activo.