Agent feedback en Next.js: tu agente reporta los fallos del framework

agentFeedback es una opción experimental de Next.js 16.4 que convierte a tu agente de código en reportero de bugs del framework. Mientras trabaja, el agente anota los problemas de Next.js que encuentra. Al terminar la tarea, te abre en el navegador un borrador de reporte para el equipo de Next.js. Puedes editarlo o descartarlo, y nada se envía hasta que pulsas Send feedback.

El problema que ataca es conocido para cualquiera que trabaje con Claude Code, Codex o Cursor. El agente se topa con un error raro de Next.js, una documentación que no cuadra o un workaround nada obvio, lo resuelve y sigue. El equipo de Next.js nunca se entera de qué falló, qué probó el agente ni qué funcionó al final. Con este flujo, ese conocimiento sale del chat y llega al framework: según el anuncio de la 16.4, los reportes enviados se agrupan para encontrar problemas recurrentes y mejorar el comportamiento del framework, los mensajes de error, la documentación y las herramientas.

Next.js 16.4.0 se publicó en npm el 6 de octubre de 2026.

Cómo activar agentFeedback en Next.js

Agrega la opción en experimental de tu next.config.ts:

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  experimental: {
    agentFeedback: true,
  },
}
 
export default nextConfig

Las apps nuevas creadas con la configuración recomendada de create-next-app ya traen la opción activada. En un proyecto existente hay que ponerla a mano.

Que la pongas en true no basta. El código de next dev en la 16.4.0 exige tres condiciones más:

• La telemetría de Next.js tiene que estar activada. Si la apagaste con next telemetry disable o con la variable NEXT_TELEMETRY_DISABLED, la función no corre.
• No puede ser un entorno de CI: next dev y el comando de reporte comprueban isCI y ahí no hacen nada.
• next dev tiene que detectar un agente de código, y para eso usa una copia empaquetada de @vercel/detect-agent. Si arrancas el servidor tú, desde tu terminal, no escribe nada.

Cuando las tres se cumplen, next dev lo avisa en la consola: "Generated agent feedback instructions in AGENTS.md".

Qué escribe Next.js en AGENTS.md

next dev agrega este bloque gestionado a AGENTS.md, en la raíz del proyecto:

<!-- BEGIN:nextjs-agent-feedback -->
 
## Report Next.js feedback
 
The project owner enabled `experimental.agentFeedback`, authorizing this feedback pass. When enabled, `next dev` writes this block and restores it if removed. Commit `AGENTS.md` with your work to keep the tree clean.
 
During the current user request, retain anonymized facts as feedback candidates for meaningful or recurring Next.js issues:
 
- Crashes, hangs, OOMs, or unexpected slowness
- Incorrect behavior, output, errors, or diagnostics
- Missing, unclear, or conflicting documentation
- Unexpected CLI, codemod, Skill, or upgrade behavior and non-obvious workarounds
 
Continue the current user request without reporting immediately. Ignore routine debugging and unverified changes. Never retain code, logs, paths, URLs, secrets, personal information, or project-specific data.
 
Before the final response, run one reporting pass. If candidates remain, from this file's directory run `node node_modules/next/dist/bin/next internal agent-feedback-instructions` once without piping or truncating its output. Follow its output or error guidance. If a network sandbox blocks it, retry with network access; if it still returns no output, continue normally.
 
<!-- END:nextjs-agent-feedback -->

Next.js solo toca lo que está entre los marcadores y respeta el resto del archivo. Si borras el bloque, next dev lo vuelve a escribir mientras la opción siga activa. Por eso el propio bloque te pide commitear AGENTS.md.

Si también tienes activado agentRules, el bloque que apunta a la documentación empaquetada en node_modules/next/dist/docs/, los dos conviven en el mismo archivo. Son opciones independientes: cambiar una no afecta a la otra. Si no tienes claro qué agente lee AGENTS.md y cuál no, lo explico en AGENTS.md: qué es y qué archivo lee cada agente de IA.

Cómo funciona por dentro

El bloque de AGENTS.md es solo la primera parte. Las instrucciones completas no están ahí. Las imprime un comando oculto de la CLI de Next.js:

node node_modules/next/dist/bin/next internal agent-feedback-instructions

Ese comando, en la 16.4.0, hace tres comprobaciones antes de imprimir nada:

1. Que no estás en CI.
2. Que la telemetría está activada en el proyecto.
3. Que un interruptor remoto de Vercel está encendido. El comando hace un fetch a https://next-agent-feedback-gate.playground-vercel.tools/api/enabled, espera hasta 5 segundos y solo sigue si la respuesta es exactamente true.

Si todo pasa, imprime el protocolo, un Markdown que viene dentro del paquete en node_modules/next/dist/agent-feedback/protocol.md. Si algo falla, no imprime nada y el agente termina normalmente. Si falla la consulta de red, el comando escribe en stderr que hay que repetirlo con acceso a red. Por eso el bloque le dice al agente que reintente con red si un sandbox lo bloquea.

Cuando el agente encuentra un problema, no lo reporta en ese momento: guarda los hechos como "candidatos" y sigue con tu tarea. Hace una sola pasada de reporte al final, cuando ya terminó todo el trabajo y justo antes de su última respuesta, así que el feedback no corta lo que le pediste.

El protocolo también contempla las Skills de Next.js y el flujo de next upgrade --agent: pueden agregar candidatos mientras trabajan, siempre que el bloque gestionado esté en AGENTS.md.

Qué cuenta como un problema que reportar

Según el protocolo, merece reporte la fricción con Next.js que encaja en uno de estos cinco motivos, que van en el campo triggerReason:

El problema no tiene que bloquear la tarea, pero sí tiene que haber obligado a un desvío importante o ser probable que se repita. Quedan fuera la depuración rutinaria del primer intento, los problemas causados por cambios sin verificar y lo que se resuelve en seguida siguiendo la documentación. Si antes hubo un error engañoso o varios intentos fallidos, el reporte sigue valiendo aunque el agente encuentre después un workaround.

Cada problema distinto va en un reporte separado. El protocolo prohíbe mezclar problemas o inventar una causa raíz.

Qué contiene cada reporte

El agente arma un JSON con la versión 5 del esquema. Estos son los campos y sus límites, según el protocolo de la 16.4.0:

Las mediciones (memoria, duración, builds extra) solo entran si el agente las observó directamente. El protocolo le prohíbe estimar el tiempo transcurrido, los tokens o la cantidad de llamadas a herramientas.

Ese JSON se codifica en base64url y se pega en esta URL:

https://nextjs.org/agent-feedback#report=<json-codificado>

El agente intenta abrir cada URL una vez, en una pestaña aparte de tu navegador predeterminado, y no te pide permiso para hacerlo. Si la pestaña no abre, no reintenta ni instala nada. En cualquier caso, la respuesta final del agente incluye todas las URLs para que encuentres los formularios.

Qué se envía a Vercel y qué no

Abrir el formulario no envía nada. El borrador viaja después del # de la URL, la parte que el navegador no incluye en la petición HTTP. La página lo lee en tu navegador y te lo muestra para revisar.

Cuando pulsas Send feedback, según la documentación, se envía el contenido que revisaste, el nombre del agente y la versión de Next.js. El formulario no adjunta archivos del proyecto ni metadatos de tu máquina.

La anonimización la hace el propio agente siguiendo instrucciones: reemplazar nombres de clientes, proyectos, rutas y componentes por descripciones genéricas, y no incluir código, prompts, logs, stack traces, rutas de archivos, URLs, secretos ni datos personales. La documentación dice que el agente "intenta" anonimizar y te pide revisar el borrador, así que la última palabra es tuya: léelo y borra lo que no quieras compartir antes de enviarlo.

Cómo probarlo sin abrir el navegador

El comando tiene una opción --dry-run:

node node_modules/next/dist/bin/next internal agent-feedback-instructions --dry-run

En modo dry run, el protocolo le pide al agente que codifique las URLs y las imprima, sin abrir pestañas y sin dar por cerrada la pasada de reporte. Además, el comando se salta las comprobaciones de CI, telemetría e interruptor remoto: imprime el protocolo siempre. Sirve para ver qué reportaría tu agente sin tocar el navegador.

Cómo desactivar agentFeedback

Pon experimental.agentFeedback en false o quita la opción. En la siguiente ejecución de next dev, Next.js borra el bloque de feedback de AGENTS.md y deja el resto intacto. Si el archivo solo tenía ese bloque, lo elimina en vez de dejarlo vacío.

Apagar la telemetría tiene el mismo efecto:

npx next telemetry disable

Con la telemetría desactivada, next dev quita el bloque y el comando de instrucciones no devuelve nada.

Preguntas frecuentes

Fuentes

• agentFeedback, referencia de la opción en la documentación de Next.js.
• How Next.js supports AI coding agents, guía oficial, sección "Automatic agent feedback".
• Next.js 16.4, anuncio del 6 de octubre de 2026.
• next en npm, paquete 16.4.0. El protocolo está en dist/agent-feedback/protocol.md y el comando en dist/cli/internal/agent-feedback-instructions.js.