# Formula reference

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

Section: Platform · Updated: 2026-11-19 · Canonical: https://nested.me/docs/formula-reference

## 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](https://nested.me/docs/packs), in `formulas/<name>.yaml`. To watch and act on runs in the app, see [Formula runs](https://nested.me/docs/formulas).

## Document fields

| Field | Required | Meaning |
|---|---|---|
| `schema` | Yes | Always `2` |
| `name` | Yes | Lowercase slug, for example `bug-fix` |
| `version` | Yes | Semantic version |
| `title`, `description` | Yes | The description is what agents read to decide when to use it |
| `input` | Yes | JSON Schema for the run input |
| `start` | Yes | Where the run begins |
| `steps` | Yes | At least one step |
| `state` | No | Schema plus initial values for run state |
| `gates` | No | Decision nodes |
| `output`, `limits`, `layout` | No | Run 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

| Limit | Default |
|---|---|
| Visits per step | 10 |
| Executions per run | 200 |
| Run duration | 7 days |
| Fan-out items | 32 |
| Step work timeout | 24 hours |
| Rendered prompt | 64 KiB |
| Step output | 64 KiB |
| Run state | 256 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.

## Related

- [Formula runs in chat](https://nested.me/docs/formulas)
- [Packs](https://nested.me/docs/packs)
- [Pack builder](https://nested.me/docs/pack-builder)
- [Automations](https://nested.me/docs/automations)
