Ouroboros AI

0.36.0 verified Sat May 09 auth: no python

Ouroboros is a specification-first workflow engine for AI coding agents, integrating with Claude Code and Codex CLI. It allows you to define reusable workflows using YAML specs and execute them via agents. Current version is 0.36.0, with a fast release cadence and breaking changes between minor versions.

pip install ouroboros-ai

Common errors

error ModuleNotFoundError: No module named 'ouroboros_ai' ↓

cause Incorrect import path; the module is named 'ouroboros' (no underscore/hyphen).

fix

Use import ouroboros or from ouroboros import WorkflowEngine.

error yaml.parser.ParserError: expected <block end>, but found '<block mapping start>' ↓

cause Workflow YAML uses 'steps' key but old spec used 'tasks'.

fix

Change top-level 'tasks' to 'steps' in your YAML file.

error TypeError: WorkflowEngine.run() missing 1 required positional argument: 'workflow' ↓

cause In version 0.35+, the 'workflow' argument is keyword-only.

fix

Call engine.run(workflow=workflow) explicitly.

Warnings

breaking In version 0.35.0, the 'run' method signature changed: it now requires 'workflow' as keyword argument, not positional. ↓

fix Update calls from `engine.run(workflow)` to `engine.run(workflow=workflow)` or just `engine.run(workflow)` if using keyword (still works in 0.35+). Actually the signature changed: previous positional args may now be keyword-only. Check migration guide.

breaking Workflow spec format changed from 'tasks' to 'steps' in version 0.30.0. Old YAML files will fail to load. ↓

fix Rename 'tasks' top-level key to 'steps' in your YAML files, and adjust per-step field names.

gotcha The package name on PyPI is 'ouroboros-ai' (with hyphen), but the importable module is 'ouroboros' (no hyphen). Common mistake: try to import from 'ouroboros_ai'. ↓

fix Use `import ouroboros` or `from ouroboros import ...`.

Imports

WorkflowEngine
wrong
```
from ouroboros_ai import WorkflowEngine
```
correct
```
from ouroboros import WorkflowEngine
```
Old library name used hyphen, but Python package uses underscore. Import from 'ouroboros'.

load_workflow

wrong

from ouroboros_ai.workflow import load_workflow

correct

from ouroboros import load_workflow

The correct import is directly from ouroboros, not a submodule.

Quickstart

Load a YAML workflow specification and execute it using the engine.

import os
from ouroboros import WorkflowEngine, load_workflow

workflow = load_workflow("my_workflow.yaml")
engine = WorkflowEngine(api_key=os.environ.get('ANTHROPIC_API_KEY', 'test-key'))
result = engine.run(workflow)
print(result)