agents.json explicado: Haz tu web legible para ChatGPT (con código)

Matthias Meyer

Cada era de la web ha tenido sus archivos de descubrimiento. Archivos que permanecen en segundo plano y dicen a las maquinas: "Aquí estoy, esto es lo que puedo hacer." La mayoría de los operadores de sitios web conocen al menos dos de ellos. Pero muy pocos saben que esta surgiendo un tercero -- y que podría convertirse en el mas importante.

La evolución de los archivos de descubrimiento#

1994: robots.txt -- Di a los crawlers lo que pueden hacer#

User-agent: *
Disallow: /admin/
Allow: /

Simple. Efectivo. robots.txt dice a los crawlers de motores de búsqueda que partes de un sitio web pueden indexar y cuales no. Ningún webmaster en 1994 pensó que este archivo de texto seria critico algún día. Hoy, todo sitio web serio tiene uno.

2005: sitemap.xml -- Muestra a los crawlers lo que existe#

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/</loc>
    <lastmod>2026-02-15</lastmod>
    <priority>1.0</priority>
  </url>
</urlset>

robots.txt dice lo que los crawlers no deben tocar. sitemap.xml dice lo que deben encontrar. Juntos, forman la base del SEO. Google, Bing y compañía leen estos archivos antes de indexar un sitio web.

2026: agents.json -- Di a los agentes de IA lo que puedes hacer#

{
  "schema_version": "1.0",
  "name": "MiEmpresa",
  "description": "Lo que hacemos",
  "url": "https://example.com",
  "tools": [
    {
      "name": "get_services",
      "description": "Obtener todos los servicios disponibles",
      "endpoint": "/api/v1/services",
      "method": "GET",
      "parameters": {}
    }
  ]
}

agents.json va un paso mas allá que robots.txt y sitemap.xml. No solo dice "aquí estoy" o "esto puede ser indexado." Dice: "Estas son mis capacidades. Así es como interactúas conmigo. Aquí están los endpoints. Aquí los parámetros."

Es el salto de la descubribilidad pasiva a la interacción activa.

Que contiene exactamente un agents.json?#

Un archivo agents.json se aloja en /.well-known/agents.json y consta de cuatro secciones principales:

1. Meta información#

{
  "schema_version": "1.0",
  "name": "StudioMeyer",
  "description": "Premium Web Design & Development Agency...",
  "url": "https://studiomeyer.io",
  "logo": "https://studiomeyer.io/icon.png",
  "contact": {
    "email": "hello@studiomeyer.io",
    "url": "https://studiomeyer.io/de/contact"
  }
}

Nombre, descripción, URL, contacto. Nada sorprendente. Pero importante: esta información es legible por maquinas. Un agente de IA no tiene que adivinar quien esta detrás del sitio web.

2. Tools -- El núcleo#

Aquí es donde se pone interesante. Cada herramienta describe una capacidad concreta:

{
  "name": "browse_portfolio",
  "description": "Browse the portfolio by industry, style, or technology.",
  "endpoint": "/api/v1/portfolio",
  "method": "GET",
  "parameters": {
    "industry": {
      "type": "string",
      "description": "Industry of the project",
      "enum": ["immobilien", "gastronomie", "handwerk", "technologie"]
    },
    "style": {
      "type": "string",
      "description": "Desired design style",
      "enum": ["premium", "minimalistisch", "modern", "klassisch"]
    }
  }
}

Lo que el agente lee de esto:

Name: browse_portfolio -- un identificador legible por maquinas
Description: Que hace la herramienta (en lenguaje natural, para que el agente decida si la necesita)
Endpoint: A donde va la solicitud (/api/v1/portfolio)
Method: Método HTTP (GET, POST, etc.)
Parameters: Lo que el agente puede enviar, incluyendo tipo, descripción y valores posibles

Es básicamente documentación de API -- pero escrita para que un agente de IA pueda entenderla y usarla sin ayuda humana.

3. Capabilities#

{
  "capabilities": {
    "webmcp": true,
    "a2a": true,
    "a2aEndpoint": "/api/a2a",
    "languages": ["de", "en", "es"]
  }
}

Aquí se indica lo que el sitio web soporta técnicamente. WebMCP? Protocolo A2A? Que idiomas? Un agente puede verificar previamente si el sitio web es adecuado para su solicitud.

4. Interacción con agent-card.json#

Junto a agents.json, existe agent-card.json -- la contraparte para el protocolo A2A (Agent-to-Agent). Mientras agents.json describe las herramientas, agent-card.json describe las habilidades:

{
  "name": "StudioMeyer",
  "protocolVersion": "1.0",
  "skills": [
    {
      "id": "validate-webmcp",
      "name": "Validate Agent Discovery",
      "description": "Validate agents.json against WebMCP spec...",
      "tags": ["validation", "webmcp", "agents"],
      "examples": [
        "Validate agents.json for example.com",
        "Is my agents.json spec-compliant?"
      ]
    }
  ]
}

La diferencia: las herramientas son técnicas (endpoint + parámetros). Las habilidades son semánticas (que puedo hacer por ti?). Ambas juntas dan al agente el panorama completo.

Como un agente de IA usa agents.json -- paso a paso#

Tomemos un escenario concreto. Un usuario le pregunta a su asistente de IA:

"Busca una agencia de diseno web con experiencia en sitios de inmobiliarias, y pide un presupuesto para un sitio de 10 paginas."

Sin agents.json (el estándar actual)#

El agente busca "agencia diseno web inmobiliarias"
Encuentra sitios web, lee HTML
Intenta determinar a partir de textos de marketing si hay experiencia en inmobiliarias
Quizá encuentra un formulario de contacto
No puede solicitar un presupuesto automático
Le dice al usuario: "Encontré algunas agencias, aquí están los enlaces"

Resultado: El usuario tiene que seguir por su cuenta. El agente fue básicamente un motor de búsqueda mejorado.

Con agents.json#

El agente encuentra un sitio web con agents.json
Lee la lista de herramientas: browse_portfolio con filtro industry
Llama a /api/v1/portfolio?industry=immobilien
Recibe datos estructurados: proyectos con capturas, tech stack, resultados
Lee la herramienta request_quote y llama a /api/v1/quote con {projectType: "website", pages: "10"}
Recibe una estimación de precio
Presenta al usuario: "StudioMeyer tiene 3 proyectos inmobiliarios en su portfolio. Un sitio de 10 paginas cuesta aproximadamente X euros. Quieres que reserve una consulta?"

Resultado: El agente completo la tarea, no solo investigo.

Ejemplo real: agents.json de StudioMeyer#

StudioMeyer ha implementado nueve herramientas en su agents.json. Aquí un resumen de lo que un agente de IA puede hacer con ellas:

Herramienta	Que hace	Método
`browse_portfolio`	Filtrar portfolio por industria y estilo	GET
`request_quote`	Estimación de precio para un proyecto web	POST
`get_services`	Obtener todos los servicios y precios	GET
`schedule_consultation`	Reservar una cita de consultoría	POST
`get_case_study`	Obtener casos de estudio por industria	GET
`validate_webmcp`	Validar implementación de agents.json	GET
`generate_agents_json`	Generar agents.json para otras empresas	POST
`get_api_docs`	Obtener documentación de API	GET

No es un concepto teórico. Estos endpoints existen, están en producción y entregan datos reales. Un agente los descubre automáticamente hoy? En la mayoría de los casos, aun no. Pero cuando un agente consulta studiomeyer.io/.well-known/agents.json, obtiene todo lo que necesita.

La implementación técnica#

Para desarrolladores: así se ve la implementación.

Servir el archivo#

agents.json se sirve como ruta de API o archivo estático bajo /.well-known/agents.json. En Next.js, se ve así:

// app/api/well-known/agents-json/route.ts
export function GET() {
  const agentsJson = {
    schema_version: "1.0",
    name: "MiEmpresa",
    tools: [/* ... */],
    capabilities: { webmcp: true }
  };

  return NextResponse.json(agentsJson, {
    headers: {
      "Cache-Control": "public, max-age=86400",
      "Access-Control-Allow-Origin": "*"
    }
  });
}

Importante: CORS debe estar abierto. Los agentes de IA vienen de diversos orígenes. Si el agents.json no es públicamente accesible, no sirve de nada.

Construir los endpoints#

Cada herramienta en agents.json apunta a un endpoint de API real. Estos endpoints deben:

Devolver JSON estructurado (no HTML!)
Aceptar parámetros documentados
Proporcionar mensajes de error significativos
Funcionar sin autenticación (al menos para accesos de lectura)

Ahí esta el verdadero esfuerzo: no el archivo agents.json en si, sino las APIs detrás. Si ya tienes una API, solo necesitas el archivo de descubrimiento. Si no, primero debes construir los endpoints.

Lo que agents.json NO es#

Para evitar malentendidos:

No es un reemplazo del SEO. agents.json no reemplaza robots.txt, sitemap.xml o el markup de Schema.org. Los complementa. El SEO sigue siendo relevante para motores de búsqueda. agents.json es para agentes de IA.

No es un riesgo de seguridad. agents.json solo expone lo que tu elijas exponer. Sin datos internos, sin funciones de administración. Solo endpoints públicos.

No es un estándar universal. A día de hoy, no hay un estándar unificado que todos los agentes soporten. agents.json es una propuesta comunitaria, A2A un protocolo iniciado por Google, WebMCP una iniciativa del W3C Community Group. La convergencia viene, pero aun no esta aquí.

No es una garantía de trafico. Solo porque tengas agents.json no significa que manana los agentes de IA asaltaran tu sitio web. Es una inversion en el futuro, no un impulsor de trafico inmediato.

Quien debería implementar agents.json?#

No todo sitio web necesita agents.json. Siendo honestos: un blog personal o un simple sitio de tarjeta de visita gana poco con ello.

Tiene sentido para:

Proveedores de servicios con servicios reservables (consultores, agencias, medicos)
E-commerce con catálogos de productos y APIs
Empresas SaaS con APIs documentadas
Restaurantes con sistemas de reserva
Inmobiliarias con bases de datos de propiedades consultables
Cualquier empresa que quiera generar consultas online

Menos relevante para:

Sitios web puramente de contenido sin funciones interactivas
Sitios web que comunican exclusivamente a traves de formularios
Empresas sin procesos digitales

Tres pasos para tu propio agents.json#

Paso 1: Hacer inventario#

Que información y acciones ofrece tu sitio web? Lista todo:

Que datos podría obtener un agente? (Precios, portfolio, FAQ)
Que acciones podría ejecutar un agente? (Reservar cita, solicitar presupuesto)
Que APIs existentes ya tienes?

Paso 2: Construir o ampliar APIs#

Para cada capacidad identificada, necesitas un endpoint de API que devuelva JSON. Empieza con los mas simples:

/api/services -- Listar servicios
/api/contact -- Aceptar consultas de contacto
/api/faq -- Responder preguntas frecuentes

Paso 3: Crear y desplegar agents.json#

Crea el archivo en /.well-known/agents.json, lista tus herramientas y asegúrate de que los endpoints funcionen.

O -- y este es el camino pragmático -- hazlo generar. StudioMeyer ofrece exactamente esto: /api/v1/generate-agents-json acepta industria y nombre de empresa y devuelve un agents.json listo para usar.

Conclusion: El siguiente archivo de descubrimiento ha llegado#

robots.txt hizo los sitios web visibles para los crawlers. sitemap.xml estructuro el contenido. agents.json hace los sitios web interactivos para agentes de IA.

El estándar es joven. La adopción esta comenzando. Pero la evolución es clara: los sitios web que puedan hablar con maquinas tendrán ventaja sobre aquellos que solo pueden ser leídos por humanos.

La buena noticia: empezar es sorprendentemente fácil. Un archivo JSON, algunos endpoints de API, y tu sitio web habla un nuevo idioma. No el idioma de los motores de búsqueda. Sino el idioma de los agentes de IA.

Y tendrán mucho que decir en los próximos anos.