Structured Orchestration of AI agents as a tree of tasks, against spaghetti vibe-coding -- Task preconditions and postconditions, spend tracking and limits, event logging, etc.
AI agent orchestration today is unstructured. Agents spawn agents, there are no verification boundaries, no budget enforcement, and no systematic way to know if work was done correctly. Free-form agent delegation is the goto of AI workflows — it produces results, but they are fragile, opaque, and unverifiable.
orxtra applies structured programming to AI workflows. Every piece of work is a task with explicit entry conditions (pre-checks), exit conditions (post-checks), and a budget ceiling. Tasks nest recursively. Failure propagates up the hierarchy. The system verifies work at every boundary — not after the fact, but as a structural guarantee.
Every tool call requires an active task.
There is no way to do untracked work. Every file read, every edit, every git operation happens inside a task with a budget, a trace, and verification boundaries. If an agent tries to call a tool outside a task, it gets a hard error.
Verification is structural, not bolted on.
Pre-checks gate entry. Post-checks gate exit. A check can be a Python script, a read-only AI agent that produces a structured verdict, or an entire sub-workflow. Failed post-checks let the agent retry. Exhausted retries escalate to the parent. The system does not trust agents to self-report quality.
The Overseer is a persistent LLM brain that acts only through typed action tools.
It can create workflows, add constraints, record decisions, create inbox items for human review — but only through a fixed vocabulary of actions. Every action is recorded in the trace. The Overseer cannot perform side effects outside its action tool set. It reasons and decides; the scheduler executes.
Budgets are denominated in USD.
Every task has a cost ceiling. Token usage is tracked per-task and converted to dollars using an internal pricing table. When a task exceeds its budget, execution stops — no silent overruns.
Agents cannot bypass safety mechanisms.
There is no bash tool. Git mutations go through safegit (concurrency-safe). File deletion goes through saferm (audited, recoverable). Write safety enforces per-path locking and stale-write detection. The system is designed so that agents cannot take shortcuts even if they want to.
Events are first-class.
Subscriptions with typed filter predicates, per-subscription action chains, accumulator buffering with count and time thresholds. External systems write events into the same store and subscribe to patterns. Dual-phase delivery: in-process futures for zero-latency task waking, PG-backed subscriptions for durable cross-process reactions.
Each module works standalone.
Use just the LLM client. Or just the task scheduler. Or just the event system. Or the full stack. 28 modules across five layers, strict dependency direction, no circular imports.
Tip
Each module installs independently. Start with what you need; add more as your requirements grow.
| Use case | Module | Install |
|---|---|---|
| Typed LLM client with streaming and tool calls | transport |
pip install orxtra-transport |
| Agent definitions from TOML + composable markdown prompts | agent |
pip install orxtra-agent |
| Tool registry with path enforcement and write safety | tool |
pip install orxtra-tool |
| Pre/post-check execution (scripts, agents, workflows) | verify |
pip install orxtra-verify |
| Deterministic task execution with budgets and constraints | scheduler |
pip install orxtra-scheduler |
| Reactive event subscriptions with actions and accumulators | dispatch |
pip install orxtra-dispatch |
| Persistent AI brain with action tools and memory | overseer |
pip install orxtra-overseer |
| PG event store with crash recovery and state machines | trace |
pip install orxtra-trace |
| Full CLI for agents and humans | cli |
pip install orxtra-cli |
| MCP server for dashboard integration | mcp |
pip install orxtra-mcp |
Six more foundation modules (protocols, secrets, write-safety, notepad, session, services) are installed as dependencies when you need them.
One-shot LLM call, no orchestration:
from orxtra.services import ask
result = await ask(
prompt="Summarize this document.",
provider_type="anthropic",
model="claude-sonnet-4-20250514",
api_key="sk-...",
)Structured workflow with verification:
from orxtra.services import start_run, RunConfig
run_id = await start_run(
pool=pg_pool,
workflow_path="workflows/review.toml",
config=RunConfig(
provider_type="anthropic",
model="claude-sonnet-4-20250514",
api_key="sk-...",
autonomy_level="medium",
),
)basic_agent.toml— minimal agent definitionsimple_workflow.toml— workflow with dependencies and post-checkscategories.toml— multi-provider model routingcoder_agent.toml— agent with exec capabilities
CLAUDE.md — full technical reference | CHANGELOG.md — release history