agents.json explicado: Cómo hacer tu sitio web legible para máquinas

Matthias Meyer

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

La evolucion 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 busqueda que partes de un sitio web pueden indexar y cuales no. Ningun webmaster en 1994 penso que este archivo de texto seria critico algun dia. 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 compania 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 alla que robots.txt y sitemap.xml. No solo dice "aqui estoy" o "esto puede ser indexado." Dice: "Estas son mis capacidades. Asi es como interactuas conmigo. Aqui estan los endpoints. Aqui los parametros."

Es el salto de la descubribilidad pasiva a la interaccion 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 informacion

{
  "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, descripcion, URL, contacto. Nada sorprendente. Pero importante: esta informacion es legible por maquinas. Un agente de IA no tiene que adivinar quien esta detras del sitio web.

2. Tools -- El nucleo

Aqui 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: Metodo HTTP (GET, POST, etc.)
Parameters: Lo que el agente puede enviar, incluyendo tipo, descripcion y valores posibles

Es basicamente documentacion 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"]
  }
}

Aqui se indica lo que el sitio web soporta tecnicamente. WebMCP? Protocolo A2A? Que idiomas? Un agente puede verificar previamente si el sitio web es adecuado para su solicitud.

4. Interaccion 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": "0.3.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 tecnicas (endpoint + parametros). Las habilidades son semanticas (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 estandar 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
Quiza encuentra un formulario de contacto
No puede solicitar un presupuesto automatico
Le dice al usuario: "Encontre algunas agencias, aqui estan los enlaces"

Resultado: El usuario tiene que seguir por su cuenta. El agente fue basicamente un motor de busqueda 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 estimacion 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. Aqui un resumen de lo que un agente de IA puede hacer con ellas:

Herramienta	Que hace	Metodo
`browse_portfolio`	Filtrar portfolio por industria y estilo	GET
`request_quote`	Estimacion de precio para un proyecto web	POST
`get_services`	Obtener todos los servicios y precios	GET
`schedule_consultation`	Reservar una cita de consultoria	POST
`get_case_study`	Obtener casos de estudio por industria	GET
`validate_webmcp`	Validar implementacion de agents.json	GET
`generate_agents_json`	Generar agents.json para otras empresas	POST
`get_api_docs`	Obtener documentacion de API	GET

No es un concepto teorico. Estos endpoints existen, estan en produccion y entregan datos reales. Un agente los descubre automaticamente hoy? En la mayoria de los casos, aun no. Pero cuando un agente consulta studiomeyer.io/.well-known/agents.json, obtiene todo lo que necesita.

La implementacion tecnica

Para desarrolladores: asi se ve la implementacion.

Servir el archivo

agents.json se sirve como ruta de API o archivo estatico bajo /.well-known/agents.json. En Next.js, se ve asi:

// 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 origenes. Si el agents.json no es publicamente 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 parametros documentados
Proporcionar mensajes de error significativos
Funcionar sin autenticacion (al menos para accesos de lectura)

Ahi esta el verdadero esfuerzo: no el archivo agents.json en si, sino las APIs detras. 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 busqueda. 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 administracion. Solo endpoints publicos.

No es un estandar universal. A dia de hoy, no hay un estandar 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 aqui.

No es una garantia 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 deberia 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 catalogos 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 informacion y acciones ofrece tu sitio web? Lista todo:

Que datos podria obtener un agente? (Precios, portfolio, FAQ)
Que acciones podria 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 asegurate de que los endpoints funcionen.

O -- y este es el camino pragmatico -- 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 estandar es joven. La adopcion esta comenzando. Pero la evolucion es clara: los sitios web que puedan hablar con maquinas tendran ventaja sobre aquellos que solo pueden ser leidos por humanos.

La buena noticia: empezar es sorprendentemente facil. Un archivo JSON, algunos endpoints de API, y tu sitio web habla un nuevo idioma. No el idioma de los motores de busqueda. Sino el idioma de los agentes de IA.

Y tendran mucho que decir en los proximos anos.