Agentes A2A que llaman a la API de un sitio web

Los agentes A2A permiten que un sistema de IA descubra a otro, le delegue una tarea y reciba un resultado estructurado. Cuando un agente puede llamar a la API de un sitio web, pasa a formar parte de un proceso de negocio real: comprueba existencias, crea solicitudes, calcula presupuestos, actualiza pedidos o recopila datos para informes.

• A2A - un protocolo de comunicación entre agentes
• API del sitio - un punto de acceso controlado a datos y operaciones
• Agent Card - la descripción de capacidades y datos de conexión
• Task - una tarea con estado, resultado e historial
• Principio clave - el agente llama a operaciones aprobadas, no a URLs arbitrarias

Qué es A2A

A2A, o Agent2Agent, conecta agentes independientes. Uno actúa como cliente y otro publica sus capacidades y ejecuta tareas. Pueden utilizar lenguajes, modelos e infraestructuras diferentes.

El flujo habitual es:

1. El agente cliente recibe la petición del usuario.
2. Encuentra un agente remoto mediante su Agent Card.
3. Crea una tarea y envía el contexto.
4. El agente remoto llama a la API del sitio.
5. El resultado vuelve como mensaje o artefacto.

A2A gestiona la comunicación entre agentes, mientras que la API da acceso a las funciones del sitio. Son capas complementarias, no sustitutas.

Por qué un agente necesita la API del sitio

Sin API, el agente suele limitarse al texto, la búsqueda documental o una automatización frágil de la interfaz. Una API ofrece un contrato predecible y permite actuar sin imitar clics.

Operaciones útiles:

• buscar productos, servicios y contenidos;
• calcular precios, plazos o planes;
• crear leads, solicitudes o pedidos;
• consultar pagos y entregas;
• actualizar perfiles o reservas;
• obtener resultados personalizados tras la autorización.

Por ejemplo, un agente asesor puede pedir al agente del sitio: "Busca un plan disponible para un equipo de 20 personas". El agente consulta las reglas actuales mediante la API interna y devuelve opciones estructuradas.

Arquitectura de la integración

Una solución práctica tiene cinco partes:

No conviene entregar al modelo una herramienta universal como request(url, method, body). Es mejor definir funciones limitadas:

search_products(query, filters)
calculate_quote(product_id, quantity)
create_lead(name, contact, consent)
get_order_status(order_id)

Así resulta más fácil controlar permisos, validar argumentos, probar y auditar.

Agent Card y descripción de capacidades

La Agent Card permite al cliente saber qué tareas puede resolver el agente. Normalmente incluye nombre, descripción, URL, métodos de autenticación y lista de skills.

La descripción de cada skill debe ser concreta. "Trabaja con el sitio" aporta poco. Es mejor: "Busca en el catálogo, calcula presupuestos y crea una solicitud tras la confirmación del usuario".

No publique en la Agent Card:

• claves API o tokens internos;
• direcciones privadas de servicios;
• detalles que faciliten evitar la autorización;
• operaciones no disponibles para clientes externos.

Autenticación y permisos

La conexión A2A y la llamada a la API pueden usar credenciales diferentes. El agente demuestra quién es y la API determina en nombre de quién se realiza la acción.

Tres modos habituales:

1. Cuenta de servicio - para datos compartidos y tareas en segundo plano.
2. Acceso delegado del usuario - para pedidos, perfiles y datos personales.
3. Operación confirmada - el agente prepara la acción y el usuario la aprueba antes de escribir.

Limite los permisos por endpoint, método HTTP, usuario y tipo de dato. Leer el catálogo no debe permitir modificar precios ni eliminar pedidos.

Seguridad de las llamadas

Los principales riesgos son la inyección de instrucciones, los argumentos incorrectos, las fugas de datos y la ejecución duplicada.

Medidas mínimas:

• validar la entrada con un esquema estricto;
• mantener una allowlist de operaciones;
• no incluir secretos en prompts ni mensajes A2A;
• usar idempotency keys al crear o pagar;
• limitar frecuencia y coste de llamadas;
• confirmar acciones financieras e irreversibles;
• ocultar datos personales y tokens en logs;
• devolver al agente solo los campos necesarios.

El texto de usuarios y otros agentes siempre es una entrada no confiable. Una instrucción convincente dentro de un documento nunca debe ampliar los permisos de una herramienta.

Tareas síncronas y de larga duración

Una búsqueda o cálculo suele responder de inmediato. Una importación, un informe grande o el procesamiento de un pedido puede tardar minutos. Para ello son útiles estados como submitted, working, completed, failed y canceled.

El cliente puede recibir actualizaciones por streaming, webhook o consultas de estado. Una reconexión no debe volver a ejecutar la operación de negocio.

Errores y observabilidad

El agente necesita un resultado comprensible, no un stack trace: servicio no disponible, argumento incorrecto, acceso denegado o confirmación requerida. Los detalles internos deben quedar en logs protegidos.

Para diagnosticar, registre:

• identificadores de task, sesión y usuario;
• nombre de la herramienta;
• copia segura de los argumentos;
• código de la API y duración;
• estado de la confirmación;
• versiones del agente y del esquema.

Esto permite distinguir un error del modelo de uno de API, red o reglas de negocio.

Plan de implementación

1. Elegir un caso con valor medible.
2. Definir un contrato API limitado y esquemas de datos.
3. Crear herramientas separadas en lugar de acceso HTTP universal.
4. Añadir autenticación, límites y auditoría.
5. Publicar una Agent Card con skills precisas.
6. Probar errores, reintentos, cancelación y entradas maliciosas.
7. Empezar en modo read-only o borrador.
8. Permitir escritura solo después de revisar logs reales.

Resumen

Un agente A2A con acceso a la API del sitio puede conectar sistemas de IA externos con servicios reales del negocio. Una integración fiable se basa en herramientas limitadas, esquemas estrictos, permisos mínimos, confirmaciones y auditoría, no en libertad ilimitada para el modelo.

Si quiere conectar un agente A2A a la API de su sitio - contacte conmigo.

Preguntas frecuentes

¿En qué se diferencia A2A de una API REST normal?

Una API REST describe operaciones de una aplicación, mientras que A2A cubre la comunicación entre agentes y el ciclo de vida de las tareas. A2A puede usar REST u otro transporte, y después el agente accede a la API mediante herramientas controladas.

¿Necesito A2A si mi agente ya llama a una API?

No siempre. Para un único agente interno puede bastar una llamada directa. A2A es útil cuando agentes independientes deben descubrirse, delegar tareas e intercambiar resultados mediante un protocolo común.

¿Puedo dar al agente un cliente HTTP universal?

Técnicamente sí, pero es arriesgado en producción. Las funciones limitadas con allowlist, esquemas y permisos separados son más fáciles de proteger, probar y auditar.

¿Cómo evito crear un pedido dos veces?

Use un idempotency key y guarde la relación entre la task A2A y la operación de negocio. Una petición repetida con la misma clave debe devolver el resultado anterior, no crear otro registro.

¿Qué acciones requieren confirmación?

Deben confirmarse pagos, publicaciones, mensajes externos, cambios de datos personales y otras acciones costosas o irreversibles. Las búsquedas, la lectura de datos públicos y los borradores suelen poder automatizarse.