> For the complete documentation index, see [llms.txt](https://docs.interactive.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interactive.ai/agents/guides/authoring-routines.md).

# Authoring routines

Building routines node by node: the golden rule, transitions and branching, tool chains, loops, common patterns, anti-patterns, and the pre-submit checklist.

> **Context** — This guide assumes the [Routines](https://docs.interactive.ai/agents/concepts/routines.md) concept page (node kinds, classification, completion semantics). Here we build up a real routine and collect the patterns that keep flows reliable.
>
> YAML examples follow **manifest schema 1.4.0**. Manifest and content shapes are schema-versioned and differ across runtime versions — see [Versioning & compatibility](https://docs.interactive.ai/agents/operations/versioning.md).

## The golden rule

**A node does exactly one thing.** It calls tools, *or* speaks, *or* routes. Never two of these at once. (Two more kinds work something out without speaking: the typed-inference **THINK** node, described with [autonomous routines](https://docs.interactive.ai/agents/guides/authoring-autonomous-routines.md) and usable in conversational ones too, and the formula [**COMPUTE** node](#working-values-out-compute-nodes). `think` node ids must be unique across the agent's routines.)

Wrong — the schema rejects `tools` + `chat_state` on one node, and for good reason:

```yaml
  - id: create-ticket
    tools: tools:create_ticket
    tool_instruction: "Create a support ticket with the issue details."
    chat_state: "Tell the customer their ticket has been registered."  # REJECTED
```

Right — two nodes connected by a transition:

```yaml
  - id: create-ticket
    tools: tools:create_ticket
    tool_instruction: "Create a support ticket with the issue details."
    transitions:
      - to: ticket-msg

  - id: ticket-msg
    chat_state: >
      Tell the customer their ticket has been registered.
```

The one tool that speaks is [`built-in:initiate_human_handoff`](https://docs.interactive.ai/agents/reference/built-in-tools.md#built-ininitiate_human_handoff): its `customer_message` parameter is emitted as the turn's reply (and `silent: true` sends nothing), so a handoff is a single tool node with no follow-up chat node.

## Activation conditions

`conditions` decide when the whole routine engages. Same craft as [policy conditions](https://docs.interactive.ai/agents/guides/authoring-policies.md#writing-conditions-that-match-correctly): concrete phrasings, explicit boundaries against sibling routines.

```yaml
conditions:
  - >
    The user wants to make a reservation — phrases like "I want to book
    this", "let's reserve the Golf", "can you book it". Activates after
    the user has identified a specific car, or when they explicitly name
    a make/model they want to rent.
```

A booking routine and a search routine live side by side precisely because each condition names its own triggers and excludes the other's ("Do NOT activate when the user is referring to a specific booking they already have").

Conditions and `chat_state` texts reach the model exactly as authored, so YAML block style matters — see [policy rule 4](https://docs.interactive.ai/agents/guides/authoring-policies.md#writing-actions-that-do-what-you-meant) for when to use a literal block (`|`) versus a folded block (`>`).

## The graph: entry, transitions, terminals

Execution starts at the node named by `entry`. Edges live on the node that produces them:

```yaml
entry: ask-dates
nodes:
  - id: ask-dates
    chat_state: >
      Ask for the pickup date and return date in one short message.
    transitions:
      - to: fetch-availability
        condition: "The user has provided both dates."

  - id: fetch-availability
    tools: cars:check_availability
    tool_instruction: >
      Call check_availability with pickup_date and return_date as
      YYYY-MM-DD strings.
    transitions:
      - to: present-availability

  - id: present-availability
    chat_state: >
      Present the available cars for those dates with daily prices in EUR.
```

The rules to internalise:

* **One transition → condition optional** (unconditional advance). On a tool, `think:` or `compute:` node a condition there is not checked; to route on the node's result, use [rules](#rules-on-transitions).
* **Two or more transitions → every one needs a condition.** The engine evaluates them and takes the matching branch. On a tool, `think:` or `compute:` node they can instead be rules the engine checks without a model — see [Rules on transitions](#rules-on-transitions).
* **No `transitions` at all → terminal node.** The routine completes there.
* **Loops are first-class.** Transition back to an earlier node id to re-ask until the answer validates — no special syntax.

## Tool nodes: the routine decides, arguments fill in

When the routine reaches a tool node, its tools run. The model never decides whether a tool is useful; it only fills in the arguments nothing else supplies, using the tool's own description and schema:

```yaml
  - id: create-the-booking
    tools: cars:create_booking
    input:
      cars:create_booking:
        member_email:
          source: llm
          instructions: Pass it only if the member lookup succeeded.
    transitions:
      - to: announce-result
```

Multiple sequential tools chain naturally (each tool node advances in the same turn). Independent tools can share one node:

```yaml
  - id: fetch-data
    tools:
      - cars:get_booking_history
      - cars:get_loyalty_status
    transitions:
      - to: present-findings
```

### Arguments

A tool node's `input` sets where each argument comes from, keyed by tool and then parameter. Known values are bound: the parameter is hidden from the model and passed with its JSON type.

```yaml
  - id: get-history
    tools: crm:get_withdrawal_history
    input:
      crm:get_withdrawal_history:
        party_id:
          source: variable
          variable: party_id
        limit:
          source: literal
          value: 10
    transitions:
      - to: present-history
```

| Source        | Value                                                                                                                                                                             | Fields                                     |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `literal`     | A fixed JSON value (not `null`)                                                                                                                                                   | `value`                                    |
| `variable`    | A variable declared in the manifest's `context.variables`                                                                                                                         | `variable`, optional `path`                |
| `input`       | A field of the autonomous trigger input (autonomous routines only)                                                                                                                | `path`                                     |
| `message`     | The customer's message: every message they sent since the agent last replied, oldest first, one per line (conversational routines only)                                           | —                                          |
| `step_output` | The result of an earlier tool, `think:` or `compute:` node of this routine                                                                                                        | `step`, optional `path`, optional `within` |
| `today`       | Today's date (`YYYY-MM-DD`) in the agent's timezone                                                                                                                               | —                                          |
| `now`         | The current date and time (ISO 8601 with its offset), in the agent's timezone                                                                                                     | —                                          |
| `llm`         | Generated by the model                                                                                                                                                            | optional `instructions`                    |
| *(no source)* | The value of a formula, written as a [compute node's](#working-values-out-compute-nodes) are, e.g. `{formula: "lower(trim(input.email))"}`; routine nodes only, not `emit_output` | `formula`, optional `omit_if_empty`        |

`path` looks into a JSON value: dot-separated object keys or array indexes, for example `brands.0.id`. Names, paths, and types are checked when the agent starts; a bound value that is missing at runtime, or of the wrong type, blocks the call rather than being guessed. In an autonomous run, a blocked call counts as a failed tool call and follows `on_tool_error`. Without `input` every parameter is generated. Once you list arguments for a tool, unlisted required parameters are still generated but unlisted optional ones are left out — list an optional parameter as `llm` to have it generated. A binding never passes `null`: to send nothing for an optional parameter, leave it out. For an optional parameter whose value may be empty, add `omit_if_empty: true` to its `input`, `variable`, `step_output` or `formula` binding: an empty value (missing, `null`, `""`, `[]` or `{}`) then leaves the argument out instead of blocking the call; a step that failed still blocks it. A formula reads a value with nothing to read as `null`, as in a compute node, so `default()` can stand in for it; the tool's span in the trace still names that value, as a warning, or as a note when the step it reads failed or the field is declared optional. A formula that fails, or gives `null`, blocks the call. When nothing is left to generate, the tool is called without a model request.

### Results of earlier steps

`step_output` passes an earlier step's result into an argument, exactly as the step returned it, so the model never retypes it:

```yaml
  - id: get-player
    tools: crm:get_player
    input:
      crm:get_player:
        player_id:
          source: step_output
          step: get-history
          path: output.player_id
    transitions:
      - to: present-player
```

Every step's result is read as `{ok, step_id, output}`, plus `error` when the step failed (reading `error` on a step that succeeded gives `null`): `output` is what the tool returned, a `think:` node's typed output, or the values a `compute:` node worked out. The step's latest result is read, from this turn or an earlier one; `within: this_message` reads only the current message's. A chat step usually ends the turn, so a `within: this_message` read with a chat step between the step and the reader on every path finds nothing and is rejected. `path: runs` reads how many times the step ran since the routine was entered, `0` before its first run, so a rule like `{source: step_output, step: write_fix, path: runs, greater_or_equal: 3}` stops a loop after three tries; a new entry into the routine in a conversation starts the count over. When the routine is saved, `step` must be a tool node calling one tool, a `think:` node or a `compute:` node, that runs before this node on every path from `entry` (for `path: runs`, any such node, this one included, so a step can pass its own attempt number). A path into a failed step's `output` blocks the call; `ok` and `error` can still be read. A step whose latest visit called its tool more than once has no one result, so reading it blocks the call too: bind every argument of a step whose result is read, so the model can't split it into several calls.

### Declaring a step's output

A tool node calling one tool, or a compute node, may declare the result it returns in `output`, a JSON Schema. A wrong path or type in a read of the step is then rejected when the routine is saved, instead of found when it runs:

```yaml
- id: get_catalogue
  tools: games:get_catalogue
  output:
    type: object
    properties:
      brands:
        type: array
        items:
          type: object
          properties:
            id: { type: string }
            games:
              type: array
              items:
                type: object
                properties:
                  rtp: { type: number }
                  tags: { type: array, items: { type: string }, optional: true }
    additionalProperties: false
```

* A read names declared fields, with a position into a list: `output.brands.0.games.2.rtp`. `output.brands.id` (no position), the undeclared `output.brands.0.name`, and `before` on the number `rtp` are rejected.
* Every declared field is required unless it says `optional: true`; an optional field may also be `null`. A missing optional field reads as empty: `is_empty` holds, a bound value blocks the call unless `omit_if_empty`, and `default(…)` fills it in a formula. The trace notes it without a warning, as it is expected.
* When the step runs, a result that doesn't match fails it, `{ok: false, error}`, and `on_tool_error` applies. Fields it doesn't declare are allowed but can't be read; `additionalProperties: false` makes them fail the step.
* A `think:` node's `output` is required and is a full JSON Schema, with `required` lists. `output` is rejected on chat, routing-only and parallel nodes, on a node calling two or more tools, and on a compute node when it names a value the node doesn't compute, or is closed (`additionalProperties` or `unevaluatedProperties: false`) and leaves out a value it computes, also through a top-level `$ref` or `allOf`. A `$ref` that doesn't resolve is rejected too, as is one into an optional field: put a shared schema under `$defs`. A read below a `$ref`, `allOf`, `anyOf` or `oneOf` isn't checked on save.
* Without `output`, any path can be read. A tool node with no `output` takes its shape from the tool's MCP `outputSchema`, if the tool publishes one; those reads are checked when the agent starts. When the tool returns more than its `outputSchema` says, declare `output` on the node to replace it.

### Declaring a step's input

A think, compute or chat node may name the values it reads in `input`: each a `type` (a JSON Schema, read as `output` is) and a source, as an argument binding has one (`input`, `variable`, `step_output`, `message`, `today` or `now`):

```yaml
- id: pick_top
  compute:
    top: tickets
    total: count(tickets)
  input:
    tickets: { type: array, source: step_output, step: get_tickets, path: output.tickets }
  transitions:
    - to: is_duplicate

- id: is_duplicate
  think: Decide whether the new ticket repeats one of the candidates.
  input:
    ticket: { type: string, source: input, path: comment }
    candidates: { type: array, source: step_output, step: pick_top, path: output.top }
  output:
    type: object
    properties:
      duplicate: { type: boolean }
```

* A think node with `input` sees only these values, its instruction and its output schema, not the conversation, tool results or other policies.
* A compute node with `input` reads only these names in its formulas (`count(tickets)`), never `input.`, `variable.`, `step.` or `message`. An object type limits the fields that can be read.
* A chat node with `input` places each value in its `chat_state` with `${input.name}`, so the reply gets the exact value instead of finding it in an earlier tool result:

  ```yaml
  - id: offer_bonus
    input:
      tier: { type: string, source: step_output, step: get_player, path: output.tier }
      bonus: { type: number, source: step_output, step: calc_bonus, path: output.amount }
    chat_state: "Offer the player a bonus of ${input.bonus} EUR. Their tier is ${input.tier}; don't say it by name."
  ```

  The values are read again on every turn the node is active, and every model call that shows the step (routine navigation, the reply, the tool announcement) sees them; the reply still sees the whole conversation. Text goes in as it is, other values as compact JSON. A value that can't be read, such as one from a failed step, is empty text: a chat step never blocks. Each `${input.name}` must name a declared input: save checks the text as written, and the agent's start checks it again once macros are filled in.
* Without `input`, all three read what they read before.
* When the routine is saved, each source is checked like any other read, and its type must fit the input's when the source declares one.
* An input marked `optional: true` may read a step that runs later in a loop back to this node (a writer reading its judge's verdict on a retry; a chat step reading the check of its last reply). It reads as `null` until that step has run since the routine was entered, then the step's latest result.
* An input marked `optional: true` may also read the node's own step: the result of its previous visit, `null` on its first visit since the routine was entered. A loop that comes back to the node can build on what it returned last time (a fix's previous try). A required input can't read its own step.
* When a think or compute step runs, a value missing or of the wrong type blocks it, as a bound argument blocks its call; a run applies `on_tool_error`. A missing value marked `optional: true` reads as `null`.

### Guidance and conditions

`tool_instruction` is optional guidance for filling the node's arguments. It never stops the call: when a tool must only run under some condition, put that condition on the transition into its node.

```yaml
  - id: explain-fee
    chat_state: "Explain the cancellation fee and ask the customer to confirm."
    transitions:
      - to: cancel
        condition: The customer confirmed the cancellation fee.
  - id: cancel
    tools: bookings:cancel_booking
    tool_instruction: Cancel the booking the customer confirmed.
    transitions:
      - to: confirm-cancellation
```

Keep the tool's meaning in its own description (the model already reads it), known values in bindings, derivation in `llm` instructions or `tool_instruction`, and conditions on transitions.

## Branching: conditions on transitions

The flow splits wherever a node declares multiple conditioned transitions. Action nodes can branch directly:

```yaml
  - id: fetch-status
    tools: crm:get_account_status
    tool_instruction: "Get the account status using PARTYID."
    transitions:
      - to: active-path
        condition: "account status is ACTIVE"
      - to: suspended-path
        condition: "account status is SUSPENDED"
      - to: other-status
        condition: "account status is neither ACTIVE nor SUSPENDED"

  - id: active-path
    chat_state: "Tell the customer their account is in good standing."

  - id: suspended-path
    chat_state: >
      Explain the account is suspended and offer to connect them with a
      human agent.

  - id: other-status
    chat_state: >
      Say the account status could not be confirmed and offer to connect
      them with a human agent.
```

When a decision point needs no action of its own, use a **routing-only node** (transitions, no action):

```yaml
  - id: triage
    transitions:
      - to: vip-flow
        condition: "the customer's loyalty_tier is gold or platinum"
      - to: standard-flow
        condition: "the customer has no premium loyalty tier"
```

Write sibling conditions so exactly one matches: they must not overlap, and one of them covers the otherwise case, as `standard-flow` does above. Phrase each as a fact the engine can see: the conversation, a variable or customer metadata, the trigger input or an earlier node's output, not as a guess about intent.

### Rules on transitions

A tool, `think:` or `compute:` node can branch on **rules** the engine checks, with no model call, in conversational and autonomous routines. A rule reads a value the way a bound argument does and compares it; the node's rules are checked top to bottom once it has run, the first that holds is taken, and the node's `otherwise` is taken when none holds:

```yaml
  - id: get-order
    tools: shop:get_order
    transitions:
      - to: refund
        when:
          all:
            - {source: step_output, step: get-order, path: output.status, equals: delivered}
            - source: step_output
              step: get-order
              path: output.total
              less_or_equal: {source: variable, variable: max_refund}
      - to: review
        when: {source: step_output, step: get-order, path: output.status, one_of: [lost, damaged]}
    otherwise: escalate
```

| Operator                                                         | Holds when the value                                                                          |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `equals`, `not_equals`                                           | equals (or doesn't equal) the operand                                                         |
| `greater_than`, `greater_or_equal`, `less_than`, `less_or_equal` | is a number that compares that way                                                            |
| `before`, `after`                                                | is a date, or a date and time, earlier / later                                                |
| `contains`                                                       | is text containing the operand, or a list holding it                                          |
| `starts_with`, `ends_with`                                       | is text starting / ending with the operand                                                    |
| `matches`                                                        | is text in which the operand, a pattern, is found anywhere (`(?i)` at the start ignores case) |
| `one_of`                                                         | equals an item of the operand list                                                            |
| `is_empty`                                                       | is missing, `null`, `""`, `[]` or `{}` (`true`), or anything else (`false`)                   |

Combine rules with `all`, `any` and `not`. The operand is a fixed value or another source, as `max_refund` above. A `matches` pattern is fixed text in RE2 syntax (no back-references or look-arounds), checked when the routine is saved.

A check can also be a **formula** that gives `true` or `false`, written as a [compute node's](#working-values-out-compute-nodes) formulas are, with the same functions and the same data, and combined with other checks the same way:

```yaml
    transitions:
      - to: vip-queue
        when:
          all:
            - {source: step_output, step: get-player, path: output.status, equals: active}
            - formula: 'lower(step["get-player"].output.tier) == "gold" && !starts_with(upper(trim(input.country)), "US")'
    otherwise: normal-queue
```

A value the formula reads with nothing to read is `null`. A formula that fails (`lower()` of a missing value) or gives anything but `true` or `false` is a mistake in the routine, like a value of the wrong type below. When what it gives is known, the routine is rejected on save instead (see the type checks under compute nodes). The trace shows the formula with the node's transitions and every value it read, beside the values the other checks read. A formula reads every value it names before it runs, so a value on a side `&&`, `||` or `if()` doesn't take is read too, and flagged when missing.

* **Empty is data.** An empty value fails every operator except `is_empty`, so a missing `status` takes the next rule or `otherwise`. To route on a missing value, check `is_empty`.
* **Values are compared as JSON:** `"10"` is not `10`, `true` is not `1`, and text is compared exactly, case included.
* **Dates** are `YYYY-MM-DD` (that day's midnight in the agent's timezone) or ISO 8601 dates and times; quote them in YAML. Compare with `today` and `now` as sources.
* **A value of the wrong type** (`greater_than` on text) is a mistake in the routine: the decision stops and the node takes `otherwise`, as when no rule holds, and the trace marks it as an error.
* A node's transitions are all rules or all conditions in words, and a rule can't lead into a routing-only node. The rest is checked when the routine is saved: a rule reads the step it leaves, or one that runs before it on every path (any step for `runs`; a tool step read for its own result calls one tool), `input` is read only in autonomous routines and at declared paths, `message` only in conversational ones, and operators fit the declared types.

The trace shows each decision with the values read and no model call; a value with nothing to read is flagged as a warning, since a misspelled path reads as empty; a path that meets `null` on the way reads as `null`, with no warning; a value empty because the step it reads failed is noted with no warning, since that step's own span shows the failure and `otherwise` routes it.

**In a conversation,** chat nodes keep the model, and rules decide the tool, `think:` and `compute:` nodes between them. Here a compute node reads the player id out of the customer's message, and a rule asks for it when it is missing:

```yaml
  - id: read-id
    compute:
      party_id: extract(message, "(\d{5,})")
    transitions:
      - to: ask-id
        when: {source: step_output, step: read-id, path: output.party_id, is_empty: true}
    otherwise: get-player
```

* Rules decide once the node's call for this visit has a result, also when the turn before ran out of iterations right after it. If the call never ran (a value the customer hasn't given yet), the model decides on the next message, reading what the customer wrote since, and normally runs the call again. A call from an earlier turn, made before this visit was chosen, does not count.
* A request that fails before its tool runs (its arguments can't be prepared, a formula fails) is the node's result, `ok: false`, and its rules route it in the same turn. A value the customer hasn't given yet is not a failure: the call waits for the next message. `runtime.on_tool_error` still decides what the customer gets after a failure.

## Working values out: compute nodes

A **compute node** works values out with formulas, with no model call: clean up an email, fill in a missing subject, add days to a date, pick an item out of a list, cut an id out of the customer's message. Each entry names a value and gives its formula; values are worked out top to bottom, and a formula can use the values above it by name:

```yaml
  - id: prepare
    compute:
      email: lower(trim(input.email))
      subject: default(step.get_magnet.output.subject, "Your free guide")
      sendable: contains(step.get_magnet.output.test_emails, email)
    transitions:
      - to: send_email
        when: {source: step_output, step: prepare, path: output.sendable, equals: true}
    otherwise: reply_not_sendable
```

Later nodes read the values like any step's result: `{source: step_output, step: prepare, path: output.email}`, in a rule or an argument. A value can be text, a number, `true` / `false`, a list or an object, so a compute node can also build the whole output `emit_output` passes on.

**Reading data.** A formula reads `input.<field>` (the trigger input, in autonomous routines), `message` (the customer's message, in conversational routines), `variable.<name>` (a declared variable) and `step.<step id>.<field>` (an earlier step's result, read as `step_output` reads it, `ok` included). Write a name with spaces or dashes in brackets: `step["get-magnet"].output.fields["Email Subject"]`; list positions the same way: `input.items[0]`. A position can be worked out, `input.items[count(input.items) - 1]`, and must then be in the list. A field whose name has a `.` can't be read.

**Writing formulas.** The functions below, called as `name(…)`; `+ - * /` (`+` also joins text); `== != < <= > >=`; `&& || !`; text in quotes, numbers, `true`, `false`, `null`, lists `[…]` and objects `{…}`. Write `if(test, a, b)`, not `test ? a : b`; `contains(list, x)`, not `x in list`. `==` and `!=` compare as rules do: `"10" == 10` is false, `10 == 10.0` is true, and a missing value equals `null`. `&&` and `||` skip the side they don't need, so `input.email != null && contains(lower(input.email), "@")` is `false` for a missing email, not a failure. Every value a formula names is still read before it runs, so a missing one on a side `&&`, `||` or `if()` doesn't take is flagged with the others even when the formula succeeds. In YAML, quote a formula that starts with `{`, `[` or `"`, or that contains `:` or `#` (single quotes keep the formula's own double quotes): `sent: '{"status": "sent", "subject": subject}'`. A pattern's `\d` is written as is; keep such a formula unquoted or in single quotes, since double-quoted YAML reads backslashes itself.

| Function                                                                     | Gives                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default(a, b)`                                                              | `a`, or `b` when `a` is empty                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `if(test, a, b)`                                                             | `a` when `test` is true, otherwise `b`; only the side taken runs, and `test` must be `true` or `false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `lower(t)`, `upper(t)`, `trim(t)`                                            | the text in lower case, in upper case, without spaces around it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `replace(t, old, new)`                                                       | `t` with every `old` replaced by `new`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `replace_pattern(t, pattern, new)`                                           | `t` with every match of the pattern replaced by `new`, as written, e.g. `replace_pattern(name, "[^A-Za-z0-9_-]", "_")`. The pattern is RE2, written as text in the formula                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `contains(t, x)`                                                             | whether text `t` contains `x`, or list `t` has an item equal to `x`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `extract(t, pattern)`                                                        | the first group in brackets that took part in the match the pattern finds in `t`, or the whole match when it has no groups; empty when it finds nothing, e.g. `extract(message, "(\d{5,})")`. The pattern is RE2, written as text in the formula                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `split(t, separator)`, `join(list, separator)`                               | text cut into a list; list items joined into text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `length(t)`                                                                  | the number of characters in text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `text(x)`                                                                    | a number or `true` / `false` as text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `json(x)`                                                                    | any value as JSON text, exactly: keys in the order written, accents kept. Use it to bind data to a text parameter, such as a file's content: `'json({"section": 1, "criteria": step.judge.output.criteria})'` (quoted, since it contains `:` ). A path inside with nothing to read is written as `null`, with a warning in the trace; wrap it in `default(...)` when the value must be there                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `values_at(x, keys)`                                                         | every text or number held under one of `keys` anywhere in `x`, at any depth, JSON written as text included; keys match without case or `_` (`PARTYID` is `party_id`); `true`, `false`, `null` and `""` are skipped, a list under a key gives its items, and an object, alone or in such a list, is read by its own keys (`values_at({"phones": [{"number": "1"}]}, ["phones"])` is `[]`); each value once, in the order found (`values_at(step.get_orders.output, ["order_id"])`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `find_all(x, pattern)`                                                       | each match of an RE2 pattern in every text anywhere in `x`, as `extract` gives it (the first group that took part, or the whole match), once, in the order found (`find_all(step.get_orders.output, "[^\d.](\d{5,})")`: the group leaves out the character before the digits); the pattern is written as text                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `anonymize(x, extra)`                                                        | `x` with every personal value replaced by a placeholder, the same for the same value however it is written, so a value a customer types can still be checked against the record's; `extra` is a list of further texts to replace the same way, such as values a model spotted (`[]` for none). The values found: any record's personal fields, read by the words of their key in any spelling (`firstName`, `FIRST_NAME`, `first_name_en`): names word by word, so a first name written alone gets the same placeholder as in the record (a first, given, middle, last, family or full name, `name` alone, and a name after words about a person such as `card_holder_name`; not a file's or a bank's name), usernames and logins, addresses, towns and birth places, postal codes, phones, emails, birth dates, IPs, IBANs, account, card, passport and other document numbers, a person's id (`user_id`, `PARTYID`; not a ticket's), coordinates; not a field about such a value (`email_status`, `phone_verified`, `ip_country`), read in objects at any depth and as `"key": "value"` in JSON text that does not parse, such as a record cut short (a field whose key names none of these is not found, so pass it in `extra`); names written in a message's text: the line after a sign-off (`Cordialement,` then `Mina - Service Clients`, up to `-` or a comma; not a line signed by a virtual assistant or a bot, the agent's persona), the capitalized words after a title (`Madame Nicole Cabal`), a greeting (`Bonjour Éric,`) or a self-introduction (`my name is Zied`), in French, English, Spanish, Portuguese, German and Italian, stopping at a word about a role (`Service`, `Team`), a word the text also writes in lower case, or a word of an email's or a link's domain (a brand); emails and the part before their `@` when it looks like a username (a digit, or `.` `_` `+` `-`; `support@` is left alone), phone numbers (international ones written with `+` or `00` and a country code, and French national ones such as `06 12 34 56 78`), numbers of 5 or more digits written in text (up to 3 letters before them; a number value counts only under a personal field), street addresses written number first, then a street type, then the name, which ends at the sentence's end and at its last word in capitals (`12 rue des Lilas` in `12 rue des Lilas is home.`; a name in lower case runs to the sentence's end; French, English, Spanish and Portuguese street types; `Calle Mayor 12` is not found), codes of 8 or more capital letters and digits, IPv4 and IPv6 addresses, IBANs (also written in groups of four), an identity card's machine-readable lines, and dates: the record's dates however a text writes them and any full date at least 16 years old, a birth date far more often than an event; values under 3 characters are left out of the text search, but replaced in a personal field (a street number `12`). The placeholders: a date gets one fake adult birth date written the way each occurrence is (`1999-08-14T00:00:00` and `14/08/1999` give, say, `1985-11-28T00:00:00` and `28/11/1985`; ISO with or without a time, day first with `/` `-` or `.`, 8 digits, a month in words in English, French, Spanish, Portuguese or German; month first when the second number can't be a month); a phone number other digits in the same layout, the last 9 the same in every form (`+33 6 12 34 56 78` and `06 12 34 56 78` stay one number); an IBAN other letters and digits in the same layout, its country code kept, the same however it is spaced; a name's word a realistic fake name from a fixed list (a first name field's words first names, a last name field's surnames, a full name's first word a first name and the rest surnames), so an agent that asks for a customer's name still sees a name; an address a fake street in its shape (its number other digits, its street type kept) and a town a fake town; an email a fake name at the same domain; an IPv4 address another one; a value given in `extra` that is only letters a fake name; any other value other letters and digits in the same shape (`jdupont77` → `kfmwqrt41`); each in the case of the text it replaces. It gives `{value, placeholders}`: `value` is `x` anonymized, and `placeholders` lists every fake it wrote, so a check for personal data left can tell realistic fakes from real values. Each value is replaced as `replace_all` replaces it, also inside a URL, a file name or `\u`-escaped JSON. A placeholder depends on the value only, so a later call that passes a value in `extra` gives it the placeholder an earlier one did. It is a heuristic: it misses what it doesn't know and can take an amount or a date (`20260301`). It pseudonymizes, best effort, not anonymization: the placeholders come from a short unsalted hash that can be undone by trying likely values, object keys stay, and the compute step's trace records its raw reads, so the raw values reach the trace |
| `replace_all(x, pairs)`                                                      | `x` with each pair's first text replaced by its second wherever it is a whole word in a text (no letter or digit next to it; a `\n` written out or a URL-encoded character such as `%20` right before it counts as a break), also written URL-encoded (`%20`, `+`, `%C3%A9`) or in JSON with `\u` escapes, the replacement then encoded the same way, so a name in an attachment's address is replaced too; in one pass, longest first; case and accents don't count, and the replacement is upper or lower case when the text it replaces is; a number equal to a first text is replaced too (a number again when the replacement is digits); object keys stay. Pairs are lists of two texts, so `map` can build them (`replace_all(step.get_orders.output, map(contacts, c, [c.name, c.alias]))`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `hash(t)`                                                                    | the SHA-256 of `t` in lowercase hex                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `diff(a, b)`                                                                 | the lines that changed from text `a` to text `b`, as a unified diff (`--- before`, `+++ after`, 2 lines around each change); `""` when they are equal. For a person to read what changed, such as a routine's YAML before and after an edit                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `number(t)`                                                                  | text as a number (`" 10.5 "` gives `10.5`; `"1,000"` fails)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `round(n)`, `round(n, places)`                                               | `n` rounded, halves away from zero                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `abs(n)`                                                                     | `n` without its sign                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `min(a, b)`, `max(a, b)`                                                     | the smaller, or the larger, of two numbers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `today()`, `now()`                                                           | today's date, or the date and time now, in the agent's timezone                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `date(d)`                                                                    | the date (`YYYY-MM-DD`) of a date and time                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `add_minutes(d, n)`, `add_hours(d, n)`, `add_days(d, n)`, `add_months(d, n)` | `d` moved by `n` (a whole number, may be negative); a date and time keeps its time of day                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `hours_between(a, b)`, `days_between(a, b)`                                  | hours, or calendar days, from `a` to `b`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `working_days_between(a, b)`                                                 | Monday-to-Friday days after `a`, up to and including `b`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `format_date(d, pattern)`                                                    | `d` written with `YYYY YY MMMM MMM MM M DD D dddd ddd HH H mm ss`, e.g. `"DD/MM/YYYY"`; text in `[…]` stays as written, e.g. `"[Due:] D MMM"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `first(list)`, `last(list)`                                                  | the first or last item; empty for an empty list                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `count(list)`                                                                | the number of items                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `sum(list)`                                                                  | the numbers added up; `0` for an empty list (`sum(map(tickets, t, t.score))`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `lookup(cells, key_column, key, value_column)`                               | in a spreadsheet's cells, each with its address (`{cell: "J2", value}`, as `filestore:read_excel` returns a sheet in `cells` mode), the value in `value_column` on the row whose `key_column` holds `key` (`lookup(cells, "A", 6, "J")`); the key matches as text, so `6`, `"6"` and `6.0` are one key; no row, or more than one, with the key fails; an empty cell is `null`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `filter(list, t, test)`                                                      | the items `test` holds for (`filter(tickets, t, t.score > 0.8)`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `map(list, t, value)`                                                        | `value` worked out for each item (`map(tickets, t, t.id)`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `exists(list, t, test)`, `all(list, t, test)`                                | whether `test` holds for at least one item, or for every item; `false` and `true` for an empty list                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `sort_by(list, t, key, order)`                                               | the items by `key`, `"asc"` (lowest first) or `"desc"`; keys are all numbers or all text, and items with equal keys keep their order                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `slice(list, start, end)`                                                    | the items from position `start` up to, not including, `end`, counting from 0; past the end is the end, so `slice(list, 0, 5)` is the first five, or fewer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `before(a, b)`, `after(a, b)`                                                | whether date `a` is earlier / later than `b`, as the rule operators compare                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `starts_with(t, s)`, `ends_with(t, s)`                                       | whether text `t` starts / ends with `s`, case included                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `matches(t, pattern)`                                                        | whether the pattern is found anywhere in `t`; RE2, written as text in the formula, as for the rule operator                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `is_empty(x)`                                                                | whether `x` is missing, `null`, `""`, `[]` or `{}`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

**Lists.** `filter`, `map`, `exists`, `all` and `sort_by` name each item, here `t`, for a formula they run once per item. The name is a plain name, not `input`, `variable`, `step`, `message` or a function, and means the item only inside that formula. A field an item lacks reads as `null`, with no warning, so `default(t.tags, [])` fills it. A test gives `true` or `false` for every item, or the formula fails. A per-item formula that fails fails the whole formula, even on a side of `&&` or `||` that isn't needed: write `if(a, exists(list, t, test), false)`, not `a && exists(list, t, test)`, to run it only when `a` holds. They nest, so one value can pick the five best matches in Portuguese, and another add up every score:

```yaml
  - id: pick_similar
    compute:
      top_pt: 'slice(sort_by(filter(step.search.output.tickets, t, t.score > 0.8 && t.lang == "pt"), t, t.score, "desc"), 0, 5)'
      total_score: 'sum(map(step.search.output.tickets, t, t.score))'
```

* **A missing value reads as empty,** as in rules, and the trace flags it as a warning; a path that meets `null` on the way reads as `null`, with no warning, so `if(timeout == null, "none", timeout.COMMENT)` stays quiet; a value empty because its step failed is noted with no warning, so `default(step.x.output.y, …)` after a failed step stays quiet too. `default(a, b)` gives `b` when `a` is missing, `null`, `""`, `[]` or `{}`. `before`, `after`, `starts_with`, `ends_with`, `matches` and `is_empty` hold as the rule operators do, so an empty value gives `false` for all but `is_empty`; every other function fails on a missing or `null` value. `""` and `[]` are values: `lower("")` is `""`.
* **Numbers are one kind,** as in JSON: `80 * 1.1` is `88`, `7 / 2` is `3.5`, a whole result stays whole, and dividing by zero fails.
* **Name a formula you use more than once** in the routine's `functions:`, `name(input, …): formula`, and call it from any formula of the routine: a compute value, a rule check, a bound value.

  ```yaml
  functions:
    is_vip(player): lower(player.tier) == "gold" && player.spend > 1000
  ```

  `when: {formula: "is_vip(step.get_player.output)"}` then checks the tier and spend of `get_player`'s result. A function reads only its inputs (pass `step`, `input`, `variable` or `message` values in), and calls the formula functions and the functions defined above it, never itself. Each call is checked and run as the function's formula with its inputs written in, in brackets where needed, so traces show the formula written out; the routine you saved keeps the call. Written out, a formula can be at most 20,000 characters and 500 function calls, or the routine is refused on save: a function that calls another twice copies it twice, so the text doubles with each such level.
* **Dates are text,** `YYYY-MM-DD` or ISO 8601 dates and times, read in the agent's timezone, as `built-in:date_math` reads them. `today()` and `now()` read one clock for the whole node.
* **A formula that fails fails the node,** as a tool would: its result is `{ok: false, error}` with the value and the reason, and the routine's `on_tool_error` applies. A rule can route on `ok`.
* A compute node's values are typed where they are used (a value's type is checked where it is used, unless the node declares its values in [`output`](#declaring-a-steps-output)), can't be terminal, and runs once per visit. When the routine is saved, its names, its formulas, the steps and input fields they read, and the values later nodes read from it are checked.
* **Types are checked on save,** in every formula (compute values, formula checks, formula arguments), where they are known: each function's inputs (`lower()` takes text, `days_between()` dates, `count()` a list), each operator's sides (`&&` true or false, `-` numbers, `+` two of a kind, `==` values that can be equal), and a check's formula gives `true` or `false`. A value's type comes from the routine's input schema, a step's declared `output` (every think node's; a tool or compute node's when it declares one), a step's `ok` / `step_id` / `error` / `runs`, `message`, a compute node's declared `input`, and the values above it; a list function's item is an item of its list. A tool's data or a variable passes and is checked when the formula runs; a value that may be `null` or of several kinds fits where one of its non-null kinds fits. For example, `lower(step.score.output.tier)` with `tier: {type: integer}` is rejected: `'step.score.output.tier' is a number, but lower() takes text`.

The trace shows an `Execute: Computing` group with a `Compute: <step id>` span per node: the values read, the values worked out, and no model call.

### Trying a formula

Saving a routine checks that a formula is well written and that its types fit. It does not check that the formula gives the value you meant. To see what it gives, send it to a deployed agent with sample data, before putting it in a routine:

```bash
curl --fail-with-body "$AGENT_URL/formulas/evaluate" \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "formula": "map(slice(sort_by(filter(tickets, t, t.score > 0.8), t, t.score, \"desc\"), 0, 5), t, t.id)",
    "cases": [
      {"data": {"tickets": [{"id": 1, "score": 0.9}, {"id": 2, "score": 0.5}, {"id": 3, "score": 0.95}]},
       "expect": [3, 1]},
      {"data": {"tickets": []}, "expect": []}
    ]
  }'
```

* Each case's `data` holds what the formula reads, named as the formula names it: `input`, `variable`, `step` (`{"get_player": {"ok": true, "output": {"tier": "gold"}}}` for `step.get_player.output.tier`) and `message`. Any other key is a value by that name, as a node's declared `input` or a value computed above it.
* Each result gives the `value`, or the `error` the step would fail with, the values it read (`reads`), and each read that found nothing (`missing`, read as `null`). With `expect`, it also says whether the value matched.
* Pass the routine's named functions in `functions`, and `now` (a date and time) to fix what `today()` and `now()` read.
* Try the values a formula will meet: a usual one, an empty one, and one with a field left out.

The formula runs with the evaluator of that agent's runtime version, with no model call and no tool. It can't tell whether a step really returns the shape you gave it: declare the step's `output` for that. The request and response are in the [HTTP API](https://docs.interactive.ai/agents/reference/http-api.md#try-a-formula).

## Asking the customer and acting on the answer

A chat node whose transitions depend on the customer's reply is the question-and-dispatch idiom:

```yaml
  - id: ask-resubmit
    chat_state: >
      Ask the customer if they would like to resubmit their documents.
    transitions:
      - to: generate-link
        condition: "The customer wants to resubmit"
      - to: acknowledge-no
        condition: "The customer does not want to resubmit"

  - id: generate-link
    tools: crm:generate_upload_link
    tool_instruction: "Generate a document upload link using PARTYID."
    transitions:
      - to: share-link

  - id: share-link
    chat_state: "Share the upload link with the customer."

  - id: acknowledge-no
    chat_state: "Acknowledge and offer further help."
```

The engine waits on the customer after `ask-resubmit` (the transitions depend on their answer), then takes the matching branch — possibly several turns later, and it can [backtrack](https://docs.interactive.ai/agents/concepts/routines.md#transitions-terminals-and-movement) if they change their mind.

## Reusable wording: macro interpolation

When the same explanation must appear verbatim in several flows, publish it as a [macro](https://docs.interactive.ai/agents/concepts/glossaries-and-macros.md#macros), pin it in the manifest's `context.macros`, and interpolate it inside `chat_state` with `${macro-id}`:

```yaml
  - id: explain-cancellation
    chat_state: |
      Here's how cancellation works for your booking:

      ${cancellation-policy}

      Would you like me to go ahead and cancel it?
    transitions:
      - to: await-decision
```

Only `chat_state` interpolates macros — `tool_instruction` and `description` take literal text. Macros are filled in once, when the agent starts; a `${input.name}` placeholder (with the dot) is not a macro and is filled in on every turn, from the node's [declared input](#declaring-a-steps-input).

Say what to communicate, not how to format it. The same routine can serve chat, voice and email, so keep `chat_state` and macros free of channel-specific formatting.

## Anti-patterns

| Anti-pattern                                                                        | Symptom                                                                        | Fix                                                                                                        |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| Tools + `chat_state` on one node                                                    | Schema rejects it                                                              | Split into tool node + chat node connected by a transition                                                 |
| Messaging inside `tool_instruction`                                                 | Tone leaks into tool calls; replies appear before data arrives                 | Move messaging to the following chat node                                                                  |
| Conditions narrating actions ("ask the user X if…")                                 | Transitions that half-do things                                                | Conditions gate; actions act                                                                               |
| Mega-nodes ("collect dates, search, present, and offer extras")                     | The model freelances the ordering                                              | One concern per node                                                                                       |
| Two chat nodes with no customer-dependent transition between them                   | Second one never runs in the same turn                                         | Merge the messages or make the dependency explicit                                                         |
| Duplicating a global rule in every routine                                          | Drift between copies                                                           | Make it a [policy](https://docs.interactive.ai/agents/guides/authoring-policies.md)                        |
| Hard-coding a business fact (an amount, a threshold, a delay) in routine text       | Copies drift when the fact changes                                             | Make it a [glossary](https://docs.interactive.ai/agents/concepts/glossaries-and-macros.md#glossaries) term |
| Deep tool chains exceeding the iteration cap                                        | Turn ends mid-flow / autonomous runs fail with `max_engine_iterations_reached` | Shorten, parallelise independent tools, or raise `runtime.max_engine_iterations`                           |
| Unconditioned multi-way branches                                                    | Schema rejects 2+ transitions without conditions                               | Condition every branch explicitly, or use rules with the node's `otherwise`                                |
| Asking the model to reformat a known value (lower-case an email, default a subject) | A model call per run, and a wrong value now and then                           | A [compute node](#working-values-out-compute-nodes)                                                        |

## Testing a routine

Before deploying, [try each formula](#trying-a-formula) against sample data.

1. Deploy it to a non-production agent against a stub MCP server (the [Quickstart](https://docs.interactive.ai/agents/guides/quickstart.md) builds one end to end).
2. Run the happy path and each branch, including the "changed my mind" backtrack. For a conversational routine, use replay scenarios (`iai agents replay`): fixed customer messages and recorded tool results against live reasoning, repeatable on every change. For an autonomous routine, trigger it with one input per branch (see [Authoring autonomous routines](https://docs.interactive.ai/agents/guides/authoring-autonomous-routines.md#testing-checklist)).
3. When you change an existing routine, also run the case that caused the change and the routine's existing cases, which must not change (write at least one if it has none yet).
4. Watch the trace for the turn — it shows activation, node selection, and each tool call; see [Observability](https://docs.interactive.ai/agents/guides/observability.md).
5. Check boot output: every routine logs `Routine '<title>' evaluated: N nodes in Xs` at startup — failures there mean structural problems.

## Pre-submit checklist

* [ ] `entry` names a declared node; every `transitions[].to` resolves
* [ ] No node combines `tools` with `chat_state`
* [ ] Every tool node that needs customer-facing output transitions to a chat node
* [ ] `tool_instruction` guides arguments only — no messaging, no conditions (those go on transitions)
* [ ] Known values are bound in `input`
* [ ] Values derived from known data are worked out in a compute node, not by the model
* [ ] Every multi-way branch conditions all of its transitions, or uses rules with the node's `otherwise`
* [ ] Sibling transition conditions do not overlap, and one covers the otherwise case
* [ ] Node ids unique
* [ ] Terminal nodes are intentional (no `transitions` means the routine ends there)
* [ ] Activation conditions name concrete triggers and exclude sibling routines
* [ ] Longest tool chain fits within `max_engine_iterations`
* [ ] Every `${macro-id}` in `chat_state` is pinned in `context.macros`
* [ ] A change to an existing routine is scoped to its situation: no new "always" or "regardless of …", no case content in a macro
* [ ] The case that caused a change and the routine's existing cases all pass


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.interactive.ai/agents/guides/authoring-routines.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
