ai-catalog.json: qué es y su relación con ARD
Autor: Redacción Domeny.ForSale Publicado Actualizado
En breve: /.well-known/ai-catalog.json es la antigua ruta de publicación del manifiesto de recursos para agentes AI, descrita como predecesora de /.well-known/ard.json en la especificación Agentic Resource Discovery (ARD). Este manifiesto presenta las herramientas, los agentes o las instrucciones de uso disponibles en un formato JSON estructurado. En una implementación nueva se debe utilizar la ruta ard.json y el enlace HTML rel="ard".
Este artículo se basa en la especificación ARD v0.91 del 26 de agosto de 2026, marcada como Proposal, es decir, una propuesta. El estado de la documentación se comprobó el 3 de octubre de 2026.
¿Para qué sirve un catálogo de recursos para agentes?
Un asistente que necesita una herramienta externa debe averiguar primero qué hace y dónde encontrar su descripción. El manifiesto permite al editor presentar esa información con una estructura común. Las entradas pueden apuntar, entre otras cosas, a la descripción de un servidor MCP, a una ficha de agente A2A o a un archivo con instrucciones para ejecutar una tarea, denominado skill.
En ARD, publicar el manifiesto constituye la parte estática del descubrimiento de recursos. El registro cumple una función distinta: obtiene las entradas, las indexa y permite buscarlas. Así, el cliente puede consultar una necesidad concreta y recibir recursos adecuados. El archivo JSON no ejecuta por sí mismo las herramientas; el protocolo o las instrucciones correspondientes determinan cómo se ejecutan. Estas capas se describen en los capítulos 3 y 5 de la especificación .
¿Por qué se utiliza ahora ard.json?
En el apartado 5.1 , la especificación establece reglas claras para localizar los manifiestos:
| Mecanismo | Nombre actual | Nombre anterior |
|---|---|---|
| Archivo en el dominio | /.well-known/ard.json | /.well-known/ai-catalog.json |
| Enlace en HTML | rel="ard" | rel="ai-catalog" |
| Compatibilidad del cliente ARD | Obligatoria al descubrir entradas del dominio | Compatibilidad retroactiva opcional |
Un cliente conforme con la especificación que descubre recursos de un dominio debe obtener /.well-known/ard.json y respetar el enlace rel="ard". También puede comprobar la ruta anterior y la relación ai-catalog; si lo hace, las trata como fuentes equivalentes de entradas.
Esto significa que un cliente ARD que funcione correctamente puede pasar por alto un sitio que solo publique ai-catalog.json. La especificación recomienda migrar a ard.json. Mantener la dirección antigua junto a la nueva sigue siendo una opción para las integraciones anteriores, no un requisito de una implementación nueva.
¿Cómo es un manifiesto válido?
El documento contiene un array entries con las descripciones de los distintos recursos. El siguiente ejemplo es una versión abreviada del
manifiesto de Domeny.ForSale
:
{
"entries": [
{
"identifier": "urn:air:domeny.forsale:skill:domain-catalog-search",
"displayName": "Buscador del catálogo de Domeny.ForSale",
"type": "text/markdown; profile=\"urn:air:agent-skills\"",
"url": "https://domeny.forsale/.well-known/agent-skills/domain-catalog-search/SKILL.md",
"capabilities": ["searchDomainCatalog"],
"representativeQueries": [
"encuentra un dominio en venta para una tienda online",
"muestra artículos sobre cómo elegir y comprar un dominio"
]
}
]
}
La entrada apunta a las
instrucciones de búsqueda en el catálogo
. Estas describen cómo utilizar la herramienta WebMCP searchDomainCatalog y, cuando no está disponible, cómo buscar en el índice JSON del sitio. Por tanto, la dirección de url lleva a un documento que explica el procedimiento.
Según los apartados 4.2 y 4.3 :
identifier,displayNameytypeson obligatorios. Definen el identificador, el nombre legible y el tipo de recurso.- La entrada debe contener exactamente uno de estos campos:
url, que apunta al documento, odata, que lo contiene directamente. representativeQueriesdebería contener entre 2 y 5 consultas de ejemplo. Estas ayudan a indexar el recurso según las necesidades del usuario. La ausencia del campo o un número distinto de ejemplos genera una advertencia de la herramienta de conformidad, no un error de validación del esquema.capabilitieses una lista opcional de nombres breves de funciones, útil para filtrar.
El manifiesto también puede contener campos adicionales de nivel superior, como host o specVersion. ARD no les asigna significado en su modelo de manifiesto. Por eso, el valor "specVersion": "1.0" que aparece en nuestro archivo no significa que la especificación actual de ARD sea la versión 1.0. La estructura se define formalmente en el
esquema de la entrada y del manifiesto
.
¿Cómo migrar de ai-catalog.json a ard.json?
La migración de un catálogo existente puede hacerse en cuatro pasos:
- Comprueba las entradas con el esquema actual de ARD, incluidos los identificadores, las direcciones de los recursos y las consultas de ejemplo.
- Publica el manifiesto en
/.well-known/ard.jsondentro de tu propio dominio. - Añade un enlace a ese documento en la sección
<head>de las páginas. - Comprueba que se puedan obtener el manifiesto y los recursos indicados, y realiza la validación. Si conservas la ruta antigua para los clientes existentes, mantén ambas versiones coherentes entre sí.
El enlace puede tener este aspecto:
<link rel="ard" href="/.well-known/ard.json" type="application/json">
La especificación ofrece una herramienta de pruebas de conformidad . Permite comprobar el manifiesto y su localización en el dominio.
¿Qué aporta publicar este archivo?
El manifiesto facilita que el software compatible con ARD identifique las capacidades del sitio. En nuestro ejemplo, describe cómo buscar dominios y artículos. Para que un recurso aparezca en los resultados de un registro concreto, ese registro debe localizar la fuente e indexarla.
Publicar el archivo no garantiza por sí solo que cualquier asistente lo admita ni que el sitio obtenga una posición más alta en Google. El efecto práctico debe comprobarse en una integración que realmente utilice ARD: si obtiene el manifiesto, reconoce la entrada y puede utilizar el recurso indicado.
Véase también: ¿Qué es ARD?
Lee también
