According to Gartner, more than 30% of the growth in API demand by 2026 will come from AI and tools using large language models. That figure reflects a reality every technical team sees in practice: APIs no longer serve only to connect interfaces to databases. They are becoming the connective tissue between business applications, LLMs and autonomous agents. An API poorly designed for these new uses does more than produce slow responses: it generates hallucinations, tool routing errors and soaring token costs.
This article details the API design patterns that actually work in AI projects, the antipatterns that sabotage integrations, and the practical trade-offs between REST, GraphQL, WebSocket and MCP for connecting systems to LLMs and agents.
TL;DR: For AI projects, favor REST with semantically rich OpenAPI schemas for agent interoperability, SSE for token streaming, and MCP for dynamic tool discovery. Avoid chatty APIs, unstructured responses and endpoints without descriptions models can use.
Why API Design Changes Radically with AI
The API Consumer Is No Longer Human
For two decades, APIs were designed for human developers who read documentation, understand implicit context and adapt their calls based on errors. An LLM or AI agent works differently. It selects a tool from a function catalog, generates a structured JSON call, then interprets the response to decide what to do next.
This fundamental difference imposes three new constraints on API design. First, every endpoint must be self-describing: its name, description and parameter schema must be enough for the model to understand when and how to use it. Second, responses must be predictable and structured: an LLM cannot parse HTML or guess the meaning of a poorly named field. Third, error handling must provide machine-actionable context, rather than a generic message intended for a human who will consult the logs.
Exploding Demand: Numbers That Speak for Themselves
Driven by AI, the API market is accelerating at an unprecedented rate. According to Market Data Forecast, the global API management market reached $10 billion in 2025 and is expected to exceed $108 billion by 2033, an annual growth rate of 34.7%. Gartner estimates that more than 80% of companies will have used generative AI APIs or deployed GenAI applications in production by 2026, compared with less than 5% in 2023.
For technical teams, this means the APIs you design today will be consumed by AI agents tomorrow, even if that is not your immediate use case. Designing APIs that are ready for agents has become architectural insurance rather than a luxury.
What Agents Expect from Your APIs
An AI agent interacts with an API in three distinct phases. First, discovery: it consults a tool catalog (functions, endpoints) and selects the tool matching the user's intent. Next, invocation: it generates a structured call with the right parameters. Finally, interpretation: it analyzes the response to decide its next action—call another API, ask for clarification or return a result to the user.
Each phase can fail if the API was not designed for this interaction model. An ambiguous function name causes the wrong tool to be selected. An incomplete parameter schema leads to malformed calls. A poorly structured response blocks the agent's reasoning chain.
REST, GraphQL, WebSocket: Which Protocol for Which AI Use Case?
REST: The Universal Foundation for Agent APIs
REST remains the default choice for APIs intended for AI agents, for good reasons. Its compatibility with the OpenAPI specification makes it the protocol LLMs can use most directly. An OpenAPI specification can be automatically converted into function definitions for any major LLM provider—OpenAI, Anthropic, Google—making your API immediately usable by agents.
In performance terms, REST handles around 20,000 simple requests per second on standard production hardware, with median latency of 250 ms according to SmartDev benchmarks. These figures are more than sufficient for most AI agent use cases, where the LLM's own response time, often 1–5 seconds, dominates the total.
REST's main advantage for AI projects lies in its ecosystem. API gateways, documentation tools, rate limiting and authentication mechanisms are mature and proven. When an agent must call 15 different APIs in a workflow, REST standardization considerably reduces integration complexity.
GraphQL: Powerful but Risky with LLMs
GraphQL excels in one particular scenario: complex data aggregation. According to available benchmarks, GraphQL can reduce API call counts by 60% in complex aggregation scenarios, such as combining outputs from multiple models or powering data-intensive ML dashboards.
However, GraphQL poses specific challenges for AI agents. An LLM must generate a syntactically correct GraphQL query, which is significantly more complex than filling in REST call parameters. The N+1 problem, where one query triggers dozens of database subqueries, is amplified when an agent generates queries without awareness of performance implications. Caching is more complex than with REST, potentially creating unexpected infrastructure costs.
GraphQL is justified in AI projects when the frontend consumes data from multiple models with dynamic filtering needs, typically an AI analytics dashboard. For standard agent–API interactions, REST offers a better balance of simplicity and efficiency.
WebSocket and SSE: Real-Time Token Streaming
Streaming is fundamental to AI applications. No user accepts waiting 8 seconds for an LLM to generate its entire answer before seeing the first word. Two protocols compete for this use case: WebSocket and Server-Sent Events (SSE).
SSE has become the de facto standard for LLM token streaming. OpenAI, Anthropic and nearly all LLM providers use SSE natively, with a content-type: text/event-stream header. The reason is simple: token flow is one-way (server → client), and SSE provides that functionality with a fraction of WebSocket complexity. No sticky sessions, no connection state management and straightforward horizontal scaling with stateless servers.
WebSocket regains the advantage when interaction becomes bidirectional. Agent workflows with a human in the loop (human approval during a chain), cross-device interactions and systems where the client must signal the server during an active session justify WebSockets' added complexity.
Comparison Table: API Protocols for AI Projects
| Criterion | REST | GraphQL | SSE | WebSocket |
|---|---|---|---|---|
| Median latency | 250 ms | 180 ms | — | < 50 ms |
| Throughput (requests/s) | 20,000 | 15,000 | — | Variable |
| Agent compatibility | 5/5 | 2/5 | 4/5 | 3/5 |
| Integration complexity | Low | High | Low | Medium |
| Token streaming | Not native | Not native | Optimal | Possible |
| Horizontal scaling | Simple | Moderate | Simple | Complex |
| OpenAPI/MCP support | Native | Partial | Compatible | Manual |
| Main AI use case | Agent tool calls | ML data aggregation | LLM response streaming | Interactive real-time agents |
The 5 API Integration Patterns for AI Agents
Pattern 1 — Function Calling
Function calling is the most widespread pattern for connecting an LLM to APIs. The principle: define a catalog of “functions” with structured schemas based on OpenAPI; the LLM analyzes the user request and generates structured JSON specifying which function to call and with which arguments. Your application code then executes the actual call.
This pattern decouples the model from execution, improving security: the LLM never directly handles credentials or network connections. OpenAI, Anthropic and Google support it natively. Its main limitation: beyond 10–15 tools, schema management becomes burdensome and the risk of the model selecting the wrong tool increases.
When to use it: in-app copilots, assistants with a defined toolset (1–10 integrations), agent prototypes.
Pattern 2 — Model Context Protocol (MCP)
MCP, announced by Anthropic in November 2024, became the de facto standard for connecting AI agents to external tools and data in under two years. Adopted by OpenAI in March 2025, then Google DeepMind in April 2025, the protocol was transferred to the Agentic AI Foundation under the Linux Foundation in December 2025.
MCP operates as a centralized server exposing a standardized tool catalog. Agents dynamically discover available tools, their schemas and permissions through a unified protocol. The major advantage: you can automatically convert an existing OpenAPI specification into an MCP server, making any REST API accessible to agents without rewriting it.
When to use it: enterprise agent platforms requiring centralized control, dynamic tool discovery and access governance.
Pattern 3 — Unified API (Multiprovider Abstraction)
A unified API provides a standardized interface for an entire software category. The unified API provider translates calls into each vendor's native API, handling authentication, token refresh and API changes transparently. This is the “build once, connect to many” principle.
This pattern drastically reduces development time when an agent must interact with dozens of SaaS services: CRM, messaging, project management and accounting. The trade-offs are additional latency from the intermediate hop and limited access to vendor-specific features.
When to use it: agent products needing 10 to 100+ SaaS integrations, business automation across multiple tools.
Pattern 4 — Direct Calls (and Why to Avoid Them)
Direct calls, where the agent generates and executes raw HTTP requests, offer maximum control and minimum latency. But specialist architects describe this pattern as “extremely fragile.” Every API change breaks the integration, maintenance grows explosively with the number of APIs, and model-managed credentials pose a significant security risk.
When to use it: internal scripts, rapid prototyping with 1–2 stable APIs. Avoid in production.
Pattern 5 — Agent-to-Agent (A2A)
The A2A pattern allows autonomous agents to communicate and delegate tasks directly to one another without a central orchestrator. It is promising for decentralized multiagent systems, but discovery and communication standards remain in their infancy.
When to use it: advanced research, decentralized multiagent systems. Not yet ready for most enterprise use cases.
Antipatterns That Sabotage Your AI APIs
Antipattern 1 — The Chatty API
When an agent must chain five separate calls to retrieve the data needed for one action—user profile, preferences, account status, history and permissions—every call consumes context tokens, adds cumulative latency and multiplies failure points. In a typical agent workflow, a chatty API can triple token cost and quadruple total response time.
The fix: design aggregated endpoints around use cases. An endpoint such as /user/context should return everything the agent needs in one call instead of five micro-endpoints. Think in terms of “what the agent needs to act,” rather than database entities.
Antipattern 2 — Empty or Ambiguous Descriptions
An AI agent selects a tool primarily based on its name and description. A function named processData with the description “Processes data” is unusable for a model. It cannot know whether the function cleans a CSV, transforms JSON or launches an ML pipeline. According to field reports from specialist teams, poorly defined tool schemas are the leading cause of incorrect tool selection by production agents.
The fix: every endpoint needs an explicit action name (analyzeCustomerSentiment, generateInvoicePdf) and a 2–3 sentence description explaining when to use it, what data it expects and what it returns.
Antipattern 3 — Unstructured Responses
An LLM cannot reliably extract a date from a free-text block or interpret an error message written in prose. APIs returning inconsistent responses—sometimes a JSON object, sometimes plain text, sometimes HTML—force the agent to hallucinate the structure it hopes to find.
The fix: enforce a standardized response format across all endpoints. Every response must include a status field, a structured data field and an error field with a machine code and readable message. No exceptions.
Antipattern 4 — No Versioning
Without explicit versioning (/api/v1/, /api/v2/), a server-side schema change silently breaks every agent consuming the API. Agents cannot “understand” that a field has been renamed or a parameter has become mandatory. They fail, retry with the same parameters and waste tokens in an unproductive loop.
The fix: version APIs systematically. Maintain older versions for a sufficient migration period. Document changes in a machine-readable changelog.
Antipattern 5 — Excessive Granularity (CRUD Overengineering)
Exposing each database table as a separate REST endpoint is a classic antipattern, but it becomes critical with AI agents. An agent facing 200 CRUD endpoints cannot fit them all into its context window: the practical limit is around 50 tools before selection deteriorates significantly.
The fix: design APIs around business domains rather than databases. Group related operations into high-level endpoints corresponding to users' actual actions.
Summary Table: Antipatterns and Fixes
| Antipattern | Impact on AI agents | Fix |
|---|---|---|
| Chatty API | 3x token cost, 4x latency | Aggregated endpoints by use case |
| Empty descriptions | Incorrect tool selection | Explicit names + 2–3 sentence descriptions |
| Unstructured responses | Parsing hallucinations | Consistently standardized JSON format |
| No versioning | Cascading silent failures | Semantic versioning + machine-readable changelog |
| CRUD overengineering | Context window overflow | Business-domain APIs, maximum 30–50 tools |
Designing an API Ready for Agents: A Practical Guide
The OpenAPI Schema as an Agent–Machine Contract
The OpenAPI specification is no longer just a documentation tool for developers. It is the contract that lets an AI agent understand and use your API without human intervention. Every schema element contributes to the agent's ability to interact correctly.
Each operation's summary field must clearly express the endpoint's intent in one sentence. Its description must specify usage conditions, prerequisites and side effects. Parameter schemas must include validation constraints (minimum, maximum, pattern, enum) that prevent the agent from generating invalid values. Examples (example) give the model concrete reference points for formatting calls.
A rigorous OpenAPI specification can be automatically converted into an MCP server or function definitions for major LLMs. Investment in schema quality pays off again with every new AI consumption channel.
Structure Responses for Agent Reasoning
An API response consumed by an agent should support chained reasoning. This means three practical things.
First, include a next_actions field listing operations available after the response. An agent receiving order confirmation and seeing ["track_shipment", "cancel_order", "request_invoice"] can proactively offer those options to the user without scanning the entire tool catalog.
Second, return data in a directly usable format. If an endpoint returns a product list, include the identifiers needed for subsequent actions (adding to a cart, comparison) instead of forcing another call to retrieve them.
Third, error messages must include a machine code (INSUFFICIENT_BALANCE, INVALID_DATE_RANGE) and a corrective suggestion the agent can execute automatically. “Error 400” enables no reasoning; {"error_code": "DATE_RANGE_TOO_WIDE", "max_days": 90, "suggestion": "Reduce date range to 90 days or less"} lets the agent correct and retry.
Authentication in an Agent Context
AI agent authentication poses a specific challenge: an agent is neither a human user nor a traditional backend service. It acts on a user's behalf, with permissions that may vary with conversational context.
The recommended pattern combines OAuth 2.0 with scoped tokens. The agent receives a token granting access only to resources needed for the current task, with a short lifetime of 15–30 minutes. The orchestration layer manages this token, never the LLM directly: the model must never see or handle credentials.
In MCP architectures, the MCP server centralizes token management and exposes only the tools an agent is authorized to use. This centralization simplifies security auditing and granular access control.
Rate Limiting and Cost Management
A poorly calibrated AI agent can generate thousands of API calls in minutes through a badly managed retry loop, circular reasoning or simply a complex workflow with many steps. Rate limiting becomes a safety net against runaway agents as well as protection against abuse.
Implement three rate limiting levels. A global limit per agent (for example, 500 calls/hour) prevents runaway behavior. An endpoint limit protects costly operations (writes, deletes). A token budget per session limits the financial cost of LLM interactions.
Return rate limiting information in HTTP headers (X-RateLimit-Remaining, X-RateLimit-Reset) so the agent can adjust its pace before reaching the limit.
Reference Architecture: An Agent API in Practice
Scenario: An AI Assistant for Sales Management
Consider a concrete case. A mid-sized company with 200 employees wants to deploy an AI assistant that helps salespeople prepare for meetings. It must retrieve prospect information (CRM), correspondence history (email), recent orders (ERP), and generate a pre-meeting brief.
With a traditional API architecture, the agent would chain 4 separate calls, handle 4 different authentication schemes and parse 4 heterogeneous response formats. Brief preparation approaches 15 seconds, and each additional call consumes context tokens that reduce the model's reasoning capacity.
The recommended architecture combines three layers. An API Gateway centralizes authentication and rate limiting. An MCP server exposes a standardized tool catalog with semantically rich descriptions. Aggregated endpoints provide data grouped by business use case: one prepareMeetingBrief(prospect_id) call returning everything the agent needs.
The result: the brief is generated in 3 seconds instead of 15, token cost falls 60%, and reliability improves because the agent manages one interaction instead of four.
The Layers of a Well-Architected AI API
┌─────────────────────────────────────┐
│ AI Agent / LLM │
├─────────────────────────────────────┤
│ MCP Server (tool discovery │
│ + schemas) │
├─────────────────────────────────────┤
│ API Gateway (auth, rate │
│ limiting, observability) │
├─────────────────────────────────────┤
│ Aggregated Business APIs │
│ (use-case-driven endpoints) │
├─────────────────────────────────────┤
│ Backend Services │
│ (CRM, ERP, Email, Documents) │
└─────────────────────────────────────┘
This layered architecture clearly separates concerns. The MCP layer manages tool discovery and selection. The API Gateway handles security and observability. Aggregated business APIs handle domain logic. Backend services remain unchanged: you do not need to rewrite your CRM to make it compatible with agents.
Prepare Existing APIs for AI Agents
Agent Compatibility Audit: The Checklist
Before rewriting anything, assess existing APIs for AI agent compatibility. Forrester reports that large companies manage an average of 1,800 APIs, but only 58% are formally documented or cataloged. Undocumented APIs are, by definition, unusable by agents.
Here are the priority assessment criteria:
- Up-to-date OpenAPI specification: is every endpoint described with complete schemas, clear descriptions and examples?
- Explicit naming: are endpoint and parameter names understandable without context?
- Structured responses: is the response format consistent and predictable across all endpoints?
- Machine-readable error handling: do errors include a code and corrective suggestion?
- Versioning: is the API versioned with an accessible changelog?
- Documented rate limiting: are limits exposed in headers?
Gradual Migration: 3 Pragmatic Steps
Making APIs ready for agents does not require rebuilding everything. A three-step approach maximizes impact with a measured investment.
Step 1 — Enrich schemas (1–2 weeks). Without changing code, enrich OpenAPI specifications with detailed descriptions, examples and validation constraints. This action alone makes APIs usable through LLM function calling.
Step 2 — Create aggregated endpoints (2–4 weeks). Identify the 3–5 most frequent agent workflows and create endpoints aggregating the necessary data. These endpoints call existing APIs internally, with no backend rewrite.
Step 3 — Deploy an MCP server (1–2 weeks). Convert the enriched OpenAPI specification into an MCP server using tools such as Speakeasy Gram, FastMCP or openapi-mcp-generator. Your APIs are now dynamically discoverable by any MCP-compatible agent.
The total migration cost is 5–8 weeks of development. The benefit: APIs usable by AI agents, internal copilots and future automation, without breaking existing integrations.
FAQ
Should You Choose REST or GraphQL for an API Consumed by AI Agents?
REST is the recommended choice for APIs consumed by AI agents. Its native compatibility with OpenAPI and LLM function calling makes it the most directly usable protocol. GraphQL is justified only when the use case involves complex frontend data aggregation, not standard agent–API interactions.
What Is MCP and Why Does It Matter?
Model Context Protocol (MCP) is an open standard created by Anthropic and adopted by OpenAI, Google and Microsoft. It lets AI agents dynamically discover available tools through a centralized server. Any REST API with an OpenAPI specification can be converted into an MCP server, making endpoints accessible to agents without rewriting code.
SSE or WebSocket for Streaming LLM Responses?
Server-Sent Events (SSE) is the de facto standard for LLM token streaming, used natively by OpenAI and Anthropic. SSE is sufficient for one-way server-to-client flow and scales horizontally easily. WebSockets are justified only when bidirectional communication is needed, such as agent workflows with real-time human approval.
How Many Tools Can an Agent Effectively Manage Through an API?
The practical limit is around 50 tools. Beyond that, injecting all schemas into every request becomes impractical because of LLM context window limits. The solution: implement semantic search that dynamically retrieves relevant tools (top-k) based on the current request.
How Do You Secure an API Used by AI Agents?
Use OAuth 2.0 with short-lived scoped tokens (15–30 minutes). The LLM must never directly handle credentials: token management is delegated to the orchestration layer or MCP server. Implement rate limiting at three levels: globally per agent, per endpoint and by per-session token budget.
What Does It Cost to Make Existing APIs Compatible with AI Agents?
A gradual three-step migration—enriching OpenAPI schemas, creating aggregated endpoints and deploying MCP—takes 5–8 weeks of development. The most impactful step, schema enrichment, requires no code changes and can be completed in 1–2 weeks.
AI Coder Squad: APIs Designed for Agents from the First Commit
Designing APIs that work equally well for humans and AI agents requires specific architectural expertise, gained from delivered projects rather than reading tutorials. AI Coder Squad incorporates MCP patterns, function calling and enriched OpenAPI schemas into every project from the design stage.
AI Coder Squad designs custom applications and AI agents for companies that want to move fast without sacrificing quality, with senior developers and an AI-powered approach.
→ Start your project and discover how AI Coder Squad can accelerate your next delivery.