Agent-First API Design.

For thirty years, "API-first" meant designing clean interfaces for human developers. Good docs, predictable endpoints, stable schemas, sensible errors. In the agentic era, the primary consumer of your API is no longer a developer at all. It is an autonomous system that has to discover, decide, act, recover, and explain. That changes what good API design means.

---

01 · From API-first to agent-first

API-first design assumed a human in the loop. The developer reads the docs, understands the business context, writes the glue code, catches the errors, and decides when an action is safe. Every soft surface of an API — naming, errors, examples, edge cases — was tuned to that one user.

Agentic systems break the assumption. An AI agent does not browse documentation, does not have institutional memory, and does not know which endpoints are reversible. It infers, plans, calls tools, chains actions, and operates across systems it has never seen before. The agent is fast, persistent, and confidently wrong in ways a developer rarely is.

We call the discipline that emerges from this shift Agent Experience (AX) — the practice of designing APIs, tools, schemas, permissions, errors, and capability descriptions so autonomous agents can use them safely, reliably, and explainably. Where AUX (Agentic User Experience) governs how humans and agents collaborate at the product surface, AX governs how agents and software systems negotiate underneath it.

API-first asks: "Can a developer integrate this?" Agent-first asks: "Can an agent use this without creating chaos?"

These are not the same question. And the products that answer the second one well will be the platforms of the next decade.

---

02 · API-first vs agent-first

The shift is not cosmetic. It rewires the contract between software systems. An API-first surface treats the developer as the intelligence layer. An agent-first surface assumes the intelligence is on the other end of the wire — probabilistic, fast, and operating without a coffee break.

---

03 · Why APIs built for humans break agents

The same APIs that score 9/10 on developer experience routinely score 3/10 on agent experience. Six patterns explain almost all the failures.

1. Ambiguous endpoint names. Humans infer nuance from context. Agents overgeneralize. update_contact will be called for things that should never touch a contact record.

2. Schemas that describe data, not intent. A field called status is not enough. What does changing it do? Who is affected downstream? Is it reversible? Without the answer, the agent has to guess — and it will.

3. No asymmetry between read and write. Reading is usually low-risk. Writing, sending, deleting, charging, publishing — these need trust boundaries the agent can see. Flat capability surfaces hide them.

4. Errors that help debugging, not recovery. 400 Bad Request is a useful signal to a developer with a stack trace. It is useless to an agent that needs to replan. Agents need errors that name what is missing and suggest the next valid move.

5. No escalation path. APIs rarely tell agents when not to proceed. There is no signal for "this is a confirmation-required action" or "this requires a human approver." The agent has to learn it the hard way — usually in production.

6. Documentation written for humans only. PDFs and Stripe-style guides are great for developers. Agents need machine-readable capability descriptions: purpose, allowed use cases, disallowed use cases, side effects, examples, escalation rules. The Model Context Protocol exists precisely because this layer was missing.

Each failure is a design choice, not a model limitation. Fix the design, and the same model behaves dramatically differently.

---

04 · The six principles of agent-first API design

These are the principles we apply when designing an Agentic API Experience — whether the surface is REST, GraphQL, an MCP server, or a tool-calling layer over a legacy system.

Principle 01 — Design actions, not endpoints

Instead of exposing only:

PATCH /contacts/{id}
POST  /emails
GET   /deals

Expose an action layer the agent can reason about:

enrich_contact_profile
draft_follow_up_email
summarize_deal_risk
request_human_approval

The point is not to hide REST. The point is to give the agent a vocabulary that maps business intent to system capability. The endpoints stay; an action surface sits above them.

Principle 02 — Make consequences explicit

This is the API-layer counterpart to the AUX principle Clarify Before Commit: before high-stakes actions, the agent — or the API — pauses and confirms intent. Intelligent friction that protects time, reputation, and trust.

Principle 03 — Separate read, suggest, and execute

A mature agent-facing API distinguishes three modes for the same business operation:

read_customer_data        // observe
suggest_account_update    // propose with rationale
execute_account_update    // act, with audit trail

This separation gives product and engineering a clean autonomy ladder — the API-layer expression of the Control vs Autonomy map. Different operations live at different rungs: read autonomously, suggest with reasoning, execute with confirmation, block dangerous operations entirely. The product can promote and demote actions on the ladder as trust accumulates, without redeploying.

Principle 04 — Build for recovery, not just success

Agents will call the wrong thing, miss context, hit permissions, or discover conflicting data. Design the error surface deliberately.

Bad:

{ "error": "Invalid request" }

Agent-first:

{
  "error": "missing_required_context",
  "missing_fields": ["company_id", "approval_reason"],
  "safe_next_steps": [
    "lookup_company_by_domain",
    "ask_user_for_approval_reason"
  ],
  "retryable": true,
  "human_escalation": false
}

Same condition. Completely different downstream behavior. The first triggers retries and hallucinated parameters. The second triggers a sensible plan.

Principle 05 — Make capabilities discoverable

Agents need to know what tools exist, when to use them, and — equally important — when not to use them. Each tool descriptor should encode purpose, allowed use cases, disallowed use cases, required context, examples, side effects, and escalation rules. This is the structural reason MCP matters. Treating it as plumbing misses the point — it is a schema for trust.

Principle 06 — Design trust into the API

For every action, the API should make four answers unambiguous:

• Can the agent read this?
• Can it write this?
• Can it act autonomously, or does it need confirmation?
• Who approves, what is logged, what can be undone?

This is the same trust ladder we design at the product layer — Functional, Contextual, Judgment, Advocacy — pulled down into the schema. When trust is encoded as structure, autonomy becomes a configuration, not a leap of faith.

---

05 · A worked example — turning a CRM API into an agent-first surface

Most CRMs expose a developer-grade API: a few hundred endpoints, REST or GraphQL, well-documented, and almost entirely flat.

Traditional surface:

GET   /contacts/{id}
PATCH /contacts/{id}
POST  /tasks
POST  /emails
GET   /deals

Hand this to a sales agent and you get exactly what you would expect: contacts updated for the wrong reasons, emails drafted without context, deals modified in ways no rep can later explain.

Agent-first surface — the action layer above the same primitives:

analyze_lead_fit
summarize_contact_history
recommend_next_best_action
draft_sales_followup
request_rep_approval
send_approved_followup
log_followup_outcome

Each action carries its consequence schema. draft_sales_followup is reversible and autonomous. send_approved_followup is irreversible and requires approval from a specific human role. recommend_next_best_action is read-only and returns its reasoning trace. The agent does not need raw access to every CRM operation. It needs a safe action vocabulary that maps business intent to system capability — and a permission topology that says which actions it can take without asking.

The traditional API is still there underneath. But the agent never touches it directly.

---

06 · The agent-first API checklist

For every API or tool surface you expose to an agent, run it through these ten questions. If you cannot tick every box, you have not yet designed the surface — you have designed half of it.

The list is short on purpose. The discipline is in applying it to every endpoint, not in expanding the list.

---

07 · Why this is the new developer experience

For the last decade, "developer experience" meant SDKs, status pages, ergonomic clients, and Stripe-quality docs. That bar still matters. But there is a new bar above it.

The companies that will define the agentic era — across CRM, finance, advertising, ops, ad-tech, security, RevTech — are the ones that treat their API as an agent-facing surface, not just a developer-facing one. They invest in action layers, consequence schemas, recovery semantics, capability discovery, and trust topology with the same seriousness that the last generation invested in documentation.

In the API-first era, the API was the contract between software systems and developers.

In the agentic era, the API becomes the contract between software systems, AI agents, and human trust.

The winners will not simply expose more endpoints. They will design better action surfaces: interpretable, constrained, recoverable, and safe for agents to use.

That is agent-first API design. That is Agent Experience. That is the new DX.

---

08 · How we work on this

auxfirst designs Agentic API Experience surfaces for teams shipping infrastructure for the agentic era — from MCP-ready tool layers to action vocabularies built on top of legacy APIs.

Two engagements typically apply:

If you are building infrastructure other teams will build agents on top of, we should talk.

---