---
title: "Describe multi-step tasks as Arazzo · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/contracts-and-docs/arazzo-workflows
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Describe multi-step tasks as Arazzo workflows

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Contracts and docs](https://agentwranglers.se/playbook/api-design/contracts-and-docs.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

- ID: API-68
- Level: Optional
- Chapter: [Contracts and docs](https://agentwranglers.se/playbook/api-design/contracts-and-docs)
- Rule: When a common task takes three or more calls in a fixed order, describe it in an Arazzo file next to the OpenAPI contract.
- Applies when: The project offers an API to others.
- How: 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](https://agentwranglers.se/playbook/api-design/contracts-and-docs/openapi-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](https://agentwranglers.se/playbook/stack/testing-and-code-quality/spectral) shows. Publish it where agents [find the API](https://agentwranglers.se/playbook/api-design/contracts-and-docs/agent-discovery).
- 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.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### YAML example

```yaml
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
```

## Sources

- [Arazzo Specification 1.1.0](https://spec.openapis.org/arazzo/v1.1.0.html)

## Related rules

- [Write the contract first](https://agentwranglers.se/playbook/api-design/contracts-and-docs/openapi-contract) in API design
- [Use Spectral to lint the OpenAPI contract](https://agentwranglers.se/playbook/stack/testing-and-code-quality/spectral) in Software choices
- [Make the API easy for agents to find](https://agentwranglers.se/playbook/api-design/contracts-and-docs/agent-discovery) in API design

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/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.

- Previous: [Mark server-set fields read-only and secrets write-only](https://agentwranglers.se/playbook/api-design/contracts-and-docs/read-only-fields)
- [Contracts and docs](https://agentwranglers.se/playbook/api-design/contracts-and-docs)