Artificial Intelligence
Designing APIs for AI Agents: Your API Is a User Interface Now
Nobody would ship a screen that dumps every column of every legacy record into one giant table and call it a user experience. Yet that is what many integration teams ship as an API: the old record, field for field, behind a new URL. It was a poor interface when the only callers were other developers. Designing APIs for AI agents makes the problem impossible to ignore, because the caller is now a language model reading your names, your descriptions and your error messages to decide what to do next.
The short answer: treat the API as a user interface and design it for the people and agents who use it. Don’t wrap a legacy message format in REST and call it modern. Render from your domain model through two adapters, one that keeps existing integrations working and one that exposes clean, resource-oriented operations. Then shape that new surface for a caller that reads descriptions, recovers from errors and works through a problem over several turns.
An API Is a User Interface
Every interface makes choices about what the user sees, in what words, and what happens when they get it wrong. A screen makes those choices for a person; an API makes them for a program and the developer who wrote it.
When those choices go unmade, the API exposes whatever the storage layer holds: cryptic column names, codes that only mean something inside the building, and twenty fields where the caller needed three. Developers cope by asking someone and hard-coding the answer, and every team that integrates pays that cost again.
An AI agent copes worse. It cannot walk down the hall and ask what STS_CD = 4 means. It reads what you published and acts on it.
Why a REST Wrapper Over a Legacy Interface Isn’t Modernization
A common modernization plan goes like this: the system already speaks a legacy message format (an HL7 v2 feed, an EDI X12 exchange, a fixed-width file, a SOAP service built around one giant document), so put a REST layer on top that accepts JSON, translates it into the old message, and translates the reply back.
It looks modern from the outside. Underneath, three things go wrong.
- The data is rendered twice. The core system builds the legacy message, then the wrapper parses it and builds something else. Every field passes through a format nobody wanted, and every translation is a place for meaning to slip.
- The new API can only say what the old format can carry. If the legacy message has no place for a field, the REST layer has nothing to return. If the message bundles ten things together, the wrapper either returns all ten or re-implements the logic to pick one apart. The new interface is hamstrung by the old one.
- It is still record exchange, not an API. Many legacy interfaces were designed to move packaged bundles between systems: an admission, a shipment, an invoice, each tiered and specific to one workflow. A modern API offers discrete resources and operations a caller can combine. Wrapping a bundle in JSON does not turn it into a resource.
Healthcare shows the gap clearly. HL7’s own FHIR standard defines all exchangeable content as resources, unlike the message-oriented design of HL7 v2. A REST shim over a v2 feed does not get you FHIR’s model, only v2’s limits in a newer syntax. (For how the healthcare formats differ in practice, see our guide to HL7, FHIR and X12 integration.)
Render From the Domain, Through Two Adapters
The better design starts one layer down. Your system already has domain objects, or at least database rows that represent real things: customers, orders, appointments, shipments. Render from those directly, and put two adapters at the edge.
| Adapter | Who it serves | What it emits |
|---|---|---|
| Legacy adapter | Existing integrations that cannot change on your schedule | The legacy message format, byte for byte as before |
| Resource adapter | New consumers: partner developers, your own front ends, AI agents | Discrete resources and focused operations, named for the business |
Neither adapter depends on the other. The legacy feed keeps running, so nothing breaks for partners who are not ready to move. The new API is free to model the business as it is, not as a twenty-year-old message spec described it. This is the ports-and-adapters idea Alistair Cockburn described in his Hexagonal Architecture paper: keep the core independent of the things that drive it, so a new kind of caller is a new adapter, not a rewrite.
A translation layer still has a place when the core genuinely cannot change, such as a vendor system you do not own. Make it a decision you reach, not the plan you start with: if you own the core, rendering a second format from it is usually less work than maintaining a wrapper for the life of the system. The same incremental thinking applies to the rest of the system; we cover it in modernizing legacy systems without a rewrite.
What Changes When the Caller Is an AI Agent
Agents reach your system in two main ways. Through the Model Context Protocol (its 2025-06-18 revision), a server exposes tools that a language model discovers and calls; each tool carries a name, a human-readable description and a JSON Schema for its inputs. Through agent-to-agent protocols such as Google’s Agent2Agent (A2A), one organization’s agent talks to another’s.
Either way, the consumer is reading natural language, not a record layout. That changes what good design means.
Descriptions are part of the interface. A model chooses a tool largely from its name and description. “Get record” with an undocumented ID parameter is a guess. “Find open appointments for a service location within a date range” is a decision the model can make.
Errors are instructions. The MCP specification separates protocol errors from tool execution errors, which come back in the result with isError set so the model can see what failed. An error that says “invalid request” ends the conversation. An error that says “date range cannot exceed 31 days; split the request” lets the agent fix its own call. For plain HTTP APIs, RFC 9457 Problem Details gives the same idea a standard shape.
The interaction is a negotiation, not a single call. Picture a partner’s agent that needs to book a service visit. It sends a customer, a preferred week and a photo of a document. Your side does not have enough to commit, so it asks for the account number and the site address. The partner’s agent supplies them, your side offers three slots, and they settle on one. That is several turns of back-and-forth, each one shaped by what your API said in the turn before. An API built for one-shot record exchange has no way to ask a question back.
Designing APIs for AI Agents: A Checklist
Most of what makes an API work well for agents also makes it better for developers. Use this list to review an existing API, or an MCP server design, before an agent ever calls it.
- Name resources and operations for the business.
cancel_shipment, notupdateStatuswith a magic code. A caller should be able to guess what an operation does from its name. - Write descriptions for a reader with no context. Say what the operation does, when to use it, what each parameter means, and what it will not do.
- Keep operations small and focused. One operation that does one thing is easier for a model to choose correctly than one that does six things depending on a flag.
- Return errors that say what to do next. Name the field, the rule it broke and the fix.
- Make writes idempotent. Agents retry. Accept an idempotency key on any operation that creates or changes something, so a retry never books the same appointment twice.
- Paginate the same way everywhere. One cursor convention across every list operation, so an agent that learns it once can use it everywhere.
- Return only what the caller needs. Offer a summary shape and let the caller ask for detail; large payloads crowd a model’s context.
- Mark what is safe. Distinguish read-only operations from ones that change data or cannot be undone, so the client can put a person in the loop where it matters.
- Write the contract first. Agree the schema, the names and the errors before the code. Contract-first design keeps both adapters honest and gives the agent a description you meant to publish.
Security belongs in the same conversation. An agent calling your API is a non-human identity acting on someone’s behalf, and it needs scoped credentials, rate limits and an audit trail like any other integration. If you plan to expose an MCP server to partners, decide early where it sits in your infrastructure; we walk through one approach in running an MCP server behind an API gateway.
Don’t Bet the Design on One Agent Protocol
MCP and A2A solve different problems. A2A has moved from Google’s announcement to a Linux Foundation project, and Google describes it as complementing MCP rather than replacing it. Both are evolving, and others will appear.
The two-adapter design is the hedge. With a clean domain model and a well-described resource API, an MCP server or an A2A endpoint is one more thin adapter over the same core. With only a wrapper around a legacy message, every new protocol means translating that message again. Choose the protocol for the partners you need to reach, and keep the design in the domain layer, where no protocol owns it.
Frequently Asked Questions
Can we just expose our existing REST API to AI agents?
Often, as a start. Review it the way you would review a screen: are the names meaningful, do the descriptions explain when to use each operation, and do the errors tell the caller how to recover? An API that needs a developer’s tribal knowledge to use will confuse an agent faster than it confused the developer.
Should we build for MCP or A2A?
Build the domain model and resource API first, then add the protocol your partners and tools actually use. MCP connects an agent to tools and data; A2A connects agents to each other. Many systems will want both, as separate adapters over the same core.
Where to Start
Pick one integration that partners or internal teams complain about, and look at it as a user interface. What would a caller need to see, in what words, to use it without asking anyone? That answer is the first draft of the resource adapter.
If your team has the roadmap but not the capacity to rework an integration layer, that is the work we do alongside in-house IT. See how we work as an engineering partner for IT teams and how we approach AI implementation, or book a discovery call to talk through your API.
Newsletter
Subscribe to newsletter
Subscribe to receive the latest blog posts to your inbox every week.
