From Endpoints to Intent: Rethinking Agent API Workflows with Arazzo
Once, the rallying cry of the mobile revolution was ‘There’s an app for that.’ Today, the new reality is that AI-powered agents are substantially changing how we interact with software, coining a new catchphrase: ‘There’s an agent for that!’ From automating tasks to executing complex workflows and acting autonomously on our behalf, AI agents are becoming critical intermediaries in digital interactions. While it may seem like magic, it’s still APIs—not new wizardry—that provide the connective fabric enabling these agentic workflows and serving this new class of consumers.
This shift has led to a massive acceleration in API consumption, with AI-driven API usage soaring throughout the last 18 months as the demand for machine-readable data exchanges skyrocketing. The new wave of AI consumers has fuelled a drastic 800% increase in AI-related API production, further reinforcing the importance of designing APIs that are structured, interoperable, and AI-ready. As a result, thinking holistically about APIs—and ensuring they are built for the AI era—has never been more important all industry verticals.
The surge in API activity has also driven renewed momentum in standards-based initiatives like the OpenAPI Initiative (OAI). In 2024, the initiative set a new bar for activity with the release of new specifications like Arazzo 1.0.0 and Overlay 1.0.0, alongside two important patch versions of the OpenAPI Specification: 3.1.1 and 3.0.4. This momentum has carried forward across 2025, marked by the patch release for Arazzo 1.0.1.
Why do standards and specifications matter?
In today’s fast-evolving API landscape, where AI agents are emerging as first-class API consumers, standards and specifications play a critical role in ensuring interoperability, improving the tooling experience, and fostering a shared understanding of how APIs are designed, implemented, and consumed. Specifications such as OpenAPI, AsyncAPI, and now Arazzo form the foundation for creating consistent, predictable API experiences—something that is vital especially as we enter the AI era.
This shift in API consumption has real implications. But why does this matter?
More often than not, extracting value from APIs requires more than just a single API call. Instead, workflows often demand a series of API calls to be orchestrated programmatically to accomplish a specific task (or jobs to be done). This same premise holds true when delegating responsibilities to an AI agent performing tasks autonomously on our behalf.
However, API documentation quality and accuracy vary significantly, creating challenges for all consumers. Even structured formats like OpenAPI descriptions do not natively define complex workflows, especially when spanning multiple APIs. Supporting documentation also often omits guidance on how to orchestrate multiple API calls into a cohesive workflow, especially in a manner that can be verified. Human consumers have been able to compensate for these gaps—using trial and error, out-of-band documentation, or direct communication with API providers. But AI agents lack this flexibility, and we certainly do not want them engaging in trial-and-error executions without deterministic guidance to function reliably.
For AI agents and systems to effectively and consistently leverage APIs, they require structured, deterministic, and reliable workflows—something that only robust specifications can guarantee. By standardizing how a series of complex or sensitive API calls should be executed in concert, we can:
- Prevent AI hallucinations or incorrect outputs from AI-driven consumers.
- Ensure interoperability, quality, and efficiency across API ecosystems.
- Build trust between API producers and consumers, both human and machine.
And by doing so we simultaneously elevate human developer experience (DX) and agent experience (AX).
In the age of agentic AI, where autonomous systems increasingly rely on interacting with diverse APIs, a specification like Arazzo emerges as a critical enabler of deterministic and reliable API workflows. By providing a standardized framework for orchestrating complex API interactions, Arazzo empowers developers to build robust and scalable solutions. This not only enhances the predictability and efficiency of AI-driven systems but also fosters greater trust and control, ensuring that the next wave of API consumption remains both flexible and governable.
David Roldán Martínez – AI Researcher and Industry Advisor
What is the Arazzo Specification?
The Arazzo Specification (now at version 1.0.1) enables the crafting of deterministic API workflows—a structured series of API calls that, when combined, accomplish a specific business objective or consumer job-to-be-done.
Arazzo supports both JSON and YAML formats, allowing workflows to be human- and machine-readable. This makes API capabilities easier to understand and consume, accelerating adoption for traditional human developers and AI-agent consumers alike. By providing a structured way to express workflows, Arazzo bridges the gap between API producers and consumers, making it easier to integrate APIs efficiently.
Beyond readability, Arazzo’s assertable nature helps API providers tackle key industry challenges while enabling new possibilities for next-generation, agent-based API consumption. It also supports third-party verification, allowing regulatory bodies to improve rigor and compliance across jurisdictions.
Arazzo and AI-Agent API Consumption
Arazzo’s deterministic approach makes agentic API consumption more efficient, allowing API providers to deliver interoperable workflows that work across various LLMs and agent technology stacks. It enables providers to define use case-oriented consumption semantics across multiple API operations—whether within a single API description or spanning multiple independent API descriptions.
Additionally, Arazzo’s extensibility allows for the inclusion of usage-based or SLA-based metadata, which can be enforced at the processing or observability layer to ensure predictable scale, cost management, and intended AI-agent use of APIs which will be ever more important as IT leaders navigate the total cost of ownership (TCO) of new AI-fused topologies.
APIs are the ‘Best’ Interfaces for Agents
The rise of AI agents for Computer Use (ACU) and Computer-Using Agents (UCAs)—including recent innovations like OpenAI’s Operator—demonstrates how AI can augment human workflows by interacting with existing user interfaces (UIs). This approach is especially useful in legacy environments, where AI can unlock value quickly without requiring new API development.
However, while leveraging UI-based automation may provide short-term gains, APIs are inherently the superior interface for AI agents. Unlike UIs, which are designed for human cognition, APIs are built for machine consumption, making them more scalable, reliable, and cost-effective in the long run.
Convenience technology has a habit of biting back, and while there can be short-term gains, there is also a risk that executives misinterpret those gains as cheaper, faster, and a more consistent way to enable AI goals. Just as Robotic Process Automation (RPA) was often misinterpreted as a “quick automation solution” (only to lead to expensive maintenance costs later), short-term UI-based AI integrations risk becoming a crutch if companies fail to invest in API-first strategies.
By investing in robust API assets, organizations prepare for the inevitable shift where APIs, not UIs, become the primary interface for AI agents. This is where Arazzo comes in—by providing a deterministic API workflow layer, Arazzo ensures that agents interact with APIs in a structured, reliable way, rather than relying on fragile UI-based automation, and delivering the upon the agent experience (AX) needs mentioned earlier.
Arazzo and MCP: Rethinking Tool Exposure for Agents
The Model Context Protocol (MCP) is quickly becoming a useful bridge between APIs and LLM experiences, powering discoverability and invocation in agents across tools like Cursor, Claude, Windsurf, and VSCode. It gives a structured format for accessing external tools, and that’s a an important step forward.
But there’s a potential trap lurking in how we use it.
If we treat MCP as a thin wrapper for every available API operation, turning endpoints directly into tools, we’re not exposing value, we’re exposing noise (at least in non-trivial scenarios). This 1:1 mapping (which is an naïve approach in my opnion) forces the LLM to constantly evaluate the toolset in real time, increasing context sprawl, decision fatigue, and computational cost. Worse, it locks orchestration inside the context window, where intent and memory are inherently fragile, inevitably resulting in high rates of hallucinations.
Some teams have responded by pushing all orchestration logic behind or within an MCP Server tool. This is effectively building a BFMCP (backend-for-MCP). But that’s just recreating a tightly coupled SDK under the guise of tool exposure. It’s non-interoperable, and unlikely to survive the next wave of platform or agent evolution.
Arazzo offers a better path!
Rather than exposing individual tools, Arazzo exposes the workflow-level capabilities those tools enable. It shifts the abstraction from the LLM’s reasoning loop into a protocol-defined layer that expresses value deterministically (no hallucinations). It reduces the amount of “thinking” the LLM has to do, presents actions just-in-time with relevant parameters, and maintains coherence even when the underlying APIs change. There’s also a big sustainability upside to this not to mention tremendous compute cost saving.
This separation of concerns also keeps Arazzo open and interoperable. It doesn’t require the entire ecosystem to implement a single runtime or SDK. It complements MCP by letting you express workflows that MCP tools can then execute—without coupling the two layers into a single stack.
Bottom line is that we should strive to expose value, not verbs.
Beyond AI: The Broader Use-Cases for Arazzo
While Arazzo is a key enabler of AI-based API consumption, it also provides boarder value across the API lifecycle for API producers and consumers today:
- Provide deterministic API consumption recipes – Standardize workflows to ensure repeatable, structured API interactions.
- Act as living workflow documentation – Keep API workflows up to date without relying on outdated or external documentation.
- Automate consumer-facing documentation – Reduce reliance on out-of-band documentation by generating developer portal docs dynamically.
- Enable end-to-end test automation – Define API workflows that can be used for automated testing.
- Streamline regulatory compliance validation – Automate checks to verify API interactions against compliance requirements.
- Empower next-generation API SDK generation – Enable workflow-aware SDKs for improved developer experiences.
The Arazzo Specification does not mandate a specific development process such as design-first or code-first. It facilitates either technique by establishing clear workflow interactions with HTTP APIs described using the OpenAPI Specification (and into the future it’s planned to expand to event-based protocols and the AsyncAPI specification).
Arazzo – A Concrete Example
Let’s imagine we want to describe how to achieve a ‘Buy Now Pay Later (BNPL)’ checkout workflow for online products. An agent will take responsibility for determining if the products and indeed customer are eligible for this type of financial engagement. The steps to perform the BNPL flow are:
- Check selected products are BNPL eligible
- Retrieve T&Cs and determine customer eligibility
- Create customer record (if needed)
- Initiate the BNPL Loan Transaction
- Authenticate customer and obtain loan authorization
- Calculate and retrieve payment play for client-side rendering
- Update order status
There are two APIs which together offer endpoints/methods needed to complete the process. They are:
Figure 1 – Buy Now, Pay Later – Eligibility API
Figure 2 – Buy Now, Pay Later – Loan API
Leveraging Arazzo, we can describe the workflow explicitly, giving the instructions needed for the agent to execute the workflow first-time and every-time correctly. If you would like to get a better understanding of the specification structure before looking at the Arazzo document below, check out this deep dive on the spec.
arazzo: 1.0.1
info:
title: BNPL Loan Application Workflow
version: 1.0.0
description: >
This workflow walks through the steps to apply for a BNPL loan at checkout, including checking product eligibility,
retrieving terms and conditions, creating a customer record, initiating the loan transaction, customer authentication,
and retrieving the finalized payment plan. It concludes by updating the order status once the transaction is complete.
sourceDescriptions:
- name: BnplEligibilityApi
url: https://raw.githubusercontent.com/frankkilcommins/apidays-describing-api-workflows-with-arazzo/ef35e237576d7af2bc3be66d94ffca94eee5036d/specs/bnpl-eligibility.openapi.yaml
type: openapi
- name: BnplLoanApi
url: https://raw.githubusercontent.com/frankkilcommins/apidays-describing-api-workflows-with-arazzo/ef35e237576d7af2bc3be66d94ffca94eee5036d/specs/bnpl-loan.openapi.yaml
type: openapi
workflows:
- workflowId: ApplyForLoanAtCheckout
summary: Apply for a BNPL loan at checkout using the BNPL platform
description: >
This workflow describes the steps to secure a loan at checkout using a BNPL platform, involving multiple API calls
to check product eligibility, determine customer eligibility, initiate the loan transaction, authenticate the customer,
retrieve the payment plan, and update the order status.
inputs:
type: object
required:
- customer
- products
- totalAmount
- token
properties:
customer:
description: Customer details or link to an existing customer record.
oneOf:
- type: object
required:
- firstName
- lastName
- dateOfBirth
- postalCode
properties:
firstName:
type: string
lastName:
type: string
dateOfBirth:
type: string
format: date-time
postalCode:
type: string
- type: object
required:
- uri
properties:
uri:
description: URI for an existing customer.
type: string
format: uri
products:
type: array
minItems: 1
items:
type: object
required:
- productCode
- purchaseAmount
properties:
productCode:
type: string
purchaseAmount:
type: object
required:
- currency
- amount
properties:
currency:
type: string
pattern: "^[A-Z]{3}$"
amount:
type: number
totalAmount:
type: object
required:
- currency
- amount
properties:
currency:
type: string
pattern: "^[A-Z]{3}$"
amount:
type: number
token:
description: Authorization token for the loan transaction.
type: string
steps:
- stepId: checkProductEligibility
description: Call the BNPL API to check if selected products are eligible for BNPL loans.
operationId: $sourceDescriptions.BnplEligibilityApi.findEligibleProducts
requestBody:
contentType: application/json
payload: |
{
"customer": "{$inputs.customer.uri}",
"products": $inputs.products
}
successCriteria:
- condition: $statusCode == 200
outputs:
eligibilityCheckRequired: $response.body.eligibilityCheckRequired
eligibleProducts: $response.body.productCodes
totalLoanAmount: $response.body.totalAmount
onSuccess:
- name: productsEligible
type: goto
stepId: getCustomerTermsAndConditions
criteria:
- condition: $response.body.productCodes != null
- name: productsNotEligible
type: end
criteria:
- condition: $response.body.productCodes == null
- stepId: getCustomerTermsAndConditions
description: Retrieve terms and conditions for BNPL loans.
operationId: $sourceDescriptions.BnplEligibilityApi.getTermsAndConditions
successCriteria:
- condition: $statusCode == 200
outputs:
termsAndConditions: $response.body
onSuccess:
- name: eligibilityCheckRequired
type: goto
stepId: createCustomer
criteria:
- condition: $steps.checkProductEligibility.outputs.eligibilityCheckRequired == true
- name: eligibilityCheckNotRequired
type: goto
stepId: initiateBnplTransaction
criteria:
- condition: $steps.checkProductEligibility.outputs.eligibilityCheckRequired == false
- stepId: createCustomer
description: >
If the customer is not already enrolled, create a new customer record by verifying their eligibility for a BNPL loan.
operationId: $sourceDescriptions.BnplEligibilityApi.createCustomer
requestBody:
contentType: application/json
payload: |
{
"firstName": "{$inputs.customer.firstName}",
"lastName": "{$inputs.customer.lastName}",
"dateOfBirth": "{$inputs.customer.dateOfBirth}",
"postalCode": "{$inputs.customer.postalCode}",
"termsAndConditionsAccepted": true
}
successCriteria:
- condition: $statusCode == 200 || $statusCode == 201
outputs:
customer: $response.body.links.self
onSuccess:
- name: customerCreated
type: goto
stepId: initiateBnplTransaction
criteria:
- condition: $statusCode == 201
- name: customerNotEligible
type: end
criteria:
- condition: $statusCode == 200
- stepId: initiateBnplTransaction
description: Initiate the BNPL loan transaction.
operationId: $sourceDescriptions.BnplLoanApi.createBnplTransaction
requestBody:
contentType: application/json
payload: |
{
"enrolledCustomer": "https://api.example.com/customers/12345",
"products": $inputs.products,
"totalAmount": $inputs.totalAmount
}
successCriteria:
- condition: $statusCode == 202
outputs:
redirectAuthToken: $response.body.redirectAuthToken
loanTransactionId: $response.body.loanTransactionId
onSuccess:
- name: authorizationRequired
type: goto
stepId: authenticateCustomerAndAuthorizeLoan
criteria:
- condition: $response.body.redirectAuthToken != null
- name: authorizationNotRequired
type: goto
stepId: retrievePaymentPlan
criteria:
- condition: $response.body.redirectAuthToken == null
- stepId: authenticateCustomerAndAuthorizeLoan
description: Authenticate the customer and obtain authorization for the loan.
operationId: $sourceDescriptions.BnplEligibilityApi.getAuthorization
parameters:
- name: authorizationToken
in: query
value: $inputs.token
successCriteria:
- condition: $statusCode == 200
outputs:
redirectUrl: $response.headers.Location
- stepId: retrievePaymentPlan
description: Retrieve the finalized payment plan after loan authorization.
operationId: $sourceDescriptions.BnplLoanApi.retrieveBnplLoanTransaction
parameters:
- name: loanTransactionId
in: path
value: $steps.initiateBnplTransaction.outputs.loanTransactionId
successCriteria:
- condition: $statusCode == 200
outputs:
finalizedPaymentPlan: $response.body
- stepId: updateOrderStatus
description: Update the order status to "Completed" once the loan transaction is finalized.
operationId: $sourceDescriptions.BnplLoanApi.updateBnplLoanTransactionStatus
parameters:
- name: loanTransactionId
in: path
value: $steps.initiateBnplTransaction.outputs.loanTransactionId
requestBody:
contentType: application/json
payload: |
{
"status": "Completed"
}
successCriteria:
- condition: $statusCode == 204
outputs:
finalizedPaymentPlan: $steps.retrievePaymentPlan.outputs.finalizedPaymentPlanWow – all that YAML. Yes, machines love it but the beauty of such formats, is that we can also leverage tools to render Arazzo in human-centric forms too. The Arazzo Document can be parsed to a sequence diagram like:
Enabling Agentic API Consumption
The shift towards AI-driven API consumption is accelerating, and deterministic API workflows are critical to ensuring that AI agents can interact reliably with APIs. Arazzo bridges the gap between traditional API consumers and AI agents, providing a structured, assertable framework that removes ambiguity and enhances interoperability which reduces vendor lock-in.
Whether you’re automating workflows, enabling AI consumption, or enhancing API governance, Arazzo is the key to unlocking the next generation of API-driven innovation.
Explore the Arazzo Specification today to learn more.
This article originally appeared on TheNewStack. We’re sharing it here for our audience who may have missed it. This version includes additional context and updates especially related to the Arazzo and MCP intersection.