Build For Agents, Not Screens: Agent Experience (AX) And Agent-First API Design In Code

89% vs 24% - Developers using generative AI daily versus those designing their APIs with AI agents in mind  ·  APIs, MCP, CLI - Salesforce's Headless 360 exposes data, workflows and business logic to agents without a screen  ·  AX ⊃ DX - Agent experience is a superset of developer experience - same foundations, stricter requirements  ·  Standards landing - MCP under the Linux Foundation, Agent Skills as a standard, a Cloudflare discovery RFC weeks old

Every API was designed for a caller, and for twenty years that caller was a developer: a person who read the docs, understood the domain, wrote the integration once, tested it, and handled the edge cases with judgement. In 2026 a second caller has arrived that does none of those things the same way. An AI agent discovers your API at runtime, reads your documentation as instructions, calls operations in sequences you did not anticipate, retries when confused, parallelises when it can, and acts on behalf of a person who may never see your interface at all. The surveys capture how unprepared most teams are for this: 89% of developers now use generative AI in their daily work, but only 24% design their APIs with AI agents in mind. Meanwhile the platforms have moved decisively. Salesforce's Headless 360 decouples its backend from its interface and exposes data, workflows and business logic as APIs, MCP tools and CLI commands - software built to be operated by agents. The Model Context Protocol, donated to the Linux Foundation, gives agents a standard way to discover and call tools. Agent Skills emerged as a standard for packaging capabilities early this year, and Cloudflare's discovery RFC - a proposal for how agents find what a service offers - landed only weeks ago. The discipline this adds up to has a name, agent experience or AX, and it is a superset of developer experience with harder requirements. As an AI Agency Developer London that builds both the agents and the systems they call, we think agent-first API design is the most consequential architecture shift of the year, and this flagship playbook is the engineering.

Discovery: How An Agent Learns What You Can Do

The first question an agent asks of any system is 'what can you do?', and agent-first design answers it in a form the agent can consume without a human. The emerging pattern has two layers. A well-known discovery endpoint - the direction of the Cloudflare RFC and of the agent-card convention in agent protocols - publishes a machine-readable manifest of the capabilities a service offers, so an agent (or the orchestrator routing to it) can find and evaluate it before calling anything. And each capability is described as a tool, in the MCP sense: a name, a precise natural-language description of what it does and when to use it, a typed input schema and a typed output schema. The description is the part most teams get wrong, because it is not documentation for a human skimming a reference - it is a prompt. An agent decides whether to call your operation, and how, from those few sentences, so they must state the purpose, the preconditions, the side effects and the cases where the tool should not be used, in the plain declarative language a model reads best. The input schema does similar work: enums instead of free strings, required fields explicit, constraints encoded, descriptions on every field. Salesforce exposing its functionality as MCP tools and CLI commands alongside APIs is the reference for the destination: the same capability offered through whichever surface the agent can use, all described well enough that no human needs to explain it.

• Publish a machine-readable capability manifest at a well-known location so agents and orchestrators can discover you before calling.
• Describe every operation as a tool - name, purpose, when to use and when not to, side effects - and treat the description as a prompt.
• Type everything - input and output schemas with enums, constraints and per-field descriptions; free-form strings are where agents go wrong.
• Offer the same capability through multiple agent surfaces - API, MCP tool, CLI - described consistently.
• Version the manifest and tool definitions like an API contract, because agents cache and reason over them.

Operations Designed For Autonomous Callers

Once an agent knows what you offer, the design of each operation determines whether autonomous use is safe. The single most important property is idempotency: agents retry, orchestrators replay, and durable workflows resume, so any operation with a side effect must accept an idempotency key and guarantee that repeating a call with the same key produces the same result once. Without this, an agent that times out on 'create invoice' and retries creates two invoices, and that failure will happen. The second property is explicit preconditions and dry-run: an agent composing a sequence benefits enormously from being able to ask 'would this succeed, and what would it do?' before committing, so a validate or dry-run mode on consequential operations turns guesswork into planning. The third is bounded, predictable pagination and limits: agents that pull data must be able to page deterministically with cursors, know the maximum they can request, and never be handed an unbounded response that blows their context. The fourth is granularity: operations should be sized so that one call accomplishes one meaningful step - fine-grained enough to compose, coarse-grained enough that the agent is not forced into ten calls for one intent - and the common multi-step intents (create-and-send, lookup-then-update) deserve first-class operations rather than being left for the agent to orchestrate fragilely. And the fifth is consequence gating: operations that move money, delete data or contact customers should require an explicit confirmation parameter or a two-step commit, so that an agent cannot stumble into them, and so a human approval step has a natural place to sit.

Errors, Identity, Limits And Observability

Four more concerns separate an API agents can use from one they merely can call. Errors must be recoverable by a machine: a structured error with a stable code, a human-readable message, the field or precondition that failed, and - crucially - a hint about what to do next (retry after a delay, supply a missing field, call a different operation first), because an agent that receives 'bad request' is stuck and an agent that receives 'missing customer_id; call lookup_customer first' can recover. Identity must be agent-aware: each agent gets its own credential with scopes limited to the operations and data its task needs, tokens are short-lived and, where the agent acts for a person, carry the delegating user's identity so authorisation is the intersection of what the agent may do and what the person may do - never a shared service key with everything. Rate limits must fail gracefully and legibly: return the limit, the remaining budget and the reset time in headers an agent can read, and prefer slowing an agent down to cutting it off mid-task. And observability must attribute: every call tagged with the agent, the delegating user and a correlation identifier for the task, so that when an agent does something wrong you can reconstruct the sequence and when it does something expensive you can see who to bill. These are the concerns that determine whether an organisation can safely let agents operate its systems at scale - which is exactly what headless software promises and exactly what most APIs are not yet ready for.

The Bottom Line

Agents are the new callers of every API, and the gap between 89% of developers using AI and 24% designing for it is the gap between organisations whose systems agents can operate and those whose systems they cannot. The platforms have chosen: Salesforce's Headless 360 offers its capabilities as APIs, MCP tools and CLI commands rather than screens, MCP and Agent Skills are standards, and discovery is being formalised. Agent experience is a superset of developer experience with stricter requirements, because an agent rediscovers your API every session, cannot read between the lines, retries, composes autonomously and acts with delegated authority. Designing for it is concrete: a machine-readable capability manifest and tool descriptions written as prompts with typed schemas; operations that are idempotent, offer dry-run, page predictably, are sized to intents and gate consequences; errors that tell an agent how to recover; agent-scoped, short-lived, delegated identity; rate limits that slow rather than sever; and observability that attributes every call. And it can be reached by layering onto an existing API - manifest first, idempotency second, errors, dry-run, identity - without breaking a single human client. Every one of these changes also makes the API better for people, which is the quiet truth of AX: building for agents is simply building well, held to a standard a machine cannot forgive. Building systems agents can operate, and agents that operate them, is exactly the work we do.

References & Further Reading

• WorkOS - agent experience: how to design products that agents can actually use (89% vs 24%): https://workos.com/blog/agent-experience-oujuh
• Stainless - steps toward great agent experience every API provider can take today: https://www.stainless.com/blog/steps-toward-great-agent-experience-every-api-provider-can-take-today
• Apideck - API design principles for the agentic era: https://www.apideck.com/blog/api-design-principles-agentic-era
• Salesforce Trailhead - APIs, CLIs and Skills for agent-ready development (Headless 360): https://trailhead.salesforce.com/content/learn/modules/headless-tools-and-functionality/learn-about-salesforce-apis-clis-and-skills
• MindStudio - how to build an agent-first product: lessons from Stripe, Google and Anthropic: https://www.mindstudio.ai/blog/how-to-build-agent-first-product-design-principles