Home

Next

tuvl

Typed workflows of agents — deterministic where they can be, bounded where they can't — on a durable, journaled runtime, built spec-first.

tuvl 2.0.0 — released 20 October 2026, public beta now

tuvl 2.0 is a redesign with no 1.x compatibility layer: workflows are graphs of typed agents, every run is durable and journaled, and projects are built from specs. See what's new. Until the release, install the public beta 2.0.0b3 — see Installation. Versions follow SemVer.

Try it live — no install

Run any example in a throwaway browser sandbox at try.tuvl.online with the Insight editor.

Pronounced "Thoo-val" (തൂവൽ) in Malayalam — a feather.

What is tuvl?

A tuvl workflow is a graph of agents. Each agent has a typed contract — inputs, outputs, the signals it emits — and an engine that implements it. Signals route to the next agent or a named end. tuvl checks the whole graph statically (contracts, data flow, types, policy, worst-case cost) and runs it on a durable runtime that records everything it does.

kind: Workflow
version: tuvl/v2
metadata: { name: refund_flow, description: Handle a refund request }
spec:
  models: [Order, Refund]
  trigger:
    http: { path: /api/refunds, method: POST }
    input: { order_id: uuid, reason: str }
  agents:
    - id: load_order
      description: Load the order
      engine: tool
      inputs: { order_id: uuid }
      outputs: { order: Order }
      tool: { use: db, model: Order, op: read, where: { id: "{{ order_id }}" } }
      routes: { default: triage, not_found: END.missing, error: END.failed }
    - id: triage
      description: Decide how the refund is handled
      engine: decide
      inputs: { order: Order, reason: str }
      outputs: { lane: "enum[auto, review]" }
      decide:
        rules:
          - { when: "order.total > 500", then: review }
          - { when: "true", then: auto }
      routes: { auto: issue_refund, review: approval, error: END.failed }
    # issue_refund (code) and approval (human) …
  outputs:
    default: { status: 200, body: { refund_id: "{{ refund.id }}" } }
    missing: { status: 404, body: { error: unknown order } }
    failed:  { status: 500, rollback: true, body: { error: refund failed } }

Key features

  • Seven engines, one contract

    code, tool (DB/HTTP/MCP), decide (rules, then a model), llm, loop (bounded tool use), human, and pending contracts. Swap an engine without touching the graph.

  • Deterministic first

    Every workflow has a determinism profile and a worst-case token cost. Rules decide before models; an unavailable model is an error, never a silent fallback.

  • Durable runs

    Runs survive restarts, wait for people, pause and resume on any worker, and compensate on rollback. Every run is journaled.

  • Record, replay, test

    Pin any run as a fixture and replay it with zero tokens. Offline tests with typed mocks; calibrated, cached judges for free-text checks.

  • Spec-driven

    Write intent in a spec; analysis proposes contracts and a task plan; codegen, validation and task status are deterministic. Coding agents use the same tools over MCP.

  • Insight

    Specs and task board, a canvas over the same YAML, runs with breakpoints, step mode and approvals, change-engine checks, judge calibration.

  • REST, SSE and MCP

    Typed OpenAPI from contracts, journal events over SSE, workflows as MCP tools, and a typed TypeScript client.

  • Governed

    Ed25519-signed JWTs, default-deny triggers, approvals without self-approval, secure fields kept away from models, policy checked before you ship.

Where to start

AI agent instructions

License

tuvl is open source software licensed under the MIT license.