Stop Building Brittle Agent Workflows

Rod Rivera — Tue, 16 Sep 2025 17:56:09 +0000

TL;DR: AI agents fail when they can't reliably chain API calls together. The Arazzo Generator automatically discovers workflow patterns from OpenAPI specs, and the Runner executes them deterministically. This means agents that actually work in production instead of breaking on the second API call.

Why Agents Need This

Your AI agent can write perfect code, analyze complex data, and generate creative content. But ask it to book a flight, and it falls apart.

The problem isn't the reasoning. It's the execution. Real tasks require multiple API calls in sequence: authenticate, search flights, check availability, reserve seats, process payment, send confirmation.

Most agents handle this with brittle prompt engineering: "First call the auth endpoint, then use that token to call the search endpoint..." When any step fails, the whole workflow breaks. The agent retries random steps, passes parameters incorrectly, or gives up entirely.

Production systems need deterministic workflows. Not LLM guesswork about which API to call next.

The Missing Standard

OpenAPI describes individual endpoints perfectly. But it doesn't describe how endpoints connect into workflows. That gap kills agent reliability.

You get documentation like this:

# What OpenAPI gives you
POST /auth/login
GET /flights/search  
POST /bookings/create
GET /bookings/{id}/confirm
POST /payments/process

But agents need this:

# What agents actually need
1. Login (POST /auth/login) -> get auth token
2. Search flights (GET /flights/search) -> get flight options  
3. Create booking (POST /bookings/create) -> reserve seat
4. Process payment (POST /payments/process) -> charge card
5. Confirm booking (GET /bookings/{id}/confirm) -> final verification

The Arazzo Specification fills this gap. It is a standard from the OpenAPI Initiative that describes multi-step API workflows in machine-readable format.

How Arazzo Engine Works

Two components solve the workflow problem:

Arazzo Generator: Analyzes OpenAPI specs and automatically identifies logical workflow patterns using AI. No manual mapping required.

Arazzo Runner: Executes workflows deterministically with proper error handling, retries, and parameter passing.

Think of it as infrastructure for reliable agent execution.

See It Work

Generate workflows from any OpenAPI spec:

# Install the generator
pip install arazzo-generator

# Generate workflows from your API
arazzo-generator generate https://api.example.com/openapi.json -o workflows.yaml

The generator discovers patterns like this:

workflows:
  - workflowId: book-flight
    description: Complete flight booking workflow
    steps:
      - stepId: authenticate
        operationId: login
        outputs:
          authToken: $response.body.token

      - stepId: search-flights
        operationId: searchFlights
        parameters:
          - name: Authorization
            value: $steps.authenticate.outputs.authToken
          - name: origin
            value: $inputs.origin
          - name: destination  
            value: $inputs.destination
        outputs:
          flightOptions: $response.body.flights

      - stepId: create-booking
        operationId: createBooking
        parameters:
          - name: Authorization
            value: $steps.authenticate.outputs.authToken
          - name: flightId
            value: $steps.search-flights.outputs.flightOptions[0].id
        outputs:
          bookingId: $response.body.bookingId

      - stepId: process-payment
        operationId: processPayment
        parameters:
          - name: Authorization
            value: $steps.authenticate.outputs.authToken
          - name: bookingId
            value: $steps.create-booking.outputs.bookingId
          - name: paymentMethod
            value: $inputs.paymentMethod

Now your agent can execute the entire workflow reliably:

from arazzo_runner import ArazzoRunner

runner = ArazzoRunner()
result = runner.execute(
    workflow_file="workflows.yaml",
    workflow_id="book-flight",
    inputs={
        "origin": "NYC",
        "destination": "LAX", 
        "paymentMethod": "card_12345"
    }
)

The runner handles authentication, parameter passing, error recovery, and step dependencies. Your agent focuses on business logic instead of API orchestration.

What This Means for Agents

Before Arazzo: Agents guess at workflow steps, pass parameters incorrectly, and break when APIs change.

After Arazzo: Agents execute deterministic workflows with proper error handling and recovery.

The difference is production reliability. Instead of brittle prompt chains, you get standardized workflow execution that works consistently.

Real Examples Agents Can Execute

E-commerce Purchase:

arazzo-generator generate shop-api.yaml --workflow-descriptions "complete purchase flow"

Discovers: Product search -> Add to cart -> Apply coupon -> Process payment -> Send confirmation

User Onboarding:

arazzo-generator generate user-api.yaml --workflow-descriptions "new user setup"

Finds: Create account -> Verify email -> Setup profile -> Configure preferences -> Send welcome

Data Processing:

arazzo-generator generate data-api.yaml --workflow-descriptions "ETL pipeline"

Maps: Upload file -> Validate format -> Transform data -> Store results -> Generate report

Each workflow includes proper error handling, retry logic, and parameter validation. Agents execute them reliably without custom orchestration code.

Join Hacktoberfest 2025

The Arazzo Engine is participating in Hacktoberfest this October. Over 40 beginner-friendly issues are ready for contributors:

Workflow generation: Improve AI-powered pattern discovery
Runner reliability: Better error handling and recovery
Documentation: Examples and tutorials for agent integration
Testing: Edge cases and integration coverage

All skill levels welcome. Every contribution helps make agent workflows more reliable.

Live AMA: September 18

Join the live discussion about Arazzo and agent workflows at the Ask Me Anything with Vladimír Gorej

When? September 18
What will we learn? How Arazzo makes agent runtimes more predictable
Why attend? We will have live demos of workflow execution and a walkthrough for any Hacktoberfest contributors.

Vladimír is a former Principal Engineer at Oracle, GitHub Star, and co-founder of SpecLynx. He knows OpenAPI tooling and how standards actually work in production.

Why This Matters Now

Agentic systems do real work only when they can call the right tools, in the right order, with the right credentials. Prompt engineering won't scale to complex multi-API workflows.

Standards solve this, as they provide:

Deterministic execution instead of LLM guesswork
Proper error handling and recovery patterns
Parameter validation and type safety
Auditability for production systems

The Arazzo Specification gives agents the infrastructure they need to work reliably at scale.

Getting Started

Install the generator:

pip install arazzo-generator

Generate workflows from your OpenAPI specs:

# Basic generation
arazzo-generator generate api.yaml

# Focus on specific workflows  
arazzo-generator generate api.yaml --workflow-descriptions "user onboarding" "checkout flow"

# Validate output
arazzo-generator validate workflows.arazzo.yaml

Integrate with your agent framework:

# Use with any agent runtime
runner = ArazzoRunner()
result = runner.execute(
    workflow="user-onboarding", 
    inputs=agent_context
)

The workflows follow the official Arazzo specification. They work with any compliant runner and integrate with existing agent architectures.

The Infrastructure Difference

Agents are infrastructure. They need reliable tools, not creative interpretations of API documentation.

Arazzo provides the missing layer between OpenAPI specs and agent execution. It makes workflows explicit, deterministic, and auditable.

Your agents stop guessing about API sequences. They execute proven patterns with proper error handling.

No more brittle prompt chains. No more debugging why the booking failed at step 3. Just reliable workflow execution that works in production.

The Arazzo Engine is open source and part of Hacktoberfest 2025. Contribute at github.com/jentic/arazzo-engine or join the live AMA on September 18.

DEV Community: Rod Rivera