Agent Workflow Orchestrator

Agent Workflow Orchestrator is a local-first engine for deterministic planner, executor, and critic workflows. It is designed for teams that need reliable orchestration semantics before connecting a workflow to external models, queues, or production systems.

The project runs with Python 3 standard library only. The demo and tests do not require network access, Docker, paid API keys, or third-party packages.

What It Provides

• Declarative workflow specs with nodes, tools, retry policy, budgets, and human-in-the-loop checkpoint rules.
• Deterministic planner/executor/critic execution using local safe tools.
• Tool registry with structured dispatch, declared cost units, and simulated failure modes.
• Budget guards for steps, tool calls, and cost units.
• Retry scheduling with traceable retry attempts and delay decisions.
• Checkpoint events when configured policy thresholds are crossed.
• JSONL trace logging and replay summaries.
• Static HTML trace explorer for node state, retries, budget usage, checkpoints, and final outcomes.

Quick Start

python3 -m unittest discover -s tests
python3 -m agent_workflow_orchestrator demo --output runs/demo

The demo writes:

• runs/demo/workflow_spec.json
• runs/demo/traces.jsonl
• runs/demo/replay_summary.json
• runs/demo/dashboard.html

Open dashboard.html in a browser to inspect the workflow timeline and outcomes.

CLI

Run the built-in demo:

python3 -m agent_workflow_orchestrator demo --output runs/demo

Replay an existing trace:

python3 -m agent_workflow_orchestrator replay --trace runs/demo/traces.jsonl --output runs/demo/replay_summary.json

Run a custom spec:

python3 -m agent_workflow_orchestrator run --spec path/to/workflow_spec.json --output runs/custom

Workflow Model

A workflow is a directed graph of node declarations. Each node has a role, a tool reference, a prompt, and optional dependencies. The engine executes nodes in deterministic topological order, dispatches local tools, records every state transition to JSONL, and stops dependent nodes when upstream work fails.

The built-in tools are intentionally simple and deterministic. They model orchestration behavior rather than language generation quality:

• planner: creates a structured local plan from node input and dependency context.
• executor: creates deterministic task artifacts.
• unstable_executor: fails for a configured number of attempts, then succeeds.
• critic: scores dependency output and can fail when quality is below threshold.
• summarizer: produces a final workflow summary.
• echo: returns structured input for tests and extensions.

Repository Layout

agent_workflow_orchestrator/        # checkout shim for python -m
src/agent_workflow_orchestrator/    # installable package
tests/                              # unittest suite
docs/                               # architecture and extension docs
.github/workflows/ci.yml            # standard test and demo CI

Integration Notes

The engine is intentionally dependency-free. Production adapters can map the same workflow semantics to systems such as LangGraph, LangChain, or the OpenAI Agents SDK by implementing custom tool handlers and trace exporters while keeping the local spec, replay, and test path intact.