# Agent Experience (AX) Agent Experience (AX) is the experience [[AI Agents]] have as users of a product or platform: how easily they discover what it does, how reliably they can operate it, and how well they recover when something goes wrong. Mathias Biilmann, CEO and co-founder of Netlify, introduced the term on 28 January 2025 in "Introducing AX: Why Agent Experience Matters", where he defined it as "the holistic experience AI agents will have as the user of a product or platform". He placed it in a lineage. [[Don Norman]] coined "user experience" in 1993, and Jeremiah Lee coined "developer experience" in 2011 (dates as given in Biilmann's post). AX doesn't replace either one; it extends them. [[User Experience (UX)|UX]] is for the humans using a product, DX for the developers building on it, and AX for the agents those humans send to do the work. Leonie Monigatti adds that an agent is often both personas at once: it uses your product AND builds with it. ## Why it matters Agents now act on behalf of people. A developer asks [[Claude Code]] to add email sending to an app, and the agent picks the email provider. Someone asks a chatbot to compare three tools, and the agent recommends one. If the agent can't find your product, can't authenticate, or can't make sense of your errors, it moves on to something else, and the human may never learn your product was an option. Waldek Mastykarz (Microsoft, October 2026) splits this into two questions. Propensity: does the agent find and choose your technology when the task doesn't name it? Efficacy: once it uses your technology, does it use it correctly (e.g., the current API rather than one you deprecated)? Developers judge your product by what the agent produces. When the agent calls a deprecated endpoint or reports success on a broken build, your product looks broken, even if your docs are excellent for people. In his one-year retrospective, Biilmann wrote that every product already has an agent experience, and the only question is whether it's good or bad. I agree with him. If you don't design it, agents get whatever your product happens to expose. ## The four areas Biilmann's retrospective (January 2026) groups the work into four areas: - **Access**: can the agent get into your product on behalf of a user, with the right permissions? Does a human need to [[Human-in-the-Loop|stay in the loop]]? - **Context**: does the model know about your product, and do your docs and your responses give it what it needs to succeed? This is [[Context Engineering]] applied to your product - **Tools**: do you offer interfaces built for agents, and do they reduce friction for the human working through the agent? - **Orchestration**: can your product trigger agent runs, pass context along, and provide sandboxes and environments? Monigatti suggests a practical shift for teams used to UX work: replace the user's emotional curve with failure modes (ambiguous error, auth failure) and with the probability that the agent succeeds at each stage. Her metrics: whether agents pick your product, how many tokens they burn, and how many feedback loops they need. ## Building blocks Most of these are existing engineering practices that agents depend on: - Machine-readable docs: the [[llms.txt convention|llms.txt]] file (proposed by Jeremy Howard in September 2024), plain-text or [[Markdown]] mirrors of every docs page, and content negotiation that returns Markdown when an agent asks for it - Agent-facing interfaces: [[Model Context Protocol (MCP)|MCP]] servers (introduced by [[Anthropic]] in November 2024, donated to the [[Linux Foundation]]'s [[Agentic AI Foundation (AAIF)]] in December 2025), clean and well-described APIs, [[AI Agent Skills|Agent Skills]] and [[WebMCP]] - [[Command Line Interface (CLI)|CLIs]] designed for agents: no interactive prompts, structured output, explicit empty states, stable exit codes. The AXI project (Kun Chen) defines 10 principles for agent-native CLIs that treat the [[Token Budget|token budget]] as a first-class constraint. On its own GitHub benchmark (425 runs with Claude Sonnet 4.6), its `gh-axi` reached 100% task success, against 86% for the regular [[GitHub CLI (gh)|`gh` CLI]] and 87% for the GitHub MCP server - Programmatic auth: tokens an agent can obtain and scope without a human clicking through a browser flow - Safe mutations: [[Idempotency|idempotency keys]], so a retry doesn't create a duplicate order, and dry-run modes, so the agent can check what would happen before it acts - Errors that teach: structured error messages that say what went wrong and how to fix it, so the agent corrects itself instead of guessing - Discovery metadata: machine-readable descriptions of what you offer, such as [[Agentic Resource Discovery Specification (ARD)|ARD]] catalogs. [[IsItAgentReady]] scores a website against many of these standards ## Shipping an MCP server is the easy part The O'Reilly Radar article "Stop Getting Good at Protocols. Get Good at Agent Experience." (June 2026) argues that, in 2025, many teams treated "we have an MCP server" as their agent strategy. According to the article, the protocol worked and the design behind those servers was weak. This is the part of AX I care about most. The evidence it cites comes from a February 2026 paper by Hasan et al. (Queen's University), "Model Context Protocol (MCP) Tool Descriptions Are Smelly!". The authors examined 856 tools across 103 MCP servers: 97.1% of the tool descriptions had at least one quality issue, and 56% didn't clearly state what the tool was for. Rewriting the descriptions raised the median task success rate by 5.85 percentage points. The same paper also reports the costs, which the O'Reilly article doesn't mention: 67.46% more execution steps, and worse results in 16.67% of cases. Better descriptions help, but you still have to measure. A valid MCP endpoint that returns opaque errors gives agents a bad experience. A plain CLI with clear help text and error messages that say how to fix the problem can give them a great one without any protocol at all. Protocols keep changing (MCP, Skills, [[Agent2Agent Protocol (A2A)|A2A]], and whatever comes next). The design questions stay the same: how does the agent discover what you do, understand where the boundaries are, recover when it fails, and avoid wasting tokens on useless round trips? Mastykarz describes a case where measuring changed the fix. Running SharePoint Framework (SPFx) upgrades in [[GitHub Copilot]] Chat, the agent passed 30 of 80 configuration checks. Telling it to use the CLI for Microsoft 365 raised that to 75 of 80. The agent's trace showed it read the SPFx release notes while it worked, so the team updated the release notes instead of shipping a skill, and from then on every run used the CLI without being told. Fixing the docs reached every developer; a skill would only have reached those who installed it. Netlify built AXIS, an open source scoring framework that runs real agents against real scenarios, for the same reason. ## My take: agents are first-class users I strongly believe agents are becoming a primary user type of software. They act on behalf of humans, they choose which tools to use, and they recommend products. A product that agents can't discover, operate or recover in will lose to one they can, and often nobody will notice why. That's why AX should be designed in from the start, next to the human UI, and NOT bolted on later as an "AI integration". In practice: - Every capability a human can reach through the UI should also be reachable through a documented, scriptable surface (CLI, API or MCP) that applies the same rules and returns the same validation errors - Docs, error messages, help text and changelogs now have two kinds of readers: humans and agents. Write them for both - Treat agent failures as product bugs, the same way you treat a confusing screen This is how I build my own tools. The [[Obsidian Starter Kit plugin for Obsidian|Obsidian Starter Kit plugin]] has a settings UI for humans, and it also ships `osk-cli` (a cross-platform CLI), an MCP server on `127.0.0.1:27125` and a plugin API, all working from the same note type definitions. In my vault, agents don't guess where a note goes: they ask `osk-cli` for the folder, template and sections of a note type, then check the result with `osk-cli validate`. My [[Agentic Resource Discovery Server plugin for Obsidian|Agentic Resource Discovery Server plugin]] turns my 500+ AI Skills into a local, searchable ARD catalog, so agents fetch the one skill they need instead of loading all of them into their [[Context Window|context window]]. And my [[Obsidian CLI REST MCP plugin for Obsidian|Obsidian CLI REST MCP plugin]] exposes every [[Obsidian CLI]] command through only two MCP tools (`search` and `execute`), no matter how many commands exist, to keep the agent's context small. ## A second meaning "Agent experience" also circulates with a different meaning: the experience of humans working with agents (how you supervise, review and steer them). That's a real design problem too, but it belongs to the UX of agent tools. In this note, AX means the agent as the user. ## References - Mathias Biilmann, "Introducing AX: Why Agent Experience Matters" (28 January 2025): https://biilmann.blog/articles/introducing-ax/ - Mathias Biilmann, "One Year of AX" (28 January 2026): https://biilmann.blog/articles/one-year-of-ax/ - Netlify, Agent Experience page and FAQ: https://www.netlify.com/agent-experience/ - Agent Experience community site (initiated by Netlify): https://agentexperience.ax/ - Waldek Mastykarz, "What is Agent Experience (AX)?", Microsoft for Developers (6 October 2026): https://developer.microsoft.com/blog/what-is-agent-experience-ax/ - O'Reilly Radar, "Stop Getting Good at Protocols. Get Good at Agent Experience." (24 June 2026): https://www.oreilly.com/radar/stop-getting-good-at-protocols-get-good-at-agent-experience/ - Leonie Monigatti, "Agent Journey Map: Designing Software for AI Agents": https://www.leoniemonigatti.com/blog/agent-experience.html - Hasan, Li, Rajbahadur, Adams and Hassan, "Model Context Protocol (MCP) Tool Descriptions Are Smelly! Towards Improving AI Agent Efficiency with Augmented MCP Tool Descriptions" (arXiv, February 2026): https://arxiv.org/abs/2602.14878 - AXI: Agent eXperience Interface, 10 principles and benchmarks (project's own results): https://github.com/kunchenguid/axi and https://axi.md/ - llms.txt proposal: https://llmstxt.org/ ## Related - [[AI Agents]] - [[AI Agents (MoC)]] - [[User Experience (UX)]] - [[Agent-Native Product Decomposition]] - [[Context Engineering]] - [[Model Context Protocol (MCP)]] - [[AI Agent Skills]] - [[Command Line Interface (CLI)]] - [[llms.txt convention]] - [[WebMCP]] - [[Agentic Resource Discovery Specification (ARD)]] - [[IsItAgentReady]] - [[Is Agentic]] - [[Generative Engine Optimization (GEO)]] - [[Obsidian Starter Kit plugin for Obsidian]] - [[Agentic Resource Discovery Server plugin for Obsidian]] - [[Obsidian CLI REST MCP plugin for Obsidian]]