La semana pasada documenté cómo implementé agent-permissions.json en este blog. Ese archivo responde la pregunta qué puede hacer un agente aquí. Pero no responde la pregunta cómo hacerlo.
Un agente sabe que tiene permiso de usar mi generador de llms.txt. Pero ¿cómo descubre el endpoint? ¿Qué parámetros necesita? ¿En qué formato recibe la respuesta? ¿Qué pasa si hay un error?
agents.json es una especificación abierta, construida sobre OpenAPI, que responde exactamente esas preguntas. Es un contrato formal que describe cómo un agente de IA puede interactuar con los servicios de un sitio web. No es un reemplazo de agent-permissions.json. Es su complemento natural.
Qué es agents.json
agents.json es una especificación creada por Wildcard AI que extiende OpenAPI para describir contratos de interacción entre APIs y agentes de IA. La diferencia fundamental con una especificación OpenAPI estándar es que agents.json está diseñado para ser consumido por LLMs, no por desarrolladores humanos.
Una especificación OpenAPI describe endpoints, métodos HTTP, parámetros y respuestas para que un developer construya una integración. agents.json describe flujos, cadenas de llamadas, vínculos entre acciones y metadatos para que un agente autónomo descubra y ejecute workflows automáticamente.
Lo que implementé para mi generador de llms.txt
Mi generador de llms.txt es una herramienta client-side. No tiene un API REST tradicional. Pero el concepto de agents.json se puede adaptar para describir la interacción con cualquier herramienta web, incluyendo formularios HTML.
{
"version": "0.1.0",
"name": "Shinobis Tools",
"description": "Free web tools for AI-ready content infrastructure",
"url": "https://shinobis.com",
"flows": [
{
"name": "generate_llms_txt",
"description": "Generate a valid llms.txt file for any website by providing its URL",
"steps": [
{
"action": "navigate",
"target": "https://shinobis.com/tools/llmstxt-generator"
},
{
"action": "set_input",
"selector": "#url-input",
"description": "Enter the target website URL",
"input_type": "url",
"required": true
},
{
"action": "click",
"selector": "button[type=submit]",
"description": "Generate the llms.txt file"
},
{
"action": "read_output",
"selector": "#output-area",
"output_format": "text/markdown"
}
]
}
]
}Este archivo describe un flujo completo: navegar a la herramienta, llenar el campo, hacer click, y leer el resultado. Un agente que lea este archivo sabe exactamente qué hacer sin necesitar instrucciones adicionales.
La diferencia con agent-permissions y agent-skills
Los tres archivos forman un sistema complementario. agent-skills dice qué herramientas existen (descubrimiento). agent-permissions dice qué acciones están permitidas (autorización). agents.json dice cómo ejecutar las acciones paso a paso (ejecución).
Es la misma lógica que un sistema de archivos: el directorio te dice qué archivos hay, los permisos te dicen si puedes leerlos o escribirlos, y la documentación te dice cómo usarlos. Los tres son necesarios.
Por qué esto importa para un blog
La mayoría de blogs no tiene herramientas interactivas. Pero los que sí tienen, calculadoras, generadores, comparadores, están en una posición única. Son sitios de contenido que también ofrecen funcionalidad. Y esa funcionalidad puede ser consumida por agentes si está correctamente descrita.
El stack de cinco capas que construí se extiende con agents.json a seis. Identidad, accesibilidad, descubrimiento, permisos, usabilidad semántica, y ahora contratos de ejecución.
No conozco otro blog personal que tenga las seis capas implementadas. La especificación es joven, la adopción es mínima, y los agentes comerciales aún no la implementan oficialmente. Pero la dirección es inequívoca: la web está evolucionando de un medio de lectura a un medio de ejecución. Y los sitios que estén preparados van a capturar una categoría de tráfico que hoy no existe.
La especificación completa está en el repositorio de Wildcard AI.
