ai/agents ai/mcp api/design apimanagement ai/governance casestudies wso2 conference
Video
Why APIs need to account for agent behavior
Nuwan Dias frames APIs as a way to support experiences. Traditional APIs often support a human-driven, step-by-step flow. Agents can explore many options, make parallel calls, retry rapidly, and take different paths for the same task. They may also lack context about the cost or side effects of an operation.
In the talk’s retail example, a person may inspect a small set of products, while an agent may compare hundreds, check inventory, and simulate carts. Exposing a human-oriented API directly to an agent can create bursts of calls that the API and its protections were not designed to handle. Putting an MCP server in front of those same operations does not remove the underlying behavior.
Dias groups AI readiness into three connected areas: design, runtime governance, and discovery.
Design for machine use
APIs should communicate intent and support efficient, safe agent actions. The talk recommends:
- Bulk operations where an agent would otherwise fetch many items one at a time.
- Machine-readable errors that state the specific reason for failure, such as an unavailable variant or out-of-stock item.
- Idempotency for sensitive writes, especially payments and checkout, so retries do not repeat an operation.
- Explicit semantics for side effects, retries, and other behavior. The talk’s description also highlights dry-run support and cost or rate hints as useful design signals.
The goal is not only to make calls valid. It is to make their meaning, consequences, and safe next steps clear to an agent.
Design MCP tools around capabilities
Dias warns against converting every API endpoint into a separate MCP tool. He distinguishes API endpoints as implementation details from MCP tools as capabilities. For example, a “check delivery status” capability may need several API calls behind it. Exposing those implementation calls as separate tools leaves the agent to coordinate them, which can increase tool use, cost, and uncertainty.
Instead, start with the agent’s task and required skills. Define the capability-oriented tools first, then decide which API operations and orchestration should implement them. The business logic should remain in the appropriate layer rather than being duplicated across tools.
Apply runtime controls to agent consumers
Runtime controls must recognize the consumer as an agent and apply policy with that identity in mind. The talk calls out these needs:
- Enforce idempotency at runtime as well as in API design, using mechanisms such as idempotency keys or a dry-run step where appropriate.
- Record the agent’s task or intent, not only the API access event. Probabilistic agent decisions make a simple access log insufficient to explain why a call occurred.
- Apply policies to MCP tools and agent-to-agent interactions, as well as to API endpoints.
- Use smart caching to reduce duplicate work and protect backend systems from high-speed retries.
Dias describes a logical architecture with an AI gateway for access to models, MCP servers, and agent-to-agent interactions, alongside an API gateway protecting backend APIs. These roles do not require two separate physical gateways.
Make capabilities discoverable
Human-oriented developer portals assume that a person can read documentation, infer side effects, and understand operational costs. Agent discovery needs machine-readable capability descriptions that state those details directly.
The speaker recommends making descriptions explicit about whether an operation is reversible, whether it needs consent or confirmation, its sensitivity, and its cost. A machine-readable capability registry can help agents discover available outcomes and workflows. Security and delegation rules also need to describe whether an agent acts with user consent or autonomously, and which operations require explicit human approval.
Dias describes WSO2’s portal as automatically generating machine-readable documentation and capability-discovery information when APIs are published. This is the presented product approach, not a claim that every portal provides these features.
Key takeaways
- AI readiness is not a flag or an MCP wrapper. Design, runtime enforcement, and discovery all need attention.
- Expect bursty, non-linear use. Bulk operations, clear errors, and retry-safe writes can reduce waste and risk.
- Expose capabilities, not a one-to-one copy of endpoints. Design MCP tools around the agent’s task and keep implementation orchestration behind them.
- Make agent activity governable and explainable. Identify the agent, enforce policy at runtime, and log task intent.
- Document consequences for machines. State side effects, consent needs, sensitivity, and cost in machine-readable form.
Related vault notes: Building Governed Integrations and AI Agents for the Enterprise covers controlled enterprise actions; Modernizing Enterprise Architecture to Unlock Agents and Abstractions for the Agentic Enterprise connect agent-ready interfaces to enterprise architecture.