The Foundational Operating System for Arazzo API Workflows
A JavaScript/TypeScript toolkit for Arazzo, the OpenAPI Initiative's specification for multi-step API workflows. Validate documents, run workflows against live APIs, and read the trace of each step.
Founded by two industry veterans with over 15 years of combined experience building and maintaining core Swagger/OpenAPI tooling. Meet the team →
Works with
Arazzo Specification
OpenAPI Specification (source descriptions)
What it does
Plenty of tools will tell you whether an Arazzo document is well formed. Far fewer will run it. UseArazzo does both, and tells you what happened.
Validate
The document, against the Arazzo specification. Every violation, with the location that caused it.
Run
The workflow, against live APIs described by your OpenAPI source descriptions.
Read the trace
Each step in run order: whether it succeeded, which action was selected, and how many attempts it took, alongside the workflow's outputs and final status.
None of it is installable yet. The Validator, the Runner, and the CLI are all under heavy development in the open, ahead of a first npm release.
Why API workflows still get improvised
A single API call is a solved problem, and everything above it isn't. OpenAPI describes endpoints, but not the order you call them in, what you carry between them, or when you're done. Agent frameworks improvise that order at runtime, and improvisation is exactly what you don't want in production. UseArazzo fills the gap with Arazzo, the OpenAPI Initiative's specification for multi-step API workflows.
Why UseArazzo
Deterministic execution
A workflow that ran yesterday runs the same today. Agents get autonomy at the decision boundary, not inside the steps.
The standard is the product
We implement Arazzo exactly as the specification defines it. When something needs fixing, we fix it in the specification by contributing upstream, instead of adding private extensions that only our tools can read.
Portable artifacts
Plain Arazzo documents in your repository, driven from your own code, your CI pipeline, or an agent. If you stop using the toolkit, your API workflows keep working.
Validate and run workflows
The entire toolkit, CLI and Validator and Runner alike, is pre-1.0 and in heavy development. Nothing is published to npm yet, and APIs may change without notice. Everything below is built in the open, so you can read the code, follow along, and tell exactly where each piece stands.
CLI
One command-line interface across the toolchain: validate and run workflows on your machine and in CI. It will wrap the Validator and the Runner in a single binary.
- ✓
validate&runin one tool - ✓ CI-friendly exit codes
- ✓ Same engine as the libraries
- ☐ Not yet published to npm
Validator
Every violation against the Arazzo specification, pinned to the exact place in the document that caused it.
- ✓ Semantic validation & linting
- ✓ LSP-compatible diagnostics
- ✓ Opt-in JSON Schema validation
- ☐ Not yet published to npm
Runner
Executes workflows step by step: criteria evaluation, output mapping, failure actions, and retries, returning a per-step record of the run.
- ✓ Full control-flow (goto/retry/end)
- ✓ Sub-workflows &
dependsOn - ✓ Pluggable HTTP transport
- ☐ Not yet published to npm
Compatibility
What the toolkit can validate and run today.
| Document | Versions | Validate | Run |
|---|---|---|---|
| Workflow Document: Arazzo | 1.0.0, 1.0.1 | ✓ Yes | ✓ Yes |
| Workflow Document: Arazzo | 1.1.0 | ✗ No | △ Partial |
| Source Description: OpenAPI | 2.0, 3.0.x, 3.1.x | ✓ Yes | ✓ Yes |
| Source Description: Arazzo | 1.0.0, 1.0.1 | ✓ Yes | ✗ No |
| Source Description: AsyncAPI | any | ✗ No | ✗ No |
On the roadmap
None of this is built yet. It's where the toolkit is headed, published here so you can tell what exists today from what doesn't.
Language Service
An LSP-compatible library bringing Arazzo intelligence to any editor or tool: validation, completion, hover, go-to-definition, and find references.
Editor
A browser-based editor for authoring and validating Arazzo workflows with real-time feedback.
VS Code Extension
Arazzo authoring inside VS Code: real-time validation, semantic linting, autocompletion, and live preview.
GitHub Actions
Validation and run results reported where the work happens: violations annotated on the diff, the step-by-step run trace rendered into the job summary, and the check status driven by step outcomes rather than a single pass or fail.
Agent Skills
A set of task-shaped skills teaching agents to work the toolchain: authoring workflows from an API description, validating and fixing them, and reading a run trace when a step fails.
MCP Server
A generic Model Context Protocol server exposing validation and execution over any Arazzo document, so agents can check and run workflows with no build step.
MCP Compiler
Compiles a specific workflow into a dedicated MCP server: one typed tool per workflow, with real input schemas, for production agent deployments.
Arazzo Transformers
Explicit, versioned transformations for reshaping data between steps, declared as ordinary API calls the toolchain can validate rather than arbitrary code that needs a sandbox to run.
Get help from the maintainers
UseArazzo is free and open source. If you have a question, an idea, or a bug to report, Discussions is a good place to start, and you are welcome to email the maintainers directly about anything else.