Learning Path
Pick the path that fits what you are working on
Websites
More on Websites
Applications
AXD Fundamentals
The agent journey map
A user journey map assumes someone who can see the screen, read the hints, and work out what you meant. Take that person away and the same app takes a different shape. This map shows the path an agent takes through software, so you can design for it before anything is built.
This is a framework, not a measurement. The Agent Analyzer reports what really happened when an agent visited a page you own. This map comes earlier, at the design stage: the steps, what each one needs, and the question to answer while changing your answer is still cheap.
Why the order matters
An agent can’t get through any step until the one before it works. That sounds obvious, but it is easy to start at step four, because building an API (a way for other software to use your app directly) that an agent can call is the part that feels like engineering.
Then nothing uses it, because no agent could find it or prove it had permission.
- 1
Discover
Find out that your software exists and what it can do, without a human reading your marketing.
What it needs from you
- A description of what your app does, in a format software can read
- A published list of the actions it offers, not a sales page
- A fixed web address for that list that doesn’t change between releases
How it usually breaks
The list of what your app can do lives in a PDF, a Notion page, or a developer site behind a login. An agent can’t read any of them, so it never learns the action exists, and it falls back to clicking through your screens the way a human would.
Ask before building: If an agent had never heard of us, which single web address would tell it what we can do?
- 2
Prove it has permission
Show that it is acting for a specific person, with their permission, for a limited purpose.
What it needs from you
- Login details an agent can hold that aren’t the user’s own password
- Permissions narrow enough that handing over a task isn’t all or nothing
- A way to tell an agent someone sent apart from a scraper (a bot copying your content), without blocking both
How it usually breaks
The only way in is a human login with a one-time code. Either the agent stops there, or the user hands over their password, and both are worse than designing for agents in the first place.
Ask before building: What is the smallest permission that lets an agent do the everyday task, and can someone grant only that?
- 3
Understand the offer
Work out which action matches what it was sent to do, and what that action needs.
What it needs from you
- Actions named for what they achieve, not for your internal terms
- Required inputs listed, with their formats and units
- Anything that has to happen first spelled out, not left implied by the order of a step-by-step form
How it usually breaks
The steps only make sense in order, because the screens forced that order. An agent looking at the actions on their own can’t tell that one has to come before another, so it tries them in the wrong order and fails without knowing why.
Ask before building: Reading only our action names and inputs, could a newcomer pick the right one first time?
- 4
Attempt
Carry out the task. This is the only step most teams design for.
What it needs from you
- An action that can be finished without a gesture, a drag, or judging something by eye
- Idempotency (safe retries), so that trying again doesn’t create a second order
- No step that exists only to slow a human down
How it usually breaks
Something in the middle needs a mouse or a human eye: drag-to-reorder, a slider, a CAPTCHA (a “prove you’re human” puzzle), or a confirmation that only shows up as a visual cue. The agent gets most of the way there and stops.
Ask before building: Can the whole task be done without seeing the layout?
- 5
Interpret the result
Find out whether it worked, and if it didn’t, whether to try again.
What it needs from you
- Errors that tell apart "wrong input", "try again later", and "this will never work"
- The exact field or value that was wrong, named
- A result that says what happened, not just an error number
How it usually breaks
Everything comes back as the same generic failure, so the agent can’t tell a typo from an outage. It keeps retrying things that will never work and gives up on things that would have worked a second later.
Ask before building: Does every error say which of those three kinds it is?
- 6
Recover
Get back on track without a human, or decide that a human is needed.
What it needs from you
- A way to check where things stand before acting again
- Actions that can be reversed, or a clear way to undo them
- A clear line between what an agent may retry by itself and what it must pass to a human
How it usually breaks
The only way to recover is through the screens ("go to settings and check"), so an agent working through your API (the way other software uses your app directly) has no route back. It either stalls or repeats the thing that failed.
Ask before building: After a half-finished task, can an agent find out where things stand and carry on?
- 7
Hand back
Go back to the user with a result they can check, or a decision only they can make.
What it needs from you
- A record of what was done that a human can read later
- Decisions raised before they’re made, not reported afterwards
- Something to show for it: a reference number, a receipt, a link to whatever changed
How it usually breaks
The agent says it succeeded and the user has no way to check. The first time that turns out to be wrong, they stop handing tasks to it, and you lose every future task that would have come through that agent along with this one.
Ask before building: When the agent says it’s done, what can the user look at to be sure?
How to use it
Pick one task a customer might well hand to an agent, such as rescheduling a booking, reordering something they keep running out of, or canceling a plan. Walk it through the seven steps, answering each question honestly for that task alone. If you can’t answer the first three, start there.
Then do it again with a task you would not want an agent doing. Where the two paths split is your real policy on agent access, and it’s better to write it down now than to find out from live customers.
See the path on your own site
The Agent Visualizer follows an AI agent through one of your pages and shows where it arrives, where it reads, where it gets stuck, and everything past that point it never reaches.
Further reading from Field Notes
Posts with more on this topic, each with its date.
Stay Updated
A monthly email about AI search, AI crawler policy (the rules for the AI bots that visit websites), and new standards for agents. It includes every Field Note published that month, and you can unsubscribe at any time.