Infrastructure — Caché, Errores, Redirecciones

¿Qué es "Infrastructure"?

El grupo Infrastructure cubre el comportamiento HTTP de bajo nivel que determina si los agentes pueden interactuar con tu origen de forma fiable. Ninguno de estos es específico de un protocolo — aplican a cualquier sitio, ya sirva un endpoint MCP, una especificación OpenAPI o solo contenido estático.

Redirección HTTPS

Los agentes siguen enlaces. Si http://tudominio.com no redirige a https://tudominio.com, los agentes que llegan a la URL HTTP fallan o se degradan. Los clientes de IA modernos suelen rechazar HTTP plano por completo.

Solución: responde con 301 o 308 desde http://tudominio.com/* a la misma ruta en HTTPS. La mayoría de plataformas lo hacen por ti (Cloudflare, Vercel, Heroku, build.io). Si te autohospedas, añade un bloque server de nginx escuchando en el puerto 80 que emita la redirección.

Sitemap.xml

Los agentes descubren tus URLs desde /sitemap.xml. Sin él, las únicas rutas a las que un agente puede llegar son las enlazadas desde tu página principal o declaradas en llms.txt — normalmente una pequeña fracción de tu contenido real.

Solución: sirve un sitemap XML en /sitemap.xml. Frameworks como Next.js, Hugo, Jekyll y Wordpress generan uno automáticamente. Para un sitemap manual:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url><loc>https://tudominio.com/</loc></url>
  <url><loc>https://tudominio.com/docs</loc></url>
</urlset>

Encabezados de caché

Todo servidor bien configurado emite al menos uno de Cache-Control, ETag o Last-Modified en sus respuestas. Sin ellos, los agentes no tienen forma de saber si volver a descargar o usar una copia en caché — o redescargan siempre (lento, caro) o cachean indefinidamente (datos incorrectos).

Solución: la mayoría de frameworks web los establecen por defecto para archivos estáticos. Para respuestas dinámicas, establece Cache-Control explícitamente:

// Express — para contenido que cambia ocasionalmente
res.set('Cache-Control', 'public, max-age=3600');

// Para respuestas que no se cachean (sigue cumpliendo la verificación):
res.set('Cache-Control', 'no-store');

no-store cuenta como un encabezado de caché válido — le dice al agente "no caches esto", lo cual ya es información útil. La verificación falla cuando *no hay ningún* encabezado de caché.

Errores estructurados (JSON 404)

Cuando un agente accede a una URL incorrecta, una página HTML 404 (con navegación, pie, buscador, etc.) desperdicia tokens y puede engañar a un agente confundido haciéndole creer que recibió contenido real. Un 404 JSON devuelve un error pequeño y parseable:

{ "error": "not_found", "path": "/wrong-url" }

Solución: usa negociación de contenido en tu manejador 404. Devuelve JSON cuando el cliente envía Accept: application/json, HTML en otro caso. Ejemplo en Express:

app.use((req, res) => {
  res.status(404);
  res.format({
    'application/json': () => res.json({ error: 'not_found', path: req.path }),
    'text/html': () => res.send('<h1>404 Not Found</h1>'),
    default: () => res.json({ error: 'not_found', path: req.path }),
  });
});

Este cambio es invisible para los humanos (los navegadores envían Accept: text/html y reciben HTML) pero transformador para los agentes (envían Accept: application/json y reciben JSON parseable).

Encabezados de rate limit (opcional)

Si tu servicio limita la tasa de peticiones, expón el estado mediante X-RateLimit-Remaining, X-RateLimit-Reset o Retry-After. Los agentes que alcanzan un límite pueden esperar el tiempo correcto y reintentar en lugar de fallar.

Esta verificación es opcional porque la mayoría de los sitios no aplican rate limit — solo lo hacen proveedores de API y aplicaciones SaaS. Los sitios estáticos no tienen nada que exponer.

Por qué son requeridas

Encabezados de caché, errores estructurados, sitemap y redirección HTTPS fallan de forma benigna hoy en muchos sitios — y ese es el punto. Cada uno representa un punto real de fricción para agentes que los humanos no perciben. Promoverlas de opcional a requerida refleja la posición de que un sitio "agent-ready" debe abordarlas, no solo las verificaciones específicas de protocolo (MCP, OpenAPI, x402, etc.).

agentgrade