Skip to content
Browse the docs

Formula reference

The schema-2 formula format: typed input, steps, gates, checks, human input, state, limits, and how runs execute, fail, and restart.

Updated 4 min readView as Markdown

What a formula is#

A formula is a reusable, typed workflow. Agents and people start it the way an agent calls a tool: by name, with an input object checked against a JSON Schema. It is a graph of steps — each one a prompt that runs as a task on the agent — and gates that join branches and route the run. A run carries a typed state object that steps can read and update.

Formulas ship inside packs, in formulas/<name>.yaml. To watch and act on runs in the app, see Formula runs.

Document fields#

FieldRequiredMeaning
schemaYesAlways 2
nameYesLowercase slug, for example bug-fix
versionYesSemantic version
title, descriptionYesThe description is what agents read to decide when to use it
inputYesJSON Schema for the run input
startYesWhere the run begins
stepsYesAt least one step
stateNoSchema plus initial values for run state
gatesNoDecision nodes
output, limits, layoutNoRun output, limit overrides, editor layout

A trimmed real formula:

yaml
schema: 2
name: small-task
title: Small task
version: 2.0.1
description: Implement and verify a small task in one session.
input:
  type: object
  required: [body]
  properties:
    body:
      type: string
start:
  goto: [implement]
steps:
  - id: implement
    title: Implement
    prompt: |-
      Implement this task:

      {{ .Input.body }}
    output:
      type: object
      required: [summary]
      properties:
        summary: { type: string }
    maxVisits: 2
    then:
      goto: [implement_passed]

Prompts use Go templates with a fixed function set. Data expressions — state writes, routing rules, output — use CEL. Nested compiles every formula when a pack is verified, uploaded, and loaded, and checks every field path statically, so an invalid formula never reaches an agent.

Steps#

Each step has an id, a prompt, and a then with exactly one of goto, complete, fail, or waitForInput. Options include:

  • output — a JSON Schema the agent’s structured result must match.
  • set and writes — state updates by expression, and state keys the agent may set itself.
  • session — continue the agent conversation or start fresh.
  • forEach — fan out over a list with a concurrency limit.
  • kind: formula — run another formula as a sub-step, up to 4 levels deep.
  • maxVisits, timeout, onError, and check.

Inside a step, the agent reports its result with a structured-output tool. Missing or invalid output gets up to 2 corrective turns before the step fails.

Checks#

A step can require a check before it continues:

  • Human — a person approves, asks for a revision with a note, or rejects. Up to 3 revisions.
  • Command — a fixed command runs in the agent’s sandbox; exit code 0 passes. Command checks are off by default and must be enabled per install.

Gates#

Gates join arrivals (each, first, or all) and route the run:

  • Rules — ordered CEL conditions, with one required default route.
  • Human — labelled routes a person picks, with an optional note.

A gate can also ask typed questions (yes/no, choice, or score) about the evidence before routing. A resolver answers them. The default resolver is an external gate-resolver service, but it is opt-in: it runs only when an operator sets its API key at install. Without a key, the gate falls back to the install’s LLM endpoint when the gate allows a fallback. Either way the question and the evidence go to that resolver, so check which one your install uses before gates handle sensitive data.

Human input#

A step that ends with waitForInput parks the run until someone replies in the step’s chat or submits values that match the schema. The agent that started the run can answer through its own tool; a step can never approve itself. Gate decisions and human checks are always made by people.

Running, cancelling, and restarting#

Each run is a durable workflow, so it survives control-plane restarts. Each step becomes a task on the agent, in the run’s workspace. A run ends when a step completes it (the only way to succeed), fails it, someone cancels it, or nothing is left to run.

A failed or cancelled run can be restarted in place: steps that succeeded keep their output and state, and the rest run again. Runs that failed by design — a route to fail, a dead end, or a loop limit — cannot be restarted.

Default limits#

LimitDefault
Visits per step10
Executions per run200
Run duration7 days
Fan-out items32
Step work timeout24 hours
Rendered prompt64 KiB
Step output64 KiB
Run state256 KiB

Waiting for input, a decision, or a human check has no timeout of its own unless the formula sets timeout on that step. Otherwise only the 7-day run limit ends the wait.

Only task and formula steps exist today.

Questions

How does an agent start a formula?
Each formula the agent’s packs allow becomes a tool named after it, for example formula_bug_fix. People can start formulas from chat and automations.
Can a formula wait for a human?
Yes. Human checks, human-routed gates, and steps that wait for input all park the run and show up in Needs you until a person acts.
Can I restart a failed formula run?
Yes, if it failed or was cancelled. Successful steps keep their results and the rest run again. Runs that ended by design cannot be restarted.