# Qué es una Agent Card del protocolo A2A > Qué es la Agent Card de A2A: el JSON en /.well-known/agent-card.json con la identidad, las habilidades y la seguridad de un agente, y cómo se firma. URL: https://clione.ai/es/glosario/agent-card/ Lang: es En el protocolo [A2A (Agent2Agent)](/es/glosario/a2a/), un [agente de IA](/es/glosario/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**.[^a2a-discovery] 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](/es/glosario/comercio-agentico/), 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)](/es/glosario/ucp/) declara el transporte A2A, la dirección que aparece es la de una Agent Card.[^ucp-overview] ## 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.[^a2a-spec] Estos son sus campos: | Campo | Obligatorio | Qué dice | | ----------------------------------------- | ----------- | ------------------------------------------------------------------------------ | | `name`, `description` | Sí | El nombre del agente y para qué sirve, legibles por una persona | | `version` | Sí | La versión del agente, no la del protocolo | | `supportedInterfaces` | Sí | Las direcciones y los enlaces de protocolo que admite, en orden de preferencia | | `capabilities` | Sí | Si admite respuestas en directo, notificaciones o una tarjeta ampliada | | `defaultInputModes`, `defaultOutputModes` | Sí | Los tipos de contenido que acepta y que devuelve | | `skills` | Sí | Sus habilidades | | `provider` | No | La organización que lo ofrece | | `securitySchemes`, `securityRequirements` | No | Cómo hay que autenticarse | | `signatures` | No | Las firmas de la propia tarjeta | | `documentationUrl`, `iconUrl` | No | Documentación e icono | **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.[^a2a-spec] 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`.[^a2a-spec] **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**.[^a2a-spec] No es un contrato de entradas y salidas como el de una herramienta [MCP (Model Context Protocol)](/es/glosario/mcp/), 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.[^a2a-mcp] ## 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.[^a2a-spec] La primera sigue la convención del [directorio .well-known](/es/glosario/well-known/) y la especificación incluye su registro como URI conocida, con el sufijo `agent-card.json`.[^a2a-spec] La segunda depende de quien mantenga el catálogo, porque **la especificación no fija una API estándar para esos catálogos**.[^a2a-discovery] **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.[^a2a-spec] **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.[^a2a-spec] **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.[^a2a-spec] ## 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.[^a2a-spec] Es un **ejemplo ficticio**: el dominio, la versión y la habilidad están inventados, y la tarjeta está recortada. ```http 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](/es/glosario/a2a/). **La tarjeta pública no es sitio para nada interno.** La especificación pide que la Agent Card no incluya credenciales sensibles ni detalles internos de la implementación, y que se sirva por HTTPS.[^a2a-spec] La guía de descubrimiento va más allá: una tarjeta puede revelar sin querer direcciones de agentes internos o restringidos y descripciones de habilidades sensibles, y para eso recomienda la tarjeta ampliada con autenticación y credenciales dinámicas obtenidas por otro canal, nunca secretos fijos escritos en la tarjeta.[^a2a-discovery] ## Cómo comprobarlo 1. **Pide la tarjeta.** `https://{dominio}/.well-known/agent-card.json` tiene que devolver un objeto AgentCard.[^a2a-spec] 2. **Repasa los campos obligatorios** de la tabla de arriba y la `protocolVersion` de cada interfaz; la vigente es la 1.0.[^a2a-spec] 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.[^a2a-spec] 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é.[^a2a-spec] 5. **Busca lo que no debería estar**: secretos, direcciones internas o habilidades que solo deberían ver clientes autenticados.[^a2a-discovery] ## 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.[^ucp-overview] 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.[^ucp-overview] Un agente que compra puede llegar a la tarjeta por el perfil, o directamente. Para seguir, la [ruta de lectura de comercio agéntico](/es/aprender/comercio-agentico/) ordena el resto de protocolos, y la entrada sobre la [pasarela de protocolos](/es/glosario/pasarela-de-protocolos/) explica qué pasa cuando un agente A2A tiene que hablar con quien solo entiende MCP.