By now, most developers know the basics of Agent Experience (AX). Teams ship MCP servers, llms.txt, and a "Copy for AI" button across docs.
This is genuinely helpful, because agents can now learn how to use your product. But reading your guides and using them are two very different things. Our belief is simple: great AX is when an agent reaches its goals with your product, whatever route it might choose.
At 2027.dev, we run coding agents against tools every day. Over time, one thing has become clear to us: tools with the best AX aren't the ones with the widest MCP or CLI coverage. They're the ones that have obsessed over every place agents might look and get stuck, and work relentlessly to get them through.
Vercel is one of them, and we're excited to share their blueprint for great AX, put together in collaboration with their team.
1/ Put the docs where the agent already looks
Docs in AGENTS.md took Next.js evals from 53% to 100%.
The #1 reason agents break on fast-moving tools is the training data. An agent remembers Next.js from a year ago and confidently writes code against APIs that don't exist anymore – a very common friction across our benchmarks.
Vercel engineers noticed this in their evals. In January, they ran Next.js evals with the docs available as a skill, and compared it to a compressed 8KB docs index placed directly in AGENTS.md:
The skill alone did nothing: in 56% of runs, the agent never even called it. It turns out, agents don't look up docs for things they think they already know.
So Next.js made the docs impossible to miss. Next.js 16.2 shipped the docs inside the package: 456 files in node_modules/next/dist/docs/, always matching the installed version. And the following one, Next.js 16.3, went one step further: when next dev detects a coding agent, it writes this block into your AGENTS.md and a CLAUDE.md that imports it:
Notice how the heading goes straight at the biggest friction point: "This is NOT the Next.js you know." It shows the happy path and even covers monorepos where that path won't resolve. Next, Vercel predicts the agent will try to revert the unexpected change, explains why that won't work, and tells it what to do instead. This is a smart move: working backwards from what the agent will actually do is a great starting point for any AX decision.
Since coding agents load AGENTS.md into context automatically, "go read the docs" is now part of the system prompt. The agent doesn't have to find a docs tool or decide to use it. (And if you don't want it, agentRules: false in next.config turns it off.)
If your SDK changes faster than models get retrained, make sure to ship versioned docs with it and point agents at them from AGENTS.md.
"We discovered that agents can brute force their way into most solutions, but that costs tokens, turns and more. We realized quickly we need to steer the agents to be more effective."
Melkey Moksyakov Staff Software Engineer @ Vercel
2/ Turn a 404 into directions
A missing page is still a chance to help the agent.
Agents guess URLs all the time. They take a docs path they remember or simply make up and fetch it. When a human hits a 404, we go back and search what to do next. When an agent hits a 404, it often decides the page doesn't exist and falls back to whatever it already believes from their memory or training data set.
Every Vercel docs page has a markdown version, and the same goes for pages that don't exist. So when an agent requests one, the 404 lists the pages it probably meant:
We like calling this "smart 404s". When humans open this page in a browser, they still get a normal HTML 404, but the agent gets real directions.
Fun fact: Vercel changed its mind on this. Agents tend to ignore the body of a 404, so its @vercel/agent-readability package used to send these pages with a 200 "success" status instead, just to make sure the suggestions got read. In August they switched to a real 404. Their guide now says the status code is the one reliable way for an agent to know a page is missing, and returning 200 takes that away, even if the body suggests alternatives.
Takeaway: an error message is a chance to point the agent in the right direction. When an agent requests a page that doesn't exist, return a real 404 in markdown that points to the closest matching pages.
Note: Having run evals on 200+ developer tools, our team has designed a skill for agent-friendly error message design. Check it out here.
3/ Make non-interactive the default
If your CLI can't run without a human, it breaks your AX.
Since August 2025, the Vercel CLI uses @vercel/detect-agent to tell when it's running under Claude Code, Cursor, Codex, Gemini CLI, Devin and others. When it detects an agent, non-interactive mode is on by default. Errors come back as JSON, with the exact command to run next:
vercel env add is a good example of how far this has come. It used to prompt for the value and the environments, so an agent simply couldn't set an env var on its own. Now it can:
It's not perfect yet. There are open issues where non-interactive env add stores an empty value, or rejects the command it just suggested – one of them is literally titled "infinite loop for agents." And this is the tricky part of designing for agents: a human notices when a CLI says "success" but nothing happens, while agents assume they've reached the goal.
What we really like is that Vercel also went the other way on purpose. Destructive commands, like deleting a blob store, now refuse to run non-interactively and return interactive_confirmation_required.
"The CLI has clearly become one of the most important surfaces for agents to be effective. We have seen first hand how crucial it is to have a secure and efficient flow for agents using Vercel, so this is why we have implemented from the ground up our CLI for our "agent" customer."
4/ Deploy first, sign up later
Identity can come second.
Most teams make signup step one, and that's exactly where agents fail: email verification, OAuth in a browser, a CAPTCHA. Vercel flips the order: it gives you a working result first, then asks for an account once there's something worth keeping.
Claimable deployments launched in January 2025 as an API for platforms building on Vercel: deploy to your own team, generate a transfer code, and send the user to a claim link. In August 2026, it came to the CLI. vercel deploy with no credentials now creates a temporary anonymous project and prints a claim URL. An agent can put a site live for someone who doesn't even have a Vercel account, and that person can take ownership later. Claims now carry connected resources too, like Neon, Supabase and Prisma databases.
For the record: on our AX Tier List, this is why Vercel is S tier (hands-off agent onboarding), along with Clerk, Railway, Browserbase, Sanity, Neon and more.
5/ Sign up for the rest of the stack from the terminal
Minimize the need for humans in the loop.
Real apps need a database, auth and error tracking. Every time an agent sees a command such as "go to the dashboard and create a project", it must interrupt its session and ask a human for help.
The Vercel Marketplace removes that handoff right from the command line:
integration add creates the resource, connects it to the project and pulls the env vars locally. Since August, it also installs the provider's own agent skills, so the agent gets the database and the instructions for using it in one step.
If your product usually sits next to others in a stack, provisioning partners from your CLI can be a game changer for agentic users.
6/ Set the standard, don't wait for one
npx skills went from launch to ~28M monthly downloads in eight months.
SKILL.md is an open format, but Vercel built the tools most people use to install it. npx skills add <owner/repo> and the skills.sh directory launched in January. npx plugins followed in March.
Same with agent detection: @vercel/detect-agent proposes AI_AGENT as one environment variable every agent can set. Whether or not these become the standard, the ecosystem is being shaped around how Vercel already works. Being the voice that pushes the standard is an AX strategy in itself.
The pattern
All these design principles show a clear pattern. Wherever an agent might stop and guess, Vercel has built a way through that doesn't need a human.
- Stale knowledge → bundled docs and a pointer in
AGENTS.md - Wrong URLs → a 404 that tells you where to go
- Interactive prompts → a flag for every question the CLI asks
- Signup walls → deploy first, claim later
- Leaving the terminal → integrations provisioned from the CLI
- Fragmented tooling → an open standard
None of this is rocket science. It's just taking agents seriously as users, identifying their common routes, releasing updates, and measuring whether the product gets them moving again.
If you're shipping for agents but have never tested where they actually get stuck, now is the right time to do it.
Let's make something agents want.