Building Reliable API Workflows with Arazzo

Agentic systems require precise tool orchestration to accomplish real work. During our recent Ask Me Anything session, Vladimír Gorej, our Prague-based senior software engineer and GitHub Star, shared practical insights on how the Arazzo specification addresses multi-step API workflow challenges that traditional OpenAPI cannot solve alone.

The conversation covered real implementation examples, migration strategies, and the role of the Arazzo Engine in making agent workflows more deterministic and reliable.

Understanding Arazzo: Beyond Single API Operations

As Vladimír explained during the session, Arazzo addresses the gap between individual API endpoints and complete business workflows. "OpenAPI is strong at describing single APIs. Teams also need a standard way to orchestrate sequences across APIs," he noted, highlighting the fundamental problem the specification solves.

OpenAPI excels at documenting individual operations-endpoints, data schemas, and encoding formats. However, it cannot describe how to orchestrate multiple operations to complete business processes. Using the classic petstore example, OpenAPI documents the /pets, /orders, and /order/{id} endpoints separately, but provides no guidance on connecting them into a complete "buy a pet" workflow.

Arazzo fills this orchestration gap with machine-readable workflow definitions in YAML or JSON. The specification sits alongside OpenAPI under the Linux Foundation's OpenAPI Initiative, ensuring long-term stability and community governance.

The Pre-Arazzo Landscape

During the AMA, Vladimír addressed how organizations previously handled workflow orchestration. While older enterprise specifications existed, they remained largely unknown and unused due to limited community adoption. Most teams resorted to documenting workflows in natural language. They are readable by humans but not executable by machines.

"People tried to document the workflows within the API for human consumption only," Vladimír explained. The lack of standardization created maintenance overhead and inconsistent implementations across organizations.

The key difference with Arazzo lies in its backing by the OpenAPI Initiative. This institutional support has catalyzed tool development and community adoption in ways previous specifications could not achieve.

Live Demo: Arazzo Engine in Action

Vladimír provided a detailed walkthrough of the Arazzo Engine during the session, demonstrating both workflow generation and execution. He showed how the system works with the familiar petstore API, using real commands and outputs to illustrate the process.

The demonstration revealed three distinct workflows the generator identified from the petstore OpenAPI specification:

Pet adoption workflow (finding available pets, placing orders, retrieving order details)
User account management (profile updates and user operations)
Pet management (retrieving and updating pet information)

Particularly noteworthy was the generator's ability to accept custom prompts for specific workflow requirements. When Vladimír provided instructions for "buying a pet" with specific parameters (available status, single pet selection), the system focused the generated workflow accordingly.

The runner demonstration showed seamless execution of the complete workflow, handling HTTP requests, authentication through environment variables, and data flow between operations-all through a simple command-line interface.

Installation and Basic Usage

Install the generator via Python package manager:

BASH
pip install arazzo-generator

Generate workflows from an OpenAPI specification:

BASH
arazzo-generator generate petstore.json --output petstore-arazzo.json

Install and use the runner:

BASH
pip install arazzo-runner
arazzo-runner execute petstore-arazzo.json --workflow-id pets-adoption-workflow --inputs '{"status": "available", "limit": 1}'

Both components support Docker deployment for containerized environments.

Advanced Features

Custom Workflow Generation

The generator accepts additional prompts to create specific workflows:

BASH
arazzo-generator generate petstore.json --workflow-description "Find available pets, place order, get order details" --output custom-workflow.json

Quality Assurance and Hallucination Mitigation

The session addressed practical concerns about LLM reliability in workflow generation. Vladimír detailed how the Arazzo Engine incorporates multiple validation layers to ensure output quality.

The generator includes specialized prompts optimized for different LLM providers, designed to minimize hallucination and improve specification accuracy. A self-correcting mechanism handles common JSON and YAML formatting issues using deterministic algorithms and regular expressions.

Post-generation validation runs automatically, checking both structural validity and Arazzo specification compliance. As Vladimír noted during the demo:

"Being valid doesn't necessarily mean that it's logically valid, but it's more like structurally valid."

This multi-layered approach provides better results than feeding raw OpenAPI specifications to general-purpose LLMs like ChatGPT, as the embedded prompts and validation routines are specifically tuned for workflow generation tasks.

Running Individual Operations

The runner executes both workflows and individual OpenAPI operations:

BASH
arazzo-runner execute-operation petstore.json --operation-id getPetById --inputs '{"petId": 123}'

Integration with Jentic Public APIs

Jentic maintains over 1,500 OpenAPI specifications and hundreds of generated workflows in the Jentic Public APIs repository. This knowledge base provides production-ready workflows for common enterprise APIs.

Each API includes corrected OpenAPI specifications and generated Arazzo workflows. The repository uses automated processes to import new APIs and generate workflows through GitHub issue templates.

Migration Strategies: From Existing Workflows to Arazzo

An audience member asked about migrating existing multi-agent systems that don't use REST APIs to Arazzo workflows. Vladimír provided practical guidance on handling this common enterprise challenge.

His recommended approach involves using LLMs as translation assistants rather than attempting manual conversion:

"We can always use some kind of LLM to help us translate it into an Arazzo. It's not going to be perfect, but it will get 80% done, and we need to review it manually,"

he explained.

The migration strategy varies by source format:

Structured formats (YAML, JSON): Deterministic translation tools can handle the bulk of conversion work
Natural language descriptions: Feed workflow documentation as context to the Arazzo generator
Code-embedded workflows: Extract workflow logic through logging analysis or code documentation

For complex enterprise workflows, Vladimír suggested a divide-and-conquer approach, breaking large processes into smaller, manageable components that can be converted incrementally.

Agent Benefits and Workflow Determinism

A significant portion of the discussion focused on how Arazzo improves agent reliability. Vladimír highlighted that agents often struggle with multi-step API processes due to hallucination and brittleness in complex workflows.

"For agent to understand the API and having an Arazzo specification on top of the API makes it understand what are the business workflows that I can follow,"

he explained.

Instead of agents attempting to deduce workflow sequences from individual endpoints, Arazzo provides explicit action sequences.

This deterministic approach reduces the prompt engineering complexity typically required to make agents reliable with multi-tool operations. Agents can reference validated workflow definitions rather than improvising API call sequences, leading to more predictable outcomes in production systems.

Contributing to Open Standards: Hacktoberfest and Beyond

The session concluded with practical guidance for developers interested in contributing to the Arazzo ecosystem. Vladimír outlined several contribution opportunities, from documentation improvements to core feature development.

He emphasized that meaningful contributions extend beyond code:

"Even when you're not familiar with the coding itself, you can still contribute by fixing our documentation, making it better, fixing the typos that we might have or fixing the nonsensical sentences."

For Hacktoberfest participants, he highlighted specific technical needs:

URL Support: Enable loading Arazzo specifications from remote URLs to integrate with the Jentic Public APIs repository
Enhanced Request Visibility: Implement detailed logging showing headers, payloads, and response data during workflow execution
Type Safety Improvements: Strengthen Python type annotations throughout the codebase
Test Coverage: Expand test cases for the self-correcting OpenAPI parser mechanisms

The project follows standard open source practices with Apache 2.0 licensing and contributor covenant guidelines, making it accessible for developers at all experience levels.

Industry Adoption and Future Outlook

When asked about enterprise adoption, Vladimír shared insights on when companies should-and shouldn't-consider Arazzo implementation. His perspective was notably balanced:

"I don't think there is a use case why not using it. Even if a company has a private API, the Arazzo can help them to understand the business processes within that company."

The conversation touched on potential adoption by integration platforms like Zapier. While Vladimír acknowledged this would be beneficial for the ecosystem, he noted the business reality: "If Zapier expose it, they would actually expose their business, like the main business that they do, and that's the integration between the services."

The discussion revealed realistic expectations about adoption timelines. Drawing parallels with OpenAPI's evolution, Vladimír emphasized that widespread adoption requires time and community building. Even OpenAPI, despite its maturity, is often used more as code-generated documentation than as infrastructure-first design specification-the ideal goal for both OpenAPI and Arazzo.

The Future of API Workflows

As an open standard under the Linux Foundation, Arazzo provides a stable foundation for API workflow automation. The specification addresses the gap between individual API operations and complete business processes.

Companies adopting design-first approaches can define workflows alongside API specifications, creating a complete picture of system interactions. This approach improves onboarding, reduces integration complexity, and enables more reliable automated systems.

The Arazzo ecosystem continues growing with community contributions, additional tooling, and integration with existing API development workflows.

Next Steps

Start exploring the Arazzo Engine with the Petstore example or browse workflows in the Jentic Public APIs repository. The command-line tools provide immediate hands-on experience with workflow generation and execution.

For organizations with complex API integration requirements, Arazzo offers a path toward more maintainable, documentable, and automatable workflows.