Designing APIs for AI agents

For many years, we designed APIs for two kinds of consumers, human developers and other applications. In 2026, there is a third consumer, and it is growing fast. AI agents. As you already know, most developers now use AI in their day to day work, but only a small number of teams design their APIs with AI agents in mind. This gap is a big problem, and also a big opportunity.

In this post, I will share what I think changes when an AI agent calls your API, and what you can do about it.

What is an AI agent?

An AI agent is a program powered by a large language model (LLM) that can take actions on its own. For example, an agent can:

• Search insurance quotes from different providers and compare policies
• Read your support tickets and reply to customers
• Pull sales data from three systems and build a report

To do these things, the agent needs to call APIs. Your APIs.

How agents are different from human developers

A human developer reads your documentation multiple times, writes code, tests it, and deploys. An agent works differently:

1. Agents read your API in real time.

An agent does not spend a week studying your docs. It looks at your API description at the moment it needs it. If your endpoint names and descriptions are unclear, the agent will make mistakes.

2. Agents call APIs at machine speed.

One agent can make hundreds of calls in a minute. It can also retry in loops if something goes wrong. Your rate limits and error handling need to be ready for this.

3. Agents cannot ask you questions.

A developer can email you when the docs are confusing. But an AI agent cannot. Everything the agent needs must be in the API contract itself.

4. Agents follow instructions literally.

If your error message says "try again later", an agent may try again every second, may be forever. Clear, specific responses are more important now.

Design checklist for agent-friendly APIs

1. Accurate OpenAPI/protobuf spec?

Agents learn your API from its machine-readable contract. If your OpenAPI spec is missing, outdated, or wrong, agents will fail. Keep the spec as the single source of truth and generate it from code, or better, write the spec first.

2. Clear descriptions

Every endpoint, parameter, and response field needs a plain description. Write for a reader with zero context. An agent does not know that "txn" means "transaction" in your company.

3. Operations named by what they do

GET /customers/{id}/orders tells an agent exactly what it gets. POST /api/v2/process tells it nothing. Clear resource names and correct HTTP methods are the cheapest agent-readiness win you can get.

4. Safe and unsafe operations

An agent must know which calls only read data and which calls change data. Use GET and QUERY for reads. Use POST, PUT, PATCH, and DELETE for writes. Never hide a data change inside a GET.

5. Safe idempotent

Support idempotency keys so the system is safe from repeated requests. Without idempotency, a timeout on "create order" leaves the agent not knowing whether the order exists or not, so it retries, and now the customer has two orders.

6. Self-explanatory errors 

Agents act on your error messages. Good error responses include:

• A correct HTTP status code and a stable error code (like 429 with RATE_LIMIT_EXCEEDED)
• A human-readable message
• What to do next (like a retry_after value)

7. Guided rate limits

Agents can send hundreds of calls per minute. Return standard rate limit headers so the agent knows how fast it can go. A hard block with no information leads to retry storms. Rate limit headers (X-RateLimit-Remaining, Retry-After) let API consumer to self-throttle before reaching its limits. 

8. Identify agents vs humans vs systems?

Your logs and analytics should show which traffic comes from agents. This helps with cost control, security, and capacity planning. Consider separate API keys or user-agent rules to identify AI-driven clients.

9. Fine-grained permissions

An agent should get the smallest access it needs. If an agent only needs to read invoices, it should not have a token that can delete or update customers. Scoped tokens and fine-grained authorization are a must.

Final thoughts

None of these points are unusual requirements for a good developer. Most of them are simply good API design and best practices that we should have been following all along.

As a best practice, I normally follow the Australian Government API Design Standard. How about you?