Building Next.js Apps for AI Agents: AGENTS.md, @vercel/next-browser, and Agent DevTools in 16.2

Next.js 16.2 ships three features that treat AI agents as first-class users of your codebase: an AGENTS.md file that create-next-app writes with version-matched docs, the @vercel/next-browser CLI that hands an LLM screenshots, network logs, and console output in one call, and an experimental Agent DevTools. In Vercel's own evals, the version-matched AGENTS.md approach hit a 100% pass rate against 79% for a generic skills file. I have spent the last two years building RAG systems and agents, and this release is the first time the framework itself started designing for the consumer I care most about: the model.

If you are wiring Claude, Cursor, or a custom agent into a Next.js repo, these are the primitives that decide whether the agent fixes your bug or hallucinates an API that was removed three versions ago.

What is AGENTS.md in create-next-app and why does it matter?

AGENTS.md is a plain Markdown file that create-next-app now generates at the project root, and it tells any AI coding agent how this specific app is structured and which Next.js APIs it should and should not use. The point is version pinning: the file documents the conventions for the exact Next.js version you scaffolded, not the average of every blog post the model trained on.

That last part is the whole story. The reason agents write broken Next.js code is not that they are bad at React. It is that the training data is a blur of App Router, Pages Router, getServerSideProps, unstable_cache, and middleware patterns spanning five years of releases. The model has no way to know that your repo is on 16.2 and that half of what it "knows" was deprecated. AGENTS.md collapses that ambiguity into one file the agent reads first.

Here is the shape of what create-next-app writes:

## AGENTS.md

This is a Next.js 16.2 project using the App Router.

## Conventions
- Use Server Components by default. Add "use client" only when you need
  state, effects, or browser APIs.
- Data caching uses the `use cache` directive, not `unstable_cache`.
- Route middleware lives in `proxy.ts` (Node runtime), not `middleware.ts`.
- Fetch in Server Components; do not create client-side fetch waterfalls.

## Commands
- `pnpm dev`, start the dev server
- `pnpm build`, production build (run before claiming a task is done)
- `pnpm lint`, eslint + type check

## Do not
- Do not import server-only modules into Client Components.
- Do not reintroduce `getServerSideProps` or the Pages Router.

The format is not Next-specific. AGENTS.md is a cross-tool convention that Cursor, Claude Code, and others already read, so one file serves every agent on the team. What Next.js added is the version-matched content and the fact that it lands automatically on create-next-app.

How does AGENTS.md compare to a generic skills file?

In Vercel's published evals, the version-matched AGENTS.md produced a 100% pass rate on their task set, while a generic "skills" file scored 79%. The gap comes down to specificity: a skills file describes Next.js in general, while AGENTS.md describes your Next.js.

I read that 21-point gap the way I read retrieval metrics in a RAG system. A generic skills file is like stuffing the whole framework docs into context and hoping the model retrieves the relevant chunk. The version-matched file is like a tuned retriever that returns exactly the passage that applies to this codebase. Less noise, fewer wrong turns, higher pass rate. This is the same lesson I apply when I build AI agents and automation ↗ for clients: precision of context beats volume of context almost every time.

The honest caveat: 100% on a curated eval set is not 100% on your gnarly production monorepo. Treat the number as evidence that version-matching is the right lever, not as a promise the agent will never miss. I still review every agent diff against a real build.

What does @vercel/next-browser actually give an agent?

@vercel/next-browser is a CLI that launches your running app in a headless browser and returns a screenshot, the network requests, and the console output as structured text an LLM can parse in a single shot. It turns "the page looks broken" into machine-readable evidence the agent can reason over without a human describing the screen.

This is the feature I was waiting for. The hardest part of letting an agent fix a frontend bug is that the agent is blind. It can read your code but it cannot see the rendered result, so it guesses. @vercel/next-browser closes that loop. One command, and the model gets the same three signals a senior dev checks first: what rendered, what the network did, and what threw in the console.

A typical agent-driven invocation looks like this:

npx @vercel/next-browser inspect http://localhost:3000/dashboard \
  --screenshot \
  --network \
  --console \
  --format json

And the agent receives something it can route on:

{
  "url": "http://localhost:3000/dashboard",
  "screenshot": "data:image/png;base64,iVBORw0KGgo...",
  "console": [
    { "level": "error", "text": "Hydration failed: text content mismatch" }
  ],
  "network": [
    { "url": "/api/metrics", "status": 500, "duration": 812 }
  ]
}

The model does not need me to interpret that. It sees a 500 on /api/metrics and a hydration error in one payload, and it can correlate them. That correlation across signals is exactly what an LLM is good at when you hand it structured input instead of a wall of prose.

How do PPR shells fit into this for agents?

@vercel/next-browser can return the Partial Prerendering (PPR) shell, the static outer frame Next.js serves before dynamic content streams in, as a separate parseable artifact. This matters because it lets an agent reason about the static layout and the streamed-in content independently instead of inspecting one tangled blob.

PPR splits a route into a prerendered static shell plus dynamic holes that stream later. For a human in DevTools, that is fine. For an agent, an undifferentiated DOM dump is hard to reason about because it cannot tell which parts are guaranteed-static and which arrive asynchronously. Exposing the shell on its own means the agent can answer questions like "is the layout itself broken or is it a streamed component failing" without guessing at timing.

In practice I use this when debugging the seams between server and client. If the shell renders clean but a streamed boundary throws, that points me at a Suspense or data-fetch issue in a dynamic hole, not at the page skeleton. The agent can make that same split, which keeps it from rewriting the static layout when the real bug is in a streamed fetch.

What are the experimental Agent DevTools in 16.2?

Agent DevTools is an experimental surface in Next.js 16.2 that exposes the framework's internal state, things like route boundaries, cache behavior, and render mode, in a form agents can query rather than a panel only humans can click through. It is the framework admitting that the consumer of debugging information is increasingly a model, not just a person.

Because it is experimental, I treat it as a preview, not a foundation. The API surface will move, and I would not build a permanent agent workflow on it yet. But the direction is clear and I think it is correct. Today an agent reconstructs framework state by reading source and inferring; Agent DevTools would let it ask the framework directly. That is the difference between an agent that infers your caching strategy from use cache directives scattered across files and one that queries the actual cache state at runtime.

If you turn it on, scope it to local development:

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  experimental: {
    agentDevTools: process.env.NODE_ENV === "development",
  },
};

export default nextConfig;

Never ship an experimental introspection surface to production. Exposing internal render and cache state is a great way to hand an attacker a map of your app.

How do I set this up in a real project today?

Start fresh or add the file by hand, then point your agent at it and give the agent the browser CLI as a tool. The minimum viable setup is one Markdown file plus one CLI dependency, and you can have it working in under ten minutes.

If you are scaffolding new, you get AGENTS.md automatically:

npx create-next-app@latest my-app
## AGENTS.md is written to the project root

For an existing app, write AGENTS.md yourself. Match it to the version in your package.json and document your real conventions, not aspirational ones. An agent that follows accurate-but-modest rules beats one chasing rules you do not actually enforce.

Then add the browser CLI and expose it to your agent as a command it is allowed to run:

pnpm add -D @vercel/next-browser

A few rules I follow so this does not turn into a foot-gun:

• Keep AGENTS.md in version control and update it the same PR you bump Next.js. A stale agent file is worse than none because it confidently misleads.


• Give the agent the build command in AGENTS.md and require a clean pnpm build before it claims a task is done. The browser CLI catches runtime errors; the build catches type and import errors.


• Run @vercel/next-browser against a real dev server, not a mock. The whole value is real network and console signal.

Should I trust an agent with this access?

Give the agent read and inspect access freely, but gate writes and never expose introspection in production. The browser CLI and AGENTS.md are about feeding the model better context, which is low risk; the danger is in what the agent does with what it learns and in what you leave exposed.

Two things keep me honest here. First, security. Next.js has had real, severe issues this cycle, and an agent that confidently applies an outdated pattern can reintroduce a vulnerability you already patched. If you are not current, read the React Server Components RCE upgrade map ↗ before you let any agent near the codebase, and encode the safe version in AGENTS.md. Second, scope. Agent DevTools and next-browser should be development-only, behind NODE_ENV checks, never bundled into a production build.

The mental model that works for me: AGENTS.md controls what the agent believes, @vercel/next-browser controls what the agent can observe, and your review plus a clean build control what the agent can ship. Get all three right and the agent becomes a fast, well-informed junior. Skip the review step and it becomes a confident one, which is worse.

If you want help wiring agents into a Next.js codebase without the foot-guns, or building the RAG and agent systems that sit behind them, my contact page ↗ is the fastest way to reach me. I would rather set this up with you once than debug a hallucinated migration later.