Descubrimiento público de agentes
Usa estos ejemplos para dar forma al JSON que otro cliente A2A obtiene antes de decidir si tu agente puede completar una tarea.
6 plantillas JSON listas para copiar · A2A v1.0
Ejemplos de A2A Agent Card
Explora plantillas prácticas de A2A v1.0, comprende sus decisiones de diseño, y luego adapta cualquier ejemplo para tu propio agente.
Envío a marketplace
Adapta el proveedor, skills, tags, capabilities, y metadatos de seguridad para que los revisores entiendan qué hace el agente y quién lo opera.
Catálogos internos de agentes
Estandariza el endpoint, autenticación, y descripciones de skills entre agentes internos antes de que los equipos los integren en flujos de trabajo.
Plantillas JSON
Agent Cards de ejemplo para agentes de soporte, reservas, compras, programación, investigación, y flujo de trabajo.
Filtro
Agente de Soporte al Cliente
Maneja preguntas sobre productos, consultas de pedidos, devoluciones, y traspasos de escalación.
Por qué está construido así
- Las credenciales de cliente OAuth 2.0 protegen los datos de pedidos: la Agent Card declara la URL del token y el scope para que los clientes puedan autenticarse sin documentación fuera de banda.
- streaming y pushNotifications son ambos true porque las conversaciones de soporte son de larga duración y las actualizaciones de resolución llegan de forma asíncrona.
- La única skill está limitada a un único límite de tarea (clasificar, resolver, escalar) en lugar de una descripción vaga de "ayudar a los clientes", para que los enrutadores puedan hacer coincidir con precisión.
{
"name": "Agente de Soporte al Cliente",
"description": "Responde preguntas de atención al cliente, recupera el contexto del pedido y deriva los problemas no resueltos a un equipo humano.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/customer-support",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Ejemplo Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "resolve-customer-support-request",
"name": "Resolver solicitud de atención al cliente",
"description": "Clasifica una solicitud de atención al cliente, recopila el contexto necesario, propone una resolución y escala cuando la confianza es baja.",
"tags": [
"support",
"orders",
"returns"
],
"examples": [
"Ayúdame a devolver mi pedido."
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/customer-support/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}Agente de Reservas
Encuentra horarios de citas disponibles y prepara confirmaciones de reserva.
Por qué está construido así
- Una clave API en una cabecera es suficiente aquí: las reservas están limitadas por inquilino pero no conllevan el problema de consentimiento de usuario delegado que OAuth resuelve.
- defaultOutputModes es solo application/json, indicando que los llamadores obtienen propuestas de reserva estructuradas en lugar de prosa.
- pushNotifications es true para que el agente pueda confirmar una reserva después de que el backend que retiene el horario se resuelva, sin que el cliente tenga que hacer polling.
{
"name": "Agente de Reservas",
"description": "Busca disponibilidad, propone opciones de reserva y prepara reservas de citas para su aprobación.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/booking",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Ejemplo Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": false,
"pushNotifications": true,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"application/json"
],
"skills": [
{
"id": "find-and-prepare-booking",
"name": "Encuentra y prepara la reserva",
"description": "Comprueba la disponibilidad de recursos, compara ventanas de reserva y devuelve una propuesta de reserva estructurada.",
"tags": [
"booking",
"calendar",
"availability"
],
"examples": [
"Encuentre una cita de 30 minutos mañana por la tarde."
]
}
],
"securitySchemes": {
"apiKey": {
"apiKeySecurityScheme": {
"location": "header",
"name": "X-API-Key"
}
}
},
"security": [
{
"apiKey": []
}
]
}Agente de Compras
Compara productos, disponibilidad, precios, y restricciones de compra.
Por qué está construido así
- Las recomendaciones clasificadas se transmiten a medida que se calculan, por lo que streaming es true mientras pushNotifications permanece false — no pasa nada después de que la respuesta se completa.
- La descripción de la skill se compromete a devolver compensaciones y justificaciones, lo que indica a los orquestadores que este agente explica las clasificaciones en lugar de solo listar productos.
- Los scopes OAuth controlan el acceso a datos relacionados con la compra; una demo pública de compras podría eliminar la seguridad por completo y seguir siendo una Agent Card válida.
{
"name": "Agente de Compras",
"description": "Compara productos con las limitaciones del usuario y devuelve opciones de compra clasificadas con compensaciones.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/shopping",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Ejemplo Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": false,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"application/json"
],
"skills": [
{
"id": "compare-shopping-options",
"name": "Compara opciones de compra",
"description": "Evalúa productos candidatos, filtra por restricciones y devuelve recomendaciones clasificadas con fundamento.",
"tags": [
"shopping",
"commerce",
"recommendations"
],
"examples": [
"Compare portátiles ligeros de menos de $1200."
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/shopping/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}Agente de Programación
Revisa tareas de código, propone parches, y explica decisiones de implementación.
Por qué está construido así
- extendedAgentCard es true: la Agent Card pública lista una skill genérica de "implementar cambio de código", mientras que las skills específicas del repositorio solo se revelan a clientes autenticados mediante GetExtendedAgentCard.
- Se declaran tanto salidas text/plain como application/json porque el agente devuelve explicaciones legibles por humanos junto con parches aplicables por máquina.
- El streaming importa para los ciclos largos de compilación y prueba; los clientes ven progreso intermedio en lugar de una llamada silenciosa de varios minutos.
{
"name": "Agente de Programación",
"description": "Ayuda con tareas de ingeniería de software analizando código, proponiendo cambios y devolviendo notas de implementación.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/coding",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Ejemplo Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": true
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "implement-code-change",
"name": "Implementar cambio de código",
"description": "Lee una solicitud de codificación, inspecciona archivos relevantes, devuelve una propuesta de parche y resume los pasos de verificación.",
"tags": [
"coding",
"review",
"patches"
],
"examples": [
"Agregue paginación a la API de los usuarios."
]
}
],
"securitySchemes": {
"apiKey": {
"apiKeySecurityScheme": {
"location": "header",
"name": "X-API-Key"
}
}
},
"security": [
{
"apiKey": []
}
]
}Agente de Investigación
Recopila fuentes, extrae evidencia, y devuelve notas de investigación estructuradas.
Por qué está construido así
- No hay securitySchemes en absoluto: el endpoint es intencionalmente público, y omitir el campo es la forma correcta de decirlo — un mapa de esquemas vacío sería ambiguo.
- La entrada es solo text/plain, porque los resúmenes de investigación comienzan con preguntas en lenguaje natural; la salida estructurada llega como notas application/json.
- Esta es la Agent Card v1.0 mínima útil: identidad, una interfaz, capabilities, modos, y una skill bien etiquetada.
{
"name": "Agente de Investigación",
"description": "Recopila material fuente, extrae evidencia y produce notas de investigación estructuradas con citas.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/research",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Ejemplo Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": false,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "prepare-research-brief",
"name": "Preparar resumen de investigación",
"description": "Busca fuentes aprobadas, extrae afirmaciones y pruebas y devuelve un resumen de investigación conciso.",
"tags": [
"research",
"evidence",
"citations"
],
"examples": [
"Prepare un informe citado sobre la política de energías renovables."
]
}
]
}Agente de Flujo de Trabajo Interno
Coordina aprobaciones, comprobaciones de estado, y actualizaciones de flujo de trabajo de back-office.
Por qué está construido así
- application/json es el único modo de entrada y salida: este agente es llamado por otros sistemas, nunca por personas escribiendo prosa.
- OAuth 2.0 más extendedAgentCard encaja con las auditorías empresariales — los equipos de seguridad pueden ver los requisitos de autenticación públicamente mientras las skills sensibles de flujo de trabajo permanecen detrás de la autenticación.
- pushNotifications es esencial porque las cadenas de aprobación toman horas o días; los webhooks reemplazan el polling para cambios de estado.
{
"name": "Agente de Flujo de Trabajo Interno",
"description": "Coordina aprobaciones internas, verifica el estado del sistema y prepara actualizaciones del flujo de trabajo para los equipos de operaciones.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/workflow",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Ejemplo Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": false,
"pushNotifications": true,
"extendedAgentCard": true
},
"defaultInputModes": [
"application/json"
],
"defaultOutputModes": [
"application/json"
],
"skills": [
{
"id": "coordinate-internal-workflow",
"name": "Coordinar el flujo de trabajo interno.",
"description": "Recibe la intención del flujo de trabajo, verifica los requisitos de las políticas, recopila aprobaciones e informa el estado final.",
"tags": [
"workflow",
"operations",
"approval"
],
"examples": [
"Solicite aprobación para implementar la actualización de nómina."
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/workflow/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}Adapta con confianza
Cómo adaptar un ejemplo de Agent Card
Cada ejemplo de Agent Card está intencionalmente completo lo suficiente como para copiarlo, pero la Agent Card no debería publicarse sin cambios. Trátala como un mapa de campos para tu propio servidor A2A: reemplaza la identidad, endpoint, proveedor, autenticación, capabilities, modos, y detalles de skills con valores de producción.
Los Agent Cards más fuertes explican el límite de la tarea del agente tanto en lenguaje simple como en metadatos legibles por máquina. Un cliente debería poder saber qué puede hacer el agente, qué no puede hacer, qué URL llamar, y si se requieren credenciales.
Antes de publicar
Reemplaza cada URL example.com con tu endpoint A2A desplegado y el sitio web del proveedor.
Reescribe el nombre de la skill, descripción, tags (requeridos en v1.0), y ejemplos para el límite de tarea real.
Establece provider.organization e incrementa la version de nivel superior cada vez que cambie el contenido de la Agent Card.
Elimina los campos de autenticación solo cuando el endpoint sea intencionalmente público.
Mantén defaultInputModes y defaultOutputModes alineados con lo que tu servidor realmente acepta y devuelve.
Valida el JSON final y publícalo en /.well-known/agent-card.json en el dominio de tu servicio.
Listo para construir
Comienza con un ejemplo, y luego hazlo tuyo.
Abre cualquier patrón en el Generador de Agent Card, revisa el JSON, y valídalo antes de publicar.