Programmable Agent Orchestration: the h5i-orchestra eDSL

An agent ensemble has one fixed answer to "what should happen next": everyone attempts the task, the round is sealed, peers review, a verifier decides. That is a good default, and h5i team ships it. But the real space of useful topologies is larger. Sometimes you want a designer agent to hand a plan to two implementers. Sometimes you want three independent attempts ranked in an arena. Sometimes you want one integrator to merge the work of many. Each of those is a different program, and a fixed protocol cannot express them.

h5i-orchestra is that program layer. It is an embedded DSL in Rust: you write an ordinary async function, you are handed a Conductor, and you drive the run by calling methods on it. There is no graph builder. There is no compile() step. The orchestration is whatever your code did, recorded as it ran.

Define-by-run: the graph is a trace, not a prerequisite

This is the one design decision everything else follows from, and it is not a new idea. It is the decision that settled the deep-learning framework wars a decade ago. Theano and early TensorFlow asked you to describe a computation to a smarter executor, then hand it over. PyTorch let you perform the computation and quietly recorded it. The recorded-execution side won on the things that actually matter day to day: errors surface where you wrote the code, the host language is the control flow, and you can drop a breakpoint anywhere.

Agent orchestration is more dynamic and more failure-prone than a training loop, so the lesson transfers with force. In h5i-orchestra, the classic ensemble is a loop you can read:

// hire two agents, each into its own sandboxed env
let claude = c.agent("claude").runtime("claude").hire().await?;
let codex  = c.agent("codex").runtime("codex").hire().await?;

// fan-out is just host-language concurrency
let (a, b) = tokio::try_join!(claude.work(&task), codex.work(&task))?;
c.freeze().await?;                       // seal the independent attempts

// cross review, a plain loop
let (ra, rb) = tokio::try_join!(codex.review(&a), claude.review(&b))?;

// neutral verification in a fresh sandbox, then a pluggable verdict
let verified = c.verify([&a, &b]).command("cargo test").await?;
let verdict  = c.judge(verified, policy::tests_then_smallest_diff()).await?;

There is no framework vocabulary here. No executors, no edges, no supersteps. To add a condition, you write an if. To retry, you write a loop. To run two agents at once, you use the concurrency your language already has. The DAG that a reviewer will later want to see is derived from the trace after the fact, with h5i team trace --dot. It is a view over what happened, never a thing you had to construct before anything could happen.

Durability without a server: journaling on a Git ref

A coding-agent turn costs minutes and real money. So the property that matters most in an orchestrator is not speed, it is this: if the process dies at step forty, restarting must not re-run the first thirty-nine. That is durable execution, and the industry has three designs for it. Temporal replays your workflow code against an event history. Restate journals each named step's result and skips it on recovery. Graph frameworks checkpoint at a barrier and re-execute forward, which can re-pay LLM calls.

h5i-orchestra takes the journaling design, because for agent turns it is the only one where a resume is free. Every effectful operation, an agent().hire(), a work, a verify, an arbitrary step, executes once and appends its serialized result to the run's event log at refs/h5i/team/<run>. Each step carries a stable key, label#seq. Re-running the score consults the journal by key: a hit returns the recorded result instantly, a miss executes live and records. Kill the run at any point, run the same binary again, and it fast-forwards through everything already done and picks up exactly where it stopped.

Because the journal is a Git ref, durability costs nothing to operate and it travels. There is no database to run and no checkpoint store to configure. h5i share push moves a live run to another clone. One machine can drive a score up to a human approval gate, a reviewer on a different machine can answer, and either side can resume. The cross-machine handoff is a git push. None of the general-purpose orchestration frameworks can do that without a hosted runtime, because their state does not live in your repo.

$ h5i team run fix-auth --task-file task.md --verify-cmd "cargo test"
➜ driving team 'fix-auth': 2 agents, 1 review round
# ...process killed at the verify step...

$ h5i team run fix-auth --task-file task.md --verify-cmd "cargo test"
➜ resuming: 6 journaled steps replay without re-execution
# the two agent attempts and the reviews are NOT re-run: they replay from the ref

The primitives

The surface is deliberately small. A score composes a handful of methods on the Conductor and on the Agent handles it hands you. Everything else is a pattern built from these.

The one discipline the eDSL asks of you is stable step identity: parallel steps must carry distinct labels, so a resume pairs the right recorded result with the right call. Agent operations get this for free, since their labels embed the agent id. For your own parallel loops, Conductor::scope gives each branch its own label namespace, and the journal fails closed if two concurrent steps ever collide on a label. That is the analog of the one constraint PyTorch borrowed from JAX: demand discipline only where it buys something users cannot get otherwise. Here it buys a free resume.

Where this sits

It would be a mistake to sell h5i-orchestra as a better LangGraph or a better Microsoft Agent Framework. Those orchestrate arbitrary in-process LLM calls, they have hosted observability, and they have ecosystems this does not. If you are building a general multi-agent application, use one of them.

What h5i-orchestra owns is the layer none of them touch: the agents are semi-trusted coding agents that need kernel-enforced isolation, their outputs need provenance, their cross-influence needs to be auditable, and their merged result needs a mediated, evidence-gated path back to the main branch. That is not a feature you bolt onto a general framework. It is the substrate underneath, and h5i already had it. The orchestrator is the thin part. The isolated envs, the capture evidence, the neutral verifier, and the Git-native event log are the parts that are hard to build and easy to depend on.

The result is an orchestrator with a different center of gravity. Not "describe a graph to a runtime," but "write a program, and the runtime records it into a Git ref you can share, resume, and audit." The score is yours. The proof travels with it.

FAQ