Referencia de schema · 14 fieldsA2A v1.0
Un Agent Card es el documento JSON estandarizado que le dice a los clientes A2A quién es un agente, dónde contactarlo, qué puede hacer, y cómo se protege el acceso. Esta referencia cubre cada campo v1.0 con tipos, requisitos, ejemplos, y los errores que los validadores detectan con más frecuencia.
Cómo funciona el descubrimiento
Un cliente A2A obtiene la Agent Card desde el URI well-known, evalúa las skills, capacidades, y requisitos de seguridad contra su tarea, y luego llama a la interfaz preferida — la primera entrada en supportedInterfaces. Si capabilities.extendedAgentCard es true, los clientes autenticados pueden solicitar una Agent Card más rica a través de la operación GetExtendedAgentCard.
La especificación registra /.well-known/agent-card.json como la ubicación estándar. Los despliegues v0.x más antiguos usaban /.well-known/agent.json, por lo que nuestro validador comprueba ambos.
# Fetch a public Agent Card
GET /.well-known/agent-card.json HTTP/1.1
Host: agent.example.com
HTTP/1.1 200 OK
Content-Type: application/a2a+json
{
"name": "GeoSpatial Route Planner Agent",
"supportedInterfaces": [
{ "url": "https://georoute-agent.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
],
...
}Referencia de campos
Las marcas de requerido siguen las definiciones protobuf de v1.0 en la especificación oficial. Los enlaces de anclaje hacen que cada campo sea citable desde issues, revisiones, y salidas de CI.
Nombre legible por humanos del agente.
Se muestra en listados de marketplace e interfaces de cliente. Manténlo corto y específico — los clientes lo usan como etiqueta principal al comparar agentes candidatos.
Error común: Usar un nombre genérico como "AI Assistant" que no da a los sistemas de enrutamiento nada con qué diferenciar.
"name": "Agente de planificación de rutas geoespaciales"
Qué hace el agente y cuándo otro agente debería llamarlo.
Esta es la señal principal de texto libre tanto para integradores humanos como para enrutadores basados en LLM que deciden si tu agente encaja en una tarea. Indica el dominio de la tarea, capacidades clave, y límites.
Error común: Descripciones de una línea con menos de 20 caracteres. Los enrutadores no pueden hacer coincidir lo que no describes.
"description": "Proporciona servicios avanzados de planificación de rutas, análisis de tráfico y generación de mapas personalizados."
Lista ordenada de endpoints y bindings de protocolo. Se prefiere la primera entrada.
Nuevo en v1.0: reemplaza los antiguos campos de nivel superior url, preferredTransport, y additionalInterfaces. Cada entrada declara su propio url, protocolBinding (JSONRPC, GRPC, HTTP+JSON, o una URI de binding personalizada), protocolVersion, y una clave de enrutamiento de inquilino opcional — así un agente puede servir múltiples versiones de protocolo y transportes simultáneamente.
Error común: Declarar un binding que el servidor en realidad no sirve en esa URL — la especificación requiere que cada entrada sea precisa.
"supportedInterfaces": [
{ "url": "https://api.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
]Quién opera el agente: organización y sitio web.
Señal de confianza para marketplaces y auditorías empresariales. v1.0 renombró el campo name a organization; url es requerido dentro del objeto cuando está presente.
Error común: Seguir usando provider.name (anterior a v1.0). Los validadores que leen Agent Cards v1.0 no lo reconocerán.
"provider": {
"organization": "Ejemplo Geo Services Inc.",
"url": "https://www.examplegeoservices.com"
}La versión del propio agente, no del protocolo.
Permite a los clientes detectar cuándo una Agent Card ha cambiado materialmente y reevaluar la compatibilidad. Sigue tu propio esquema de lanzamiento, típicamente semver.
Error común: Confundir esto con la versión del protocolo A2A — eso ahora vive en cada entrada de supportedInterfaces.
"version": "1.2.0"
Enlace a documentación legible por humanos para el agente.
Da a los integradores un lugar para leer el contrato completo de la API, límites de tasa, y términos que no pertenecen a un documento de descubrimiento.
Error común: Apuntar a una página de inicio de marketing en lugar de documentación técnica.
"documentationUrl": "https://docs.example.com/agent"
Indicadores de características del protocolo: streaming, pushNotifications, extensions, extendedAgentCard.
Los clientes NO DEBEN llamar a características que no declaraste — las llamadas de streaming no declaradas devuelven errores. extendedAgentCard: true anuncia una Agent Card autenticada más rica a través de la operación GetExtendedAgentCard. v1.0 eliminó stateTransitionHistory.
Error común: Declarar streaming: true cuando el servidor no tiene endpoint de streaming. Los clientes lo llamarán y fallará.
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
}Esquemas de autenticación nombrados: clave API, autenticación HTTP, OAuth 2.0, OpenID Connect, o TLS mutuo.
Cada esquema nombrado envuelve un objeto de esquema concreto (apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme). Los clientes descubren cómo autenticarse desde aquí — las credenciales mismas siempre se obtienen fuera de banda.
Error común: Incrustar una clave API o token real en la Agent Card. Un Agent Card es un documento público.
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
}
}Qué esquemas declarados (y scopes) se requieren para llamar al agente.
Cada entrada mapea un nombre de esquema de securitySchemes a los scopes que necesita, reflejando el patrón de requisito de seguridad de OpenAPI. Omite ambos campos por completo para agentes intencionalmente públicos.
Error común: Declarar securitySchemes pero sin requisitos de security, dejando que los clientes adivinen si se aplica la autenticación.
"security": [{ "google": ["openid", "profile", "email"] }]Tipos de medios que el agente acepta en todas las skills.
Tipos MIME estándar como text/plain, application/json, o image/png. Las skills individuales pueden anular con sus propios inputModes.
Error común: Omitir el campo. Es requerido en v1.0 — los clientes lo necesitan para dar forma a las solicitudes.
"defaultInputModes": ["application/json", "text/plain"]
Tipos de medios que el agente devuelve en todas las skills.
Le dice a los llamadores si esperar prosa, JSON estructurado, imágenes, o archivos. Las skills pueden anular por skill con outputModes.
Error común: Listar solo text/plain cuando el agente en realidad devuelve artefactos estructurados.
"defaultOutputModes": ["application/json", "image/png"]
Las habilidades concretas en las que es probable que el agente tenga éxito.
Cada skill requiere id, name, description, y tags; examples, modos por skill, y seguridad por skill son opcionales. Las skills son la unidad de descubrimiento — los enrutadores hacen coincidir tareas contra ellas, así que limita cada una a un único límite de tarea.
Error común: Skills sin tags. Los tags se volvieron requeridos en v1.0 e impulsan la coincidencia a nivel de skill.
"skills": [{
"id": "route-optimizer-traffic",
"name": "Optimizador de rutas consciente del tráfico",
"description": "Calcula rutas de conducción óptimas utilizando el tráfico en tiempo real...",
"tags": ["maps", "routing", "traffic"],
"examples": ["Planifica una ruta de A a B evitando peajes."]
}]Firmas JSON Web que prueban que la Agent Card fue emitida por el proveedor.
Cada firma lleva un encabezado JWS protegido base64url y un valor de firma, calculado sobre la Agent Card canonicalizada con RFC 8785 (JCS). Los clientes DEBERÍAN verificar al menos una firma antes de confiar en una Agent Card obtenida de la web abierta.
Error común: Firmar la tarjeta y luego editar cualquier campo — incluso cambios de valor insignificantes en espacios en blanco invalidan el JWS.
"signatures": [{
"protected": "eyJhbGciOiJFUzI1NiIs...",
"signature": "QFdkNLNszlGj3z3u0YQ..."
}]URL a un icono que representa al agente.
Usado por catálogos e interfaces de cliente. Sírvelo a través de HTTPS desde una ubicación estable.
Error común: Enlazar un icono en un dominio diferente y no confiable que puede cambiar sin previo aviso bajo tu listado.
"iconUrl": "https://agent.example.com/icon.png"
Migración de versión
Si tu Agent Card todavía tiene un url o preferredTransport de nivel superior, es anterior a v1.0. El validador marca cada uno de estos automáticamente.
| Campo v0.x | Reemplazo v1.0 | Por qué cambió |
|---|---|---|
| url | supportedInterfaces[0].url | El endpoint preferido es ahora simplemente la primera entrada de interfaz. |
| preferredTransport | supportedInterfaces[] ordering | La preferencia se expresa mediante el orden del array en lugar de un campo separado. |
| additionalInterfaces | supportedInterfaces[] | Todas las interfaces viven en un único array ordenado. |
| protocolVersion (top level) | supportedInterfaces[].protocolVersion | Cada interfaz declara su propia versión de protocolo, habilitando soporte multi-versión. |
| supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard | Se movió al objeto capabilities; el RPC se renombró a GetExtendedAgentCard. |
| provider.name | provider.organization | Renombrado por claridad. |
| capabilities.stateTransitionHistory | — removed | No es parte de v1.0; modela el comportamiento equivalente como una extensión si es necesario. |
Código base
Coloca estas interfaces en un cliente, servidor, o comprobación de CI para analizar y producir Agent Cards con seguridad de tipos. Reflejan las definiciones protobuf en el repositorio oficial de la especificación, en la forma JSON camelCase en que se publican las Agent Cards.
¿Construyendo una Agent Card a mano en su lugar? El generador produce exactamente esta forma.
// A2A v1.0 Agent Card — TypeScript definitions
export interface AgentCard {
name: string
description: string
supportedInterfaces: AgentInterface[]
provider?: AgentProvider
version: string
documentationUrl?: string
capabilities: AgentCapabilities
securitySchemes?: Record<string, SecurityScheme>
security?: Record<string, string[]>[]
defaultInputModes: string[]
defaultOutputModes: string[]
skills: AgentSkill[]
signatures?: AgentCardSignature[]
iconUrl?: string
}
export interface AgentInterface {
url: string
protocolBinding: 'JSONRPC' | 'GRPC' | 'HTTP+JSON' | (string & {})
protocolVersion: string
tenant?: string
}
export interface AgentProvider {
organization: string
url: string
}
export interface AgentCapabilities {
streaming?: boolean
pushNotifications?: boolean
extensions?: AgentExtension[]
extendedAgentCard?: boolean
}
export interface AgentExtension {
uri: string
description?: string
required?: boolean
params?: Record<string, unknown>
}
export interface AgentSkill {
id: string
name: string
description: string
tags: string[]
examples?: string[]
inputModes?: string[]
outputModes?: string[]
}
export interface AgentCardSignature {
protected: string
signature: string
header?: Record<string, unknown>
}
export type SecurityScheme =
| { apiKeySecurityScheme: { location: 'header' | 'query' | 'cookie'; name: string; description?: string } }
| { httpAuthSecurityScheme: { scheme: string; bearerFormat?: string; description?: string } }
| { oauth2SecurityScheme: { flows: Record<string, unknown>; oauth2MetadataUrl?: string; description?: string } }
| { openIdConnectSecurityScheme: { openIdConnectUrl: string; description?: string } }
| { mtlsSecurityScheme: Record<string, never> }Integridad
Debido a que los Agent Cards se obtienen de la web abierta, v1.0 formaliza la firma: la Agent Card (menos el campo signatures y valores predeterminados) se canonicaliza con RFC 8785 JSON Canonicalization, y luego se firma como un JWS. Los clientes deberían verificar al menos una firma — a través del encabezado kid/jku o un almacén de claves confiable — antes de actuar sobre una Agent Card. Múltiples firmas soportan la rotación de claves.
Sirve la Agent Card en /.well-known/agent-card.json a través de HTTPS.
Cada entrada de supportedInterfaces es alcanzable y habla el binding declarado.
Las skills tienen los tags requeridos más descripciones con límites de tarea claros.
Las capabilities declaradas coinciden con el servidor — las características no declaradas deben devolver errores, las declaradas deben funcionar.
securitySchemes describe cómo autenticarse; no aparecen credenciales en ninguna parte de la Agent Card.
version se incrementa cada vez que cambia el contenido de la Agent Card.
Un agente de soporte al cliente con OAuth 2.0, streaming, y notificaciones push — todos los campos requeridos presentes. Más patrones viven en la biblioteca de ejemplos.
{
"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"
]
}
]
}Preguntas frecuentes
Los cambios de versión, campos de descubrimiento, y detalles de publicación que deciden si una Agent Card pasa la revisión.
v1.0 consolidó url, preferredTransport, y additionalInterfaces en un único array ordenado supportedInterfaces donde cada entrada declara su propio url, protocolBinding, y protocolVersion. supportsAuthenticatedExtendedCard se movió a capabilities.extendedAgentCard, provider.name se convirtió en provider.organization, los tags de skill se volvieron requeridos, y las firmas de Agent Card JWS se formalizaron con canonicalización RFC 8785.
No. Un Agent Card es un documento de descubrimiento para un agente. Resume identidad, interfaces, capabilities, skills, modos, proveedor, y metadatos de seguridad, mientras que un schema de API completo describe formas detalladas de solicitud y respuesta. Juega el papel que un README o resumen de OpenAPI juega para un servicio: suficiente para decidir si y cómo llamarlo.
name, description, supportedInterfaces, skills (con tags), defaultInputModes, defaultOutputModes, capabilities, provider, y metadatos de seguridad. Los sistemas de enrutamiento hacen coincidir tareas contra tu description y tags de skill, luego usan interfaces y capabilities para planificar la llamada real.
Publica solo skills que sean seguras para descubrimiento no autenticado. Si se necesita una Agent Card privada más rica, establece capabilities.extendedAgentCard en true y expón skills sensibles a través de la operación autenticada GetExtendedAgentCard.
En el URI well-known https://{tu-dominio}/.well-known/agent-card.json, servido con el tipo de contenido application/a2a+json (application/json también funciona en la práctica). Implementaciones anteriores usaban /.well-known/agent.json, así que publicar ambos durante la transición es una elección pragmática.
Pon el schema a trabajar
Genera una Agent Card con forma v1.0 a partir de los detalles de tu servicio, o pega una Agent Card existente en el validador para ver exactamente qué campos necesitan atención.