Choreograph
Menu

Every guarantee is enforced at one Gate, and pinned to a named test.

Seven capabilities, enforced below the model and exercised by tests that ship with the code.

  1. Model the work

    Your process is written once and enforced everywhere; changing a step never means rewriting an agent.

    • Declare states, authority, tools and human sign-off.
    • Version and validate the declaration before work begins.

    ShippedCoverage validation refuses incomplete declarations.

    @tasktype(
    "VendorInvoice",
    fields=VendorInvoiceFields,
    initial="INTAKE",
    sub_types=[LineItem, Payment],
)
class VendorInvoice:
    edges = (
        edge("REVIEW", "APPROVED",
             by=["finance-lead"]),
    )
    Listing 1The workflow in Python.

    Selected lines from the invoice declaration; not a complete runnable definition. SDK names may change before release.

    Read the full task type declaration

  2. Swap the workflow. Keep the system.

    Workflows are portable, versioned TaskType declarations.

    • Change the workflow by loading a new version and restarting Choreograph.
    • The runtime and dashboard reconfigure automatically.

    ShippedCoverage validation refuses incomplete declarations.

    Load a new portable, versioned TaskType declaration and restart Choreograph. The runtime and dashboard then reconfigure from that declaration.
    Figure 1Load. Restart. Reconfigure.
    Open full diagram

    Illustrative architecture; not a product screenshot.

  3. Bound the authority

    No agent, and no administrator, can act outside what the process allows.

    • Authority and tool scope are checked on every submit.
    • Single-writer leases and tenant isolation constrain every write.

    ShippedA refused attempt is a commit in the same history.

    Choreograph authority matrix: an AI accounts-payable agent can propose a payment; only the finance lead can approve the bill.
    Figure 2Authority belongs to the step.
    Open full diagram

  4. Prove what happened

    Your audit is a query you run, not a report you commission.

    • Hash-linked commits preserve byte-exact model turns.
    • Replay, reconstruct and seal evidence for an independent auditor.

    ShippedOne edited byte is named by commit.

    Illustrative linked commits: changing Commit 2 breaks its recorded hash, and verification identifies that first mismatch.
    Figure 3A history you can verify.
    Open full diagram

  5. Touch the world safely

    Money moves once, after a human, or not at all.

    • Declared amounts and payees must match the committed record.
    • After a restore, effects stay off until bank reconciliation catches up.

    ShippedZoho Books live-verified; Revolut Business sandbox-integrated.

    Agent proposal, human review and executor action are separate stages.
    Figure 4Review precedes execution.
    Open full diagram

  6. Run any AI on it

    Swap the model tomorrow; keep every guarantee.

    • Bring your model and key; Pydantic AI is the reference harness.
    • A conformance bench checks replacement harnesses against the contract.

    ShippedReal model and human turns use the same Gate.

    Human and agent share the same guarded action boundaryAI agentpinned model + agent specHumandeclared roleauthority · scope · guardsTyped taskone recorded action boundaryclaim · context · submit

    Agent edgeHuman edge GuardDashed: effect after commitDotted: reopen

    Figure 5People and agents.
    Open full diagram

  7. Keep humans in command. Operate it simply.

    One database your team already runs; humans and agents queue at the same Gate.

    • Claim, review and hand off work on the same task.
    • A dead runner’s lease expires on the database clock.

    ShippedProven on Wanakam, cut-over with the release.

    An agent hands a task to human review, then resumes with its context.
    Figure 6The handoff keeps the work.
    Open full diagram

Enforce the rule with the right evidence.

Three ways to evaluate guards and invariants. Check the task’s own data, query the system that owns the fact, or use a separate model to evaluate judgement.

Guards decide whether an action may proceed; invariants check the resulting state before it is committed. Choreograph runs invariants after mutation and before commit, on every transition. What evaluates them is a design choice.

Pure-function

Enforce exact limits with a deterministic check. A Python predicate reads the task’s fields and the current world. It is fast and the default for most invariants.

For example, total_wired <= amount checks that the amount wired stays within the declared amount.

Connector-backed

Check against the system that owns the fact. The predicate queries an external system through a connector before returning its result.

For example: does this bill’s external_ref exist in Zoho, and is the bill still unpaid? The check uses a real query, not an assumption.

Model-backed

Keep the evaluator separate from the acting agent. A narrow, versioned classifier evaluates a question such as whether a synthesis cites the sources it claims.

Its verdict is a structured boolean recorded in TimeGraph. The judging model is a separate check, not the acting agent certifying its own work.

Guard and invariant evaluation in Choreograph: a state transition is checked by a Python predicate, an external connector or an independent model classifier.
Figure 7Three evaluators, one enforcement boundary.
Open full diagram

A model-backed check can be wrong. It is probabilistic; separation, versioning and a recorded verdict make it auditable, not infallible.

What is true today, September 2026.

  • automated tests1,900+ · including concurrency property tests
  • replayreplay == world · verified per tenant
  • injectionhostile instruction refused in‑chain on the live read path
  • connectorsZoho Books · live‑verified with a real model. Revolut Business · sandbox‑integrated
  • operator verbsverify · replay · world-at · fork · evidence · score · reconcile
  • evidenceevidence bundle + insurability score · third‑party re‑runnable
  • not yetreal‑money effects · hosted beta · public docs (≈30 days)

Bank effects are sandbox drafts. Real money is behind an engineering gate we chose not to cross yet, and every demonstration says so.

How this differs from frameworks and durable execution