--- title: "Agent feedback en Next.js: tu agente reporta los fallos del framework" excerpt: "agentFeedback es una opción experimental de Next.js 16.4: tu agente de código anota los problemas del framework que encuentra mientras trabaja y, al terminar, te abre un borrador de reporte en el navegador. Cómo se activa, qué hace por dentro y qué se envía." date: "2026-10-11T15:00:00.000Z" category: "Next.js" tech_article: true author: name: "angel cruz" picture: "/images/me/angel-cruz.png" ogImage: url: "/images/open-graph/next-opengraph-image.png" seo_title: "Next.js agent feedback: qué es y cómo activar agentFeedback" seo_description: "agentFeedback de Next.js 16.4: tu agente prepara reportes de bugs del framework y los abre en el navegador para que los revises. Activación, flujo y privacidad." --- **`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`: ```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: ```md ## 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. ``` 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](/post/agents-md-que-es-que-lee-cada-agente). ## 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: ```bash 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`: | `triggerReason` | Qué significa | |---|---| | `unexpected-behavior` | El framework hace algo distinto a lo esperado | | `documentation-mismatch` | La documentación no coincide con lo que pasa | | `misleading-error` | El mensaje de error lleva a una conclusión equivocada | | `repeated-failed-approach` | El agente probó varios caminos que no funcionaron | | `non-obvious-workaround` | Lo resolvió, pero con un rodeo que nadie adivinaría | 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: | Campo | Contenido | |---|---| | `title` | El comportamiento observado, hasta 100 caracteres | | `setup.mode` | `development`, `production-build`, `production-server` o `test` | | `setup.bundler` | `turbopack`, `webpack` o `unknown` | | `setup.relevantFeatures` | Hasta 3 features genéricas, 32 caracteres cada una (opcional) | | `steps` | De 1 a 4 pasos para reproducirlo, 240 caracteres cada uno | | `observed` | De 1 a 3 hechos verificables, 160 caracteres cada uno | | `expected` | El resultado esperado, hasta 200 caracteres | | `comparison` | El control o workaround observado, hasta 180 caracteres (opcional) | | `frequency` | `once` o `reproduced` | | `outcome` | `blocked`, `worked-around` o `resolved` | | `nextVersion` y `agent` | Versión de Next.js y nombre del agente, hasta 64 caracteres | 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: ```text https://nextjs.org/agent-feedback#report= ``` 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`: ```bash 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: ```bash npx next telemetry disable ``` Con la telemetría desactivada, `next dev` quita el bloque y el comando de instrucciones no devuelve nada. ## Preguntas frecuentes ### ¿Qué es agentFeedback en Next.js? Es una opción experimental de `next.config` que llegó en Next.js 16.4. Hace que `next dev` escriba en `AGENTS.md` instrucciones para que tu agente de código anote los problemas de Next.js que encuentra y, al terminar, te prepare reportes que tú revisas y decides si enviar al equipo de Next.js. ### ¿Next.js agent feedback envía mi código? No debería. El agente tiene instrucciones de no incluir código, logs, rutas, URLs, secretos ni datos del proyecto, y el formulario no adjunta archivos. Pero la anonimización depende del agente, así que revisa cada borrador antes de pulsar Send feedback. Sin ese clic no se envía nada. ### ¿Funciona con Claude Code, Codex o Cursor? Funciona con los agentes que `next dev` detecta y que leen `AGENTS.md`. La guía de Next.js para agentes menciona a Claude Code, Codex, Cursor y GitHub Copilot entre los que leen ese archivo al empezar una sesión. ### ¿Por qué no se genera el bloque en AGENTS.md? Revisa las cuatro condiciones: la opción en `true`, la telemetría activada (`npx next telemetry status`), que no estés en CI y que `next dev` lo haya arrancado un agente. Si arrancas el servidor tú desde la terminal, no hay agente que detectar. ### ¿Se puede usar agentFeedback en producción? La documentación lo marca como experimental y no recomendado para producción. De todos modos, el bloque de `AGENTS.md` solo lo escribe `next dev`, y en CI no corre nada. ### ¿Qué versión de Next.js necesito? Next.js 16.4.0 o superior. La opción `experimental.agentFeedback` se agregó en esa versión. ## Fuentes - [agentFeedback](https://nextjs.org/docs/app/api-reference/config/next-config-js/agentFeedback), referencia de la opción en la documentación de Next.js. - [How Next.js supports AI coding agents](https://nextjs.org/docs/app/guides/ai-agents#automatic-agent-feedback), guía oficial, sección "Automatic agent feedback". - [Next.js 16.4](https://nextjs.org/blog/next-16-4#agent-feedback), anuncio del 6 de octubre de 2026. - [next en npm](https://www.npmjs.com/package/next/v/16.4.0), paquete 16.4.0. El protocolo está en `dist/agent-feedback/protocol.md` y el comando en `dist/cli/internal/agent-feedback-instructions.js`. --- ## Sitemap Índice completo del sitio: [/sitemap.md](https://www.angelcruz.dev/sitemap.md) Canónico HTML: [https://www.angelcruz.dev/post/nextjs-agent-feedback](https://www.angelcruz.dev/post/nextjs-agent-feedback)