ard.json

El Descubrimiento de recursos con agentes (ARD) es una especificación para catalogar recursos de agentes. El manifiesto ard.json describe los recursos de agentes en un dominio, como los servidores de MCP, los agentes A2A y las habilidades de los agentes, para que los agentes de IA y los registros puedan encontrarlos.

Cómo funciona la auditoría de Lighthouse

Proceso de descubrimiento: La auditoría busca el manifiesto según los mecanismos de descubrimiento en la especificación de ARD (§5.1):

  • Verifica si hay una directiva Agentmap: dentro de robots.txt.
  • Analizando el código HTML en busca de etiquetas <link rel="ard" href="...">
  • Inspecciona una respuesta de encabezado HTTP Link: <...>; rel="ard".
  • Recuperando del extremo conocido /.well-known/ard.json.

Si el descubrimiento principal falla, Lighthouse verifica las rutas heredadas (como rel="ai-catalog" o /.well-known/ai-catalog.json). Si bien el contenido que se encuentra aquí se sigue validando, se genera una advertencia porque los clientes de ARD estándar no están obligados a admitir rutas obsoletas.

Reglas de validación: La verificación se realiza con un puerto de JavaScript del paquete de cumplimiento de ARD v0.91, que prueba los siguientes criterios:

Errores de conformidad y validación:

  • Sintaxis y esquema: El manifiesto es un JSON válido y coincide con el esquema del manifiesto de ARD, y cada entrada coincide con el esquema de entrada de ARD. Lighthouse no recupera ni valida el artefacto al que apunta una entrada (por ejemplo, la tarjeta del servidor de MCP en url).
  • Campos obligatorios: El manifiesto contiene un array entries, y cada entrada contiene un identifier, displayName y type.
  • URN vinculados al dominio: Cada identifier sigue el formato urn:air:<publisher>:<namespace>:<name>.
  • Definición de la ubicación: Cada entrada define exactamente uno de los url o data intercalados, nunca ambos ni ninguno.
  • Estructura del manifiesto de confianza: Cuando se incluye un trustManifest, es un objeto con una propiedad identity.

Advertencias sobre prácticas recomendadas:

  • Consultas representativas: Cada entrada tiene un array representativeQueries con entre 2 y 5 consultas de ejemplo. Los registros compilan su índice de búsqueda a partir de estos, por lo que una entrada sin ellos no aparecerá en los resultados de la búsqueda. (Si está presente, debe ser un array de cadenas; cualquier otro valor es un error).
  • Tipo de medio: type debe ser un tipo de medio bien formado. Lighthouse advierte sobre los tipos obsoletos (por ejemplo, application/mcp-server+json a application/mcp-server-card+json), los tipos estándar con parámetros faltantes o adicionales, y los tipos no reconocidos fuera de application/*. Se permiten los tipos de application/* personalizados.
  • Colecciones: Marca un campo collections de nivel superior. Ya no forma parte de ARD y se ignora; en su lugar, modela jerarquías dentro de entries.
  • Manifiestos heredados: Marca los manifiestos que solo se encuentran en las ubicaciones heredadas de ai-catalog.
  • Ubicaciones anunciadas dañadas: Marca cualquier ubicación anunciada (vínculo Agentmap:, rel="ard" o rel="ai-catalog", o encabezado Link) que no se haya podido cargar cuando se encontró el manifiesto en otro lugar.

No es obligatorio:

  • specVersion y otros campos adicionales de nivel superior no afectan la puntuación.
  • Los capabilities son opcionales y no se califican. Si tu recurso expone herramientas o habilidades con nombre, considera incluirlas en una lista (por ejemplo, ["WeatherTool", "ForecastTool"]) para que los registros puedan filtrarlas sin recuperar el artefacto completo. Si se incluye, debe ser un array de cadenas.

Cómo leer la tabla de resultados

En la columna Element, se muestra Root para los problemas con el manifiesto en su totalidad. En el caso de problemas con una entrada, se muestra el displayName de la entrada, que recurre a su identifier o Entry #n si ninguno está disponible. Un solo problema de esquema puede aparecer dos veces, una en Root y otra en la entrada, lo que coincide con el resultado de la prueba de conformidad oficial.

Comprende tu puntuación

Los resultados de la auditoría se reflejan de las siguientes maneras:

  • Aprobado (1): Se encontró el manifiesto y no tiene errores ni advertencias.
  • Crédito parcial (0.9): El manifiesto es válido, pero tiene al menos una advertencia de práctica recomendada.
  • Falla (0): Cualquier error de conformidad, como un JSON con formato incorrecto, un incumplimiento de esquema, un URN no válido, o ambos o ninguno de url/data. La auditoría también falla si se anunció un manifiesto (a través de robots.txt, un vínculo rel="ard" o rel="ai-catalog", o un encabezado Link), pero no se pudo cargar.
  • No aplicable: No se encontró ningún manifiesto con ningún método. Esto no afecta tu puntuación de Lighthouse.

Cómo corregirlo

Para aprobar la auditoría, sigue estos pasos prácticos:

  1. Entrega tu manifiesto en /.well-known/ard.json o vincúlalo con rel=ard. Si usas ai-catalog.json o rel=ai-catalog, cambia a los nombres nuevos.
  2. Corrige los errores que se indican en la tabla de auditoría para que el manifiesto coincida con el esquema de ARD.
  3. Asigna a cada entrada un identificador urn:air:... y exactamente uno de url o data.
  4. Usa un tipo de medio de ARD estándar en type cuando corresponda.
  5. Agrega entre 2 y 5 representativeQueries a cada entrada para obtener una puntuación perfecta.