Skip to content

Formulas: checked playbooks that agents and people run together

A formula is a typed workflow an agent can call like a tool. How steps, gates, checks, and human decisions run on a deterministic, durable engine.

6 min read

Long work needs a shape#

Ask a coding agent to “fix this bug” and you get one long turn. Sometimes it is great. Sometimes it skips the reproduction, edits the wrong file, and declares victory without running the tests. The agent is not lazy; nothing in a single prompt forces it to stop and prove each stage before moving on.

A formula gives the work a shape. It is a graph of steps, each one a normal agent task, connected by gates that check the result before the run moves on — and, where it matters, by a person who approves, revises, or rejects. The run is durable: it survives restarts, it can wait days for a human, and every transition is recorded.

A formula looks like a tool#

From an agent’s point of view, a formula is just another tool. Every formula has a name, a version, a description written for the agent, and an input declared as JSON Schema. When an agent’s packs include a formula, the agent gets an MCP tool named formula_<name> whose arguments are that input.

Calling it returns immediately with a run id. The caller then either polls the run, or asks to be notified: when the run settles, exactly one follow-up message arrives in the caller’s chat. People start the same formulas from chat, from automations, or through the API, and formulas can start other formulas as sub-steps.

Formulas ship only inside packs. There is no separate formula registry, so the same review, revision, and visibility rules that cover a pack cover its formulas.

The document#

Here is an abridged piece of the bug-fix formula from our builder pack:

yaml
schema: 2
name: bug-fix
title: Fix a bug
version: 2.0.2
input:
  type: object
  required: [ticket, slug]
  properties:
    ticket: { type: string }
    slug: { type: string }
    requiresSignOff: { type: boolean, default: false }
start:
  goto: [triage]
steps:
  - id: triage
    title: Triage the ticket
    prompt: |-
      Triage this bug report for {{ .Input.slug }}:
      {{ .Input.ticket }}
    maxVisits: 2
    then:
      goto: [triage_passed]
gates:
  - id: triage_passed
    resolver: jev
    questions:
      - id: pass
        type: bool
        prompt: Symptom is restated as one testable statement. No fix was applied yet.
    route:
      mode: rules
      routes:
        - id: pass
          when: answers.pass
          goto: [reproduce]
        - id: retry
          when: state.triage_attempts < 1
          set:
            triage_attempts: state.triage_attempts + 1
          goto: [triage]
        - id: give_up
          default: true
          fail:
            reason: triage did not pass its check

Prose uses Go templates with a fixed, side-effect-free function set. Data uses CEL. The compiler checks every field path statically — including that a step’s output is only referenced where that step is guaranteed to have run — so a typo fails when you save the pack, not three hours into a run.

The building blocks#

Steps render a prompt and run it as a task on the agent. A step can declare an output schema, write to a typed run state, loop up to maxVisits times, fan out over a list with a concurrency limit, continue the previous session or start a fresh one, and end by going to another node, completing, failing, or waiting for input.

Gates join arrivals and decide where the run goes next. A gate can ask typed questions — yes/no, a choice, or a score — about the evidence so far. A resolver answers them. The external gate-resolver service is opt-in — it runs only when an operator sets its API key — and otherwise the gate falls back to the install’s LLM endpoint when the gate allows it. Whichever resolver answers receives the questions and the gate’s evidence. Then routing happens either by ordered CEL rules, where exactly one route is the default, or by a person choosing a labelled route.

Checks attach to a step. A human check offers approve, revise, or reject, with a cap of three revisions. A command check runs a fixed command in the agent’s sandbox and passes on exit code 0. Command checks are off by default; an operator has to enable them for the install.

Waiting for input parks a step until someone replies on its task (a review loop) or submits values that match a schema.

Who may decide#

Every decision point has an owner, and agents do not get to approve themselves.

DecisionWho can make it
Human gate routeA person with manage access on the agent
Human check (approve / revise / reject)A person with manage access on the agent
Input for a waiting stepA person, or the agent (or ancestor run) that started this run
Rule-based gateThe CEL rules, after the resolver answers the questions

A step task cannot answer its own run’s input request, and agents have no tool for gate decisions or human checks at all. In the app, everything that needs a person shows up under Needs you.

A deterministic engine on a durable workflow#

The engine is a pure function: given the compiled program, the current state, and an event, it returns the new state, the effects to perform, and the run events to log. It does no I/O. That one decision makes runs replayable and lets us test the engine exhaustively without a server.

Around it, each run is a durable workflow on the Temporal in your cluster. External events — a step task settling, a person deciding — arrive as signals. The workflow ticks the engine, persists the state and an ordered event log, and executes effects through an outbox. A one-minute observe poll catches any task settlement that happened while the server was down.

Inside a step, the agent gets four extra tools: one to submit structured output (validated immediately), and three to read run context and state or write the state keys the step declared. If the output is missing or invalid, the step gets up to two corrective turns before it fails with OUTPUT_INVALID. If the agent still has background work running, the step stays open until it goes quiet.

Limits that keep runs bounded#

LimitDefault
Visits per step10
Executions per run200 (hard cap 1,000)
Run duration7 days
Fan-out items32
Sub-formula depth4
Step work timeout24 hours
Run state256 KiB

Waits for input, a decision, or a human check have no timeout of their own unless the formula sets timeout on that step; otherwise only the 7-day run limit ends them.

Failure, cancel, restart#

A run ends by completing (the only path to success), failing, being cancelled, or hitting a dead end where nothing live remains. A failed run stores a structured explanation: the reason, the node, and the message.

Failed or cancelled runs can be restarted in place. Restart re-activates every execution that did not succeed, keeps the outputs and state of those that did, and re-arms the run timeout. Runs that ended by design — a route that fails, a dead end, a loop limit — cannot be restarted, because running them again would only repeat the same outcome. Restart is a person’s action in the app; agents cannot restart runs.

What you see#

In the app, a formula run opens on a canvas: the graph with live status, a Live and Replay view, and a link to each step’s chat once that step has a task. Steps are grouped under one row in your archived tasks, so a twelve-step run does not bury the rest of your work.

What formulas are not#

Formulas only run agent tasks and sub-formulas. There are no HTTP or “wait until” step kinds, and live streaming of a run assumes one server replica today. If you need to call a system, do it from a step — the agent has your connectors.

Closing#

The point of a formula is not to take judgment away from the agent. It is to put checkpoints where your team would want them anyway, and to make the result auditable. To try one, see Formula runs in chat; to write your own, open the Pack builder.

Last revised .

Questions

What is a formula in Nested?
A typed, versioned workflow of agent steps, gates, and checks, shipped in a pack. Agents call it like an MCP tool named formula_<name>, and people can start it from chat or an automation.
Can an agent approve its own formula step?
No. Human gates and checks need a person with manage access on the agent, and a step task cannot answer its own run’s input request.
What happens to a formula run if the server restarts?
Each run is a durable workflow on Temporal in your cluster. It resumes where it was, and a one-minute poll catches task results that arrived while the server was down.
Can I restart a failed formula run?
Yes, from the run canvas. Restart keeps successful steps and re-runs the rest. Runs that failed by design, such as a failing route or loop limit, cannot be restarted.