Agent Wranglers

API-68Optional

Describe multi-step tasks as Arazzo workflows

When a common task takes three or more calls in a fixed order, describe it in an Arazzo file next to the OpenAPI contract.

By Agent Wranglers. Updated .

How to do it

An OpenAPI file lists each call alone. Arazzo says which calls to make in which order, which output feeds the next input, and what counts as success. People and AI agents then follow the steps instead of guessing them. Point each step at an operationId from the contract. Lint the file with a tool such as Spectral, and run each workflow as a test with a tool such as Redocly Respect. Set up the linter as use Spectral to lint the OpenAPI contract shows. Publish it where agents find the API.

Examples

YAML example

arazzo: 1.1.0
info:
  title: Place an order
  version: 1.0.0
sourceDescriptions:
  - name: shop
    url: https://api.example.com/openapi.yaml
    type: openapi
workflows:
  - workflowId: placeOrder
    inputs:
      type: object
      properties:
        sku: { type: string }
    steps:
      - stepId: createCart
        operationId: createCart
        successCriteria:
          - condition: $statusCode == 201
        outputs:
          cartId: $response.body#/id
      - stepId: addItem
        operationId: addCartItem
        parameters:
          - name: cartId
            in: path
            value: $steps.createCart.outputs.cartId
        requestBody:
          payload:
            sku: $inputs.sku
            quantity: 1
        successCriteria:
          - condition: $statusCode == 200
      - stepId: checkout
        operationId: createOrder
        requestBody:
          payload:
            cartId: $steps.createCart.outputs.cartId
        successCriteria:
          - condition: $statusCode == 201

How to check

The Arazzo file passes a linter, and every operationId it names exists in the OpenAPI file. Each workflow runs against a test server and every successCriteria passes.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/api-design/contracts-and-docs/arazzo-workflows">Agent Wranglers API design playbook</a>. In code you write, add a comment next to it with the same link.