¿Qué es una Agent Card en el protocolo A2A?

En el protocolo A2A (Agent2Agent), un agente de IA encarga tareas a otro. Antes de encargar nada, tiene que saber qué sabe hacer el otro, dónde escucha y cómo hay que identificarse, y eso es lo que contiene la Agent Card. La documentación del protocolo la llama la tarjeta de visita digital de un agente.⁠^{[1]A2A Protocol, Linux Foundation. Agent Discovery in A2A} No es una tarjeta de pago ni una credencial para que un agente compre: no lleva dinero ni autoriza nada. En el comercio agéntico, a una tienda le importa porque es lo primero que lee un agente ajeno: si tu plataforma o tu proveedor publican un agente A2A en tu nombre, o tu perfil de UCP (Universal Commerce Protocol) declara el transporte A2A, la dirección que aparece es la de una Agent Card.⁠^{[2]Universal Commerce Protocol. UCP Specification Overview (versión 2026-08-25)}

Qué incluye

La especificación 1.0.0 la define como un manifiesto que el propio agente publica sobre sí mismo, con su identidad, sus capacidades, sus habilidades, las formas de comunicarse que admite y sus requisitos de seguridad.⁠^{[3]A2A Protocol, Linux Foundation. Agent2Agent (A2A) Protocol Specification (versión 1.0.0)} Estos son sus campos:

Las interfaces van en orden. La primera de supportedInterfaces es la preferida, y el cliente tiene que elegir la primera que sepa usar y llamar a la dirección declarada para ese transporte.⁠^{[3]A2A Protocol, Linux Foundation. Agent2Agent (A2A) Protocol Specification (versión 1.0.0)} En la versión 1.0 los enlaces de protocolo posibles son JSON-RPC, gRPC y HTTP con JSON, y cada interfaz lleva su protocolVersion.⁠^{[3]A2A Protocol, Linux Foundation. Agent2Agent (A2A) Protocol Specification (versión 1.0.0)}

Las habilidades son la parte que se lee. Cada habilidad lleva un identificador, un nombre, una descripción y etiquetas, todos obligatorios, y puede llevar ejemplos de peticiones, sus propios tipos de entrada y salida y sus propios requisitos de seguridad. La especificación las describe como algo sobre todo descriptivo: el conjunto de cosas que el agente probablemente hará bien.⁠^{[3]A2A Protocol, Linux Foundation. Agent2Agent (A2A) Protocol Specification (versión 1.0.0)} No es un contrato de entradas y salidas como el de una herramienta MCP (Model Context Protocol), y por eso la documentación de A2A solo ve encaje entre las dos cuando la habilidad está bien definida y se puede llamar sin estado.⁠^{[4]A2A Protocol, Linux Foundation. A2A and MCP: Complementary Protocols for Agentic Systems}

Cómo se encuentra, se firma y se mantiene

Tres formas de encontrarla. En la dirección conocida https://{dominio}/.well-known/agent-card.json, en un catálogo de agentes o por configuración directa.⁠^{[3]A2A Protocol, Linux Foundation. Agent2Agent (A2A) Protocol Specification (versión 1.0.0)} La primera sigue la convención del directorio .well-known y la especificación incluye su registro como URI conocida, con el sufijo agent-card.json.⁠^{[3]A2A Protocol, Linux Foundation. Agent2Agent (A2A) Protocol Specification (versión 1.0.0)} La segunda depende de quien mantenga el catálogo, porque la especificación no fija una API estándar para esos catálogos.⁠^{[1]A2A Protocol, Linux Foundation. Agent Discovery in A2A}

La firma. Una Agent Card puede firmarse con JWS (JSON Web Signature) para que el cliente compruebe que no la han alterado y que viene de quien dice. Antes de firmar, el JSON se pone en forma canónica con el esquema JCS, para que cualquier implementación calcule la misma firma, y el cliente debería verificar al menos una firma antes de fiarse de la tarjeta.⁠^{[3]A2A Protocol, Linux Foundation. Agent2Agent (A2A) Protocol Specification (versión 1.0.0)}

La versión ampliada. Si la tarjeta pública declara capabilities.extendedAgentCard, el agente ofrece una segunda versión, solo para clientes autenticados con uno de los esquemas que declara la pública. Esa versión puede incluir habilidades que la pública no enseña, límites de uso o configuración propia de cada cliente.⁠^{[3]A2A Protocol, Linux Foundation. Agent2Agent (A2A) Protocol Specification (versión 1.0.0)}

La caché. Una tarjeta cambia poco y se pide mucho, así que la especificación pide al servidor una cabecera Cache-Control con su max-age y un ETag sacado de la versión o de un resumen del contenido, y al cliente, peticiones condicionales cuando la copia guardada caduca.⁠^{[3]A2A Protocol, Linux Foundation. Agent2Agent (A2A) Protocol Specification (versión 1.0.0)}

En una tienda

Así responde el servidor de una tienda cuando un agente pide su tarjeta, con las cabeceras de caché que recomienda la especificación.⁠^{[3]A2A Protocol, Linux Foundation. Agent2Agent (A2A) Protocol Specification (versión 1.0.0)} Es un ejemplo ficticio: el dominio, la versión y la habilidad están inventados, y la tarjeta está recortada.

GET /.well-known/agent-card.json HTTP/1.1
Host: mochilasnorte.example

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=3600
ETag: "1.4.0"

{
  "name": "Agente de pedidos de Mochilas Norte",
  "description": "Consulta el estado de un pedido y los plazos de envío.",
  "version": "1.4.0",
  "supportedInterfaces": [
    { "url": "https://mochilasnorte.example/a2a/v1", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }
  ],
  "capabilities": { "streaming": false, "extendedAgentCard": true },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain", "application/json"],
  "skills": [
    {
      "id": "estado-pedido",
      "name": "Estado de un pedido",
      "description": "Dice en qué punto está un pedido y cuándo llegará.",
      "tags": ["pedidos", "envíos"],
      "examples": ["¿Cuándo llega el pedido 10482?"]
    }
  ]
}

Un agente de compras que lea esto sabe tres cosas: que puede preguntar por pedidos en texto, a qué dirección y con qué versión del protocolo; que la tienda tiene una tarjeta ampliada, así que hay más habilidades para quien se autentique; y que no hace falta volver a pedir la tarjeta en una hora. La tarjeta de ejemplo completa, con su catálogo, está en la entrada sobre A2A.

Cómo comprobarlo

1. Pide la tarjeta. https://{dominio}/.well-known/agent-card.json tiene que devolver un objeto AgentCard.⁠^{[3]A2A Protocol, Linux Foundation. Agent2Agent (A2A) Protocol Specification (versión 1.0.0)}
2. Repasa los campos obligatorios de la tabla de arriba y la protocolVersion de cada interfaz; la vigente es la 1.0.⁠^{[3]A2A Protocol, Linux Foundation. Agent2Agent (A2A) Protocol Specification (versión 1.0.0)}
3. Si lleva signatures, verifica una: la clave pública se obtiene con los datos kid y jku de la firma, por HTTPS, y una clave caducada o revocada no sirve.⁠^{[3]A2A Protocol, Linux Foundation. Agent2Agent (A2A) Protocol Specification (versión 1.0.0)}
4. Mira las cabeceras de la respuesta: un Cache-Control con max-age y un ETag dicen que el servidor sigue la recomendación de caché.⁠^{[3]A2A Protocol, Linux Foundation. Agent2Agent (A2A) Protocol Specification (versión 1.0.0)}
5. Busca lo que no debería estar: secretos, direcciones internas o habilidades que solo deberían ver clientes autenticados.⁠^{[1]A2A Protocol, Linux Foundation. Agent Discovery in A2A}

Concepto cercano: perfil UCP

El perfil UCP es el documento que publica un comercio en /.well-known/ucp para decir qué servicios y capacidades de compra ofrece y por qué transportes: REST, MCP, A2A o una experiencia integrada.⁠^{[2]Universal Commerce Protocol. UCP Specification Overview (versión 2026-08-25)} La Agent Card describe un agente y cómo hablar con él por A2A; el perfil UCP describe un comercio y todas las vías por las que se puede comprar en él. Se tocan en un punto: cuando el perfil declara el transporte a2a, su dirección es la URL de la Agent Card del agente del comercio.⁠^{[2]Universal Commerce Protocol. UCP Specification Overview (versión 2026-08-25)} Un agente que compra puede llegar a la tarjeta por el perfil, o directamente.

Para seguir, la ruta de lectura de comercio agéntico ordena el resto de protocolos, y la entrada sobre la pasarela de protocolos explica qué pasa cuando un agente A2A tiene que hablar con quien solo entiende MCP.