By Juan Mestas, Group Technology Head – Digital Strategy, Architecture, Platform Engineering, Transformation and Innovation
While recently looking into an API glitch caused by a lack of idempotency, and considering what the same flaw would look like in an agentic environment, I found myself following the rabbit on a deeper question: how ready are our API design practices for a world where agents, not humans, are the primary consumers?
A quick search of the topic led me to Kong’s 2026 API analysis, which, in many ways, validated this concern. The analysis exposes a critical disconnect between intent and reality:
- 83.2% of organizations claim to have adopted an API-first approach
- Only 25% actually operate as fully API-first organizations
- Just 24% design APIs explicitly for AI agents
I decided to take a look at our current practices and design patterns for APIs. In summary, APIs are primarily designed for developers: they rely on interactive authentication flows, implicit assumptions, and a/synchronous request-response patterns, and most of them will break down when autonomous agents attempt to call them. Agents retry. Agents reason. Agents compose. And when APIs are not designed for those behaviors, failure won’t be the exception.
Doing a bit more research on the topic and trying to put my thoughts together. What follows is an exploration of why agent-callable APIs are rapidly becoming the new frontier in enterprise integration, and why this shift is architectural, organizational, and strategic, not merely technical.
From Plumbing to Capability Exposure
For all my professional experience, I could say that architecture has been optimized around three clearly distinctive layers:
- Human interaction (applications and channels)
- Process orchestration (workflows/state machines, and BPM)
- System integration (APIs as plumbing)
Agentic AI collapses these layers. An agent does not “use” an application. It invokes intent.
To better understand the above, I went to one of the sources of all things architecture: Martin Fowler. He distinguishes between syntactic and semantic interfaces primarily in the context of DSLs and Fluent Interfaces.
A syntactic interface deals with the structure and form of the code.
A semantic interface deals with the meaning and intent behind the code. It is the underlying model that defines what the program actually does when it executes.
In other words, and as an example, while a traditional API handles errors through HTTP status codes or error objects, an agent-callable API works better with natural-language explanations and recovery suggestions.
/* Traditional API */
{
“error”: “INSUFFICIENT_FUNDS”,
“code”: 464,
“message”: “Not enough funds to complete the transaction”
}
/* Agent-callable API */
{
“error”: “INSUFFICIENT FUNDS”,
“explanation”: “The transaction for $200 exceeds your current available balace”
“context”: {
“transaction_code”: “00012345”,
“transaction_amount”: “USD 200”
},
“suggested_actions”: [
{
“action”: “001”,
“description”: “Increase available balance”,
“endpoint”: “/capabilities/add-money”
},
{
“action”: “002”,
“description”: “Get a small personal loan”,
“endpoint”: “/capabilities/credit-app”
}
],
“escalation_path”: “Contact your wealth banker manager”
}
This exposes a fundamental gap that is more than a maturity issue. It is a structural constraint on the adoption of agentic AI for many companies that have heavily invested in APIs.
The MCP Connection
The Model Context Protocol (MCP) provides the transport and discovery layer, and it’s a critical enabler: it decouples models from systems, allowing agents to retrieve precisely the context they need at runtime rather than relying on bloated prompts.
But MCP per se does not create an advantage. It standardizes access, not meaning.
As an enterprise, to create critical differentiators, we need to look at:
- Capability semantics
- Business constraints
- Recovery logic
- Compliance metadata
- Cost and latency awareness
Architectural Patterns for Agent-Callable APIs
I tried to list some of the patterns that could help us to be Agent-ready in the design of our APIs.
Capability-Oriented Exposure
Agent-callable APIs expose business capabilities, not CRUD operations.Instead of /orders/{id}, agents interact with intent-revealing actions:
- Semantic description
- Preconditions
- Postconditions
- Failure modes
- Suggested recovery paths
/* Traditional REST API */
POST /orders
GET /orders/{id}
PUT /orders/{id}/status
/* Agent-callable API */
POST /capabilities/place-order
– Semantic description: “Submit a customer order for fulfillment”
– Preconditions: Customer validated, balance available, payment authorized
– Postconditions: Order created, payment received, confirmation sent
– Failure modes: Insufficient balance, payment declined
– Recovery suggestions: Alternative products, retry payment
Contextual Metadata Enrichment
Agent-callable APIs embed rich metadata that enables reasoning:
- Business rules
- Approval thresholds
- Compliance constraints
- Side effects
- Audit requirements
This is a take on “smart endpoints, dumb points” design principle.
Conversational Failure as Design, Not Exception
Failures become decision points, not dead ends. Traditional APIs terminate. Agent-callable APIs negotiate (see the above markup block)
Digital Payments and the Rise of ACP
Financial services, payments, and regulated platforms are leading adoption not despite regulation but because of it.
Several platforms are already moving in this direction:
- Stripe has built MCP support for agent-driven payment flows
- Square has released MCP servers across payments and catalog APIs
- Shopify has launched MCP integrations for commerce workflows
Beyond MCP, the industry appears to be coalescing around the Agentic Commerce Protocol (ACP) as a standardized interface between agents, merchants, and payment rails.
If ACP achieves broad adoption, it would represent the first standardized, agent-native checkout protocol a significant step toward truly frictionless commerce.
Takeaways
Two enterprises can use the same LLM. Two banks can adopt the same MCP stack. Only one will win. The reasons behind the success are that only one has:
- Explicit, agent-callable business capabilities
- Machine-readable institutional knowledge
- Auditable, intent-aware automation
This transformation is architectural, not cosmetic. Adding descriptions to existing REST APIs is necessary but insufficient. True agent-callable design requires rethinking how business capabilities are structured and exposed.
Governance must evolve in parallel. Traditional API governance focuses on consistency and security. Agent-callable governance adds intent validation, liability attribution, and reasoning auditability.
Finally: Start small.
Focus on high-value, bounded capabilities. Don’t boil the ocean.
Design accordingly.