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:
- El agente cliente recibe la petición del usuario.
- Encuentra un agente remoto mediante su Agent Card.
- Crea una tarea y envía el contexto.
- El agente remoto llama a la API del sitio.
- 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:
| Componente | Responsabilidad |
|---|---|
| Agente cliente | Comprende la intención y elige al proveedor |
| Servidor A2A | Recibe tareas, mensajes y consultas de estado |
| Capa de herramientas | Convierte la intención en una llamada concreta |
| API del sitio | Comprueba permisos, valida datos y ejecuta la operación |
| Auditoría | Guarda un historial seguro de llamadas y resultados |
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 publiques en el Agent Card datos que faciliten un ataque o evitar la autorización - por ejemplo, claves API o tokens internos. La lista completa de lo que no debe incluirse y los campos obligatorios está en «Agent Card en A2A: ejemplo JSON completo y desglose de campos».
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:
- Cuenta de servicio - para datos compartidos y tareas en segundo plano.
- Acceso delegado del usuario - para pedidos, perfiles y datos personales.
- 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
Es un proyecto de ingeniería aparte, no una configuración puntual: el siguiente plan ayuda a limitar riesgos y costes desde el inicio.
- Elegir un caso con valor medible.
- Definir un contrato API limitado y esquemas de datos.
- Crear herramientas separadas en lugar de acceso HTTP universal.
- Añadir autenticación, límites y auditoría.
- Publicar una Agent Card con skills precisas.
- Probar errores, reintentos, cancelación y entradas maliciosas.
- Empezar en modo read-only o borrador.
- Permitir escritura solo después de revisar logs reales.
Cuándo no conviene
- Si las operaciones y los datos del negocio aún no están descritos en una API estable - primero hay que poner orden ahí, no conectar un agente sobre el caos.
- Si el volumen de solicitudes rutinarias es pequeño y una sola persona lo gestiona bien - crear herramientas limitadas, permisos y auditoría puede no compensar.
- Si las operaciones implican pagos o datos personales y el equipo no ha definido antes confirmaciones y límites de permisos - empezar en modo solo lectura o posponer la implementación.
- Si nadie va a mantener la integración después del lanzamiento - actualizar esquemas, revisar logs y permisos - mejor quedarse en solo lectura y recurrir a consultas puntuales con un desarrollador en vez de abrir la escritura.
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.
Si necesita ayuda con el desarrollo, la implementación de IA o el soporte del sitio para su proyecto - escríbame.
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.
Términos del artículo
A2A — Agent-to-Agent — protocolo de interacción entre agentes de IA
endpoint — specific API URL that accepts requests — URL concreta de API que acepta peticiones
idempotency — repeating a request does not change the outcome again — repetir una petición no cambia el resultado otra vez
webhook — HTTP callback when an event happens — llamada HTTP cuando ocurre un evento
stack trace — call stack dump shown when an error occurs — volcado de la pila de llamadas al fallar