Learning Path
Navigate the AXO curriculum
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 away and the same product has a different shape. This is the path an agent walks through software, written to be designed against before anything is built.
This is a framework, not a measurement. The Agent Analyzer reports what actually happened to an agent on a page you own. This map is the design artifact that sits before that: the steps, what each one needs, and the question worth answering while it is still cheap to change the answer.
Why the order matters
Each step is impossible until the one before it works. That sounds obvious written down, and it is the single most common way agent integrations fail in practice: teams start at step four, because building an API an agent can call is the part that feels like engineering.
Then nothing uses it. Nothing discovered it existed, and nothing could prove it had permission to try. The work was real and it was in the wrong place.
- 1
Discover
Find out this software exists and what it can do, without a person reading your marketing.
What it needs from you
- A machine-readable description of what the product does
- A published catalogue of operations, not a sales page
- A stable address for that catalogue that does not move between releases
How it usually breaks
The capability list lives in a PDF, a Notion page, or a developer portal behind a login. An agent cannot read any of them, so it never learns the operation exists and falls back to driving your UI like a person.
Ask before building: If an agent had never heard of us, what single URL would tell it what we can do?
- 2
Prove standing
Show it is acting for a specific person, with that person’s permission, for a bounded purpose.
What it needs from you
- Credentials an agent can hold that are not the person’s own password
- Scopes narrow enough that delegation is not all-or-nothing
- A way to tell a delegated agent from a scraper without blocking both
How it usually breaks
The only way in is a human login with a one-time code, so the agent either stops or the person hands over their password. Both outcomes are worse than designing for it.
Ask before building: What is the smallest permission that lets an agent do the common task, and can someone grant just that?
- 3
Understand the offer
Work out which operation matches the intention it was sent with, and what that operation needs.
What it needs from you
- Operations named for outcomes rather than internal nouns
- Required inputs stated, with their formats and units
- The preconditions spelled out, not implied by a wizard’s page order
How it usually breaks
The steps make sense only in sequence, because the UI enforced the order. An agent reading the operations alone cannot tell that one must happen before another, so it tries them in the wrong order and fails without knowing why.
Ask before building: Reading only our operation names and inputs, could someone unfamiliar pick the right one on the first try?
- 4
Attempt
Carry out the task, which is the only step most teams design for.
What it needs from you
- An operation that completes without a gesture, a drag, or a visual judgement
- Idempotency, so a retry does not create a second order
- No step that exists solely to slow a human down
How it usually breaks
Something in the middle needs a mouse or a human eye: a drag-to-reorder, a slider, a CAPTCHA, a confirmation that only appears as a visual cue. The agent gets most of the way and stops.
Ask before building: Can the whole task be completed without seeing the layout?
- 5
Interpret the result
Find out whether it worked, and if not, whether the failure is worth retrying.
What it needs from you
- Errors that distinguish "wrong input" from "try again later" from "never going to work"
- The specific field or value at fault, named
- A result that states what actually happened, not just a status code
How it usually breaks
Everything returns a generic failure, so the agent cannot tell a typo from an outage. It retries what will never succeed and gives up on what would have worked a second later.
Ask before building: Does every failure tell the caller which of those three kinds it is?
- 6
Recover
Get back on track without a person, or decide that a person is needed.
What it needs from you
- A way to see current state before acting again
- Reversible operations, or a stated way to undo
- A clear boundary: what an agent may retry alone, and what it must escalate
How it usually breaks
Recovery is possible only through the interface — "go to settings and check" — so an agent with API access has no route back. It either stalls or repeats the thing that failed.
Ask before building: After a half-finished task, can an agent discover what state we are in and continue?
- 7
Hand back
Return to the person 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 surfaced before they are made, not reported afterwards
- Something to show: a reference, a receipt, a link to the thing that changed
How it usually breaks
The agent reports success and the person has no way to verify it. The first time that turns out to be wrong, they stop delegating to it, which costs you the channel rather than the task.
Ask before building: When the agent says it is done, what can the person look at to be sure?
How to use it
Take one task a customer would plausibly delegate — reschedule a booking, reorder a consumable, cancel a plan — and walk it down the seven steps, answering each question honestly for that task alone. Most teams find the first three unanswerable, which is the finding.
Then do it a second time with a task you would not want delegated. Where the two paths diverge is your real policy on agent access, and it is better to write it down than to discover it in production.
See the journey on your own site
The Agent Visualizer walks one of your pages and shows where an agent arrives, where it reads, where it stops, and everything after that it never reaches.
Stay Updated
Analysis of AI search, crawler policy and agent standards — sent when there is something worth reading, roughly twice a month. Unsubscribe anytime.