> 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/concepts/routines.md).

# Routines

Routines are graphs of nodes — chat, tool, and routing-only (fork) nodes connected by transitions. This page defines the node types and their runtime completion semantics.

> **Context** — Routines are the structured-flow building block of an agent (the cross-cutting one is [policies](https://docs.interactive.ai/agents/concepts/policies.md)). This page is the definitive model; [Authoring routines](https://docs.interactive.ai/agents/guides/authoring-routines.md) is the hands-on companion. If you read only one warning on this page, read [the node types](#node-types-read-this-first).
>
> 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).

## What a routine is

A routine is a versioned YAML document describing a **graph** the agent walks through across one or many turns: nodes carry actions, and each node lists its outbound transitions. Execution starts at the node named by `entry`.

```yaml
id: car-search
title: Car Search
conditions:
  - >
    The user wants to browse the fleet, find a car, or asks for car
    suggestions — phrases like "what cars do you have", "show me an SUV",
    "I need a 7-seater". Do NOT activate when the user is referring to a
    specific booking they already have.
description: >
  Help the user narrow down the fleet to one or two candidate cars by
  collecting their criteria, searching the catalog, and presenting results
  with prices.

entry: gather-criteria
nodes:
  - id: gather-criteria
    chat_state: >
      Ask the user for their preferences in one short message: category
      (economy / compact / SUV / van / luxury), minimum number of seats,
      transmission preference, and any daily-budget cap in EUR. Tell them
      any field is optional.
    transitions:
      - to: run-search
        condition: >
          The user has provided at least one preference, or has said
          "anything" / "no preference".

  - id: run-search
    tools: cars:search_cars
    tool_instruction: >
      Call search_cars with the filters the user provided. Pass null /
      omit fields the user did not mention. Do not invent constraints.
    transitions:
      - to: present-results

  - id: present-results
    chat_state: >
      Summarise the matching cars in a compact list — one line per car
      with make, model, category, transmission, and daily price in EUR.
      End by asking if the user wants to book one.
```

## Top-level fields

| Field         | Type                                                                                                                                       | Required            | Default | Meaning                                                                                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`       | string                                                                                                                                     | yes                 | —       | Display name in the platform UI, traces, and logs.                                                                                                                            |
| `conditions`  | string, [prompt reference](https://docs.interactive.ai/agents/concepts/prompts.md#instructions-from-the-prompt-library), or a list of them | yes (≥ 1 non-empty) | —       | When the routine activates. Evaluated like policy conditions; the routine activates when **any** condition matches.                                                           |
| `entry`       | string                                                                                                                                     | yes                 | —       | Id of the node where execution starts. Must match a declared node id.                                                                                                         |
| `nodes`       | list of node objects                                                                                                                       | yes (≥ 1)           | —       | The graph (below). Each node is declared exactly once; node ids must be unique.                                                                                               |
| `id`          | string                                                                                                                                     | no                  | `null`  | Optional in-document id. Identity actually comes from the catalog name the document is published under — that name is what the manifest's `context.routines[].id` references. |
| `description` | string                                                                                                                                     | no                  | `null`  | Long-form purpose. Not used for matching.                                                                                                                                     |
| `policies`    | list of policy objects                                                                                                                     | no                  | `null`  | Routine-scoped policies (each requires an explicit `id`) — see [Policies](https://docs.interactive.ai/agents/concepts/policies.md#scoping-agent-wide-vs-routine-scoped).      |
| `autonomous`  | object                                                                                                                                     | no                  | `null`  | Makes the routine triggerable as a typed automation — see [Autonomous routines](https://docs.interactive.ai/agents/concepts/autonomous-routines.md).                          |

## Node fields

| Field                          | Type                                                                                                                      | Required | Default  | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                           | string                                                                                                                    | yes      | —        | Unique within the routine. Referenced by `entry` and by `transitions[].to`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `title`                        | string                                                                                                                    | no       | `null`   | The step's short name, shown as its heading in the agent UI's runs view; without it the UI shows the node `id`. Never read by the engine or shown to the customer, and editing it does not change the routine's node ids.                                                                                                                                                                                                                                                                                                                              |
| `description`                  | string                                                                                                                    | no       | `null`   | Author note, shown when the step is expanded in the agent UI; never read by the engine or shown to the customer, and editing it does not change the routine's node ids.                                                                                                                                                                                                                                                                                                                                                                                |
| `tools`                        | string or list of strings                                                                                                 | no       | `null`   | TOOL node: tool id(s) to call, `service:tool` form (a bare string is normalised to a one-element list).                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `tool_instruction`             | string or [prompt reference](https://docs.interactive.ai/agents/concepts/prompts.md#instructions-from-the-prompt-library) | no       | `null`   | TOOL node: guidance for filling the tools' arguments. The tools always run when the node is reached; conditions belong on the transitions into it. Never shown to the customer. Requires `tools`.                                                                                                                                                                                                                                                                                                                                                      |
| `input` (TOOL)                 | object                                                                                                                    | no       | `null`   | TOOL node: where each argument comes from (`literal`, `variable`, `input`, `step_output`, or `llm` with instructions), keyed by tool then parameter — see [Authoring routines](https://docs.interactive.ai/agents/guides/authoring-routines.md#arguments). Named `tool_arguments` before schema 1.2.0; the old name still loads.                                                                                                                                                                                                                       |
| `awaits_customer`              | boolean                                                                                                                   | no       | inferred | CHAT nodes only: wait for a customer reply before advancing. Defaults to `true` when the node has transitions, otherwise `false`. An explicit value overrides either default.                                                                                                                                                                                                                                                                                                                                                                          |
| `chat_state`                   | string or [prompt reference](https://docs.interactive.ai/agents/concepts/prompts.md#instructions-from-the-prompt-library) | no       | `null`   | CHAT node: instruction for what the agent should say. Supports `${macro-id}` interpolation — see [Glossaries & macros](https://docs.interactive.ai/agents/concepts/glossaries-and-macros.md#macros) — and `${input.name}` placeholders for the values the node declares in `input`.                                                                                                                                                                                                                                                                    |
| `transitions`                  | list of `{to, condition? \| when?}`                                                                                       | no       | `[]`     | Outbound edges; a `condition` may be a [prompt reference](https://docs.interactive.ai/agents/concepts/prompts.md#instructions-from-the-prompt-library). **Omitted/empty = terminal node.** With 2+ entries, every transition requires a `condition`, or a TOOL, THINK or COMPUTE node routes by rules: `when` on every transition, and `otherwise` on the node — see [Rules on transitions](https://docs.interactive.ai/agents/guides/authoring-routines.md#rules-on-transitions).                                                                     |
| `otherwise`                    | node id                                                                                                                   | no       | `null`   | The node taken when none of the node's `when` rules holds. Required on a node whose transitions have `when`, and only there; it may be the node itself, to run it again.                                                                                                                                                                                                                                                                                                                                                                               |
| `think`                        | string or [prompt reference](https://docs.interactive.ai/agents/concepts/prompts.md#instructions-from-the-prompt-library) | no       | `null`   | The typed-inference (THINK) node instruction; see [Autonomous routines](https://docs.interactive.ai/agents/concepts/autonomous-routines.md#node-types).                                                                                                                                                                                                                                                                                                                                                                                                |
| `compute`                      | object                                                                                                                    | no       | `null`   | The COMPUTE node: value names mapped to formulas, worked out with no model call. Mutually exclusive with every other action, and never terminal; see [Working values out](https://docs.interactive.ai/agents/guides/authoring-routines.md#working-values-out-compute-nodes).                                                                                                                                                                                                                                                                           |
| `output`                       | object                                                                                                                    | no       | `null`   | On a THINK node, required: the JSON Schema its structured output must match (named `output_schema` before schema 1.2.0; the old name still loads). On a tool node calling one tool, or a COMPUTE node, optional: the JSON Schema of the result it returns; every declared field is required unless `optional: true`. Reads of the step are checked against it on save, and a result that doesn't match fails the step. See [Declaring a step's output](https://docs.interactive.ai/agents/guides/authoring-routines.md#declaring-a-steps-output).      |
| `input` (THINK, COMPUTE, CHAT) | object                                                                                                                    | no       | `null`   | Named, typed values a THINK, COMPUTE or CHAT node reads, each from a source as an argument binding has one. A THINK node then sees only these values; a COMPUTE node's formulas read them by name; a CHAT node's `chat_state` places them with `${input.name}`, filled in on every turn. Each read is checked on save, and a value missing or of the wrong type blocks a THINK or COMPUTE step (a CHAT step gets empty text). See [Declaring a step's input](https://docs.interactive.ai/agents/guides/authoring-routines.md#declaring-a-steps-input). |

Machine-validated rules (enforced by the published JSON Schema): unique node ids; `entry`, every `transitions[].to` and `otherwise` must name declared nodes; `tools` is mutually exclusive with `chat_state`; `tool_instruction` requires `tools`; a node must carry an action (`tools` or `chat_state`) **or** at least one transition; 2+ transitions ⇒ all conditioned, or rules with the node's `otherwise`; malformed `${…}` macro tokens in `chat_state` are rejected. (The schema also defines the `think`/`output` and `compute` nodes described below.)

## Node types: read this first

A conversational routine is built from **three node types**. Each node is exactly one of them, determined by its action field:

| Node type                     | Set by                                      | What it is                                                                                                                                                            |
| ----------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **CHAT**                      | `chat_state`                                | Speaks to the customer. Completes when the agent sends a message fulfilling the instruction. May interpolate `${macro-id}` and place declared `${input.name}` values. |
| **TOOL**                      | `tools` (+ `tool_instruction`)              | Calls one or more tools. Completes when the tool executes — it produces no message of its own.                                                                        |
| **Routing-only** (the *fork*) | no action field, 2+ conditional transitions | A pure branch point — no tool call, no message. The engine evaluates the outgoing conditions and takes the matching path. This is how a routine **forks**.            |

> Two more node types work something out without speaking: **THINK** (typed inference by the model) and **COMPUTE** (formulas, no model call), described with [autonomous routines](https://docs.interactive.ai/agents/concepts/autonomous-routines.md#node-types) and used in conversational routines too. Neither has customer-facing output: a chat node after them tells the customer. A THINK node's output is stored in `session.metadata.step_outputs[<node-id>]`, and `think` node ids must be unique across the agent's routines.

> ⚠️ **The classic bug.** `tools` and `chat_state` on the same node is rejected by the schema — and for good reason: "create the ticket *and* tell the customer it's registered" must be **two nodes**. A tool node's customer-facing output belongs in a follow-up chat node. The one exception is [`built-in:initiate_human_handoff`](https://docs.interactive.ai/agents/reference/built-in-tools.md#built-ininitiate_human_handoff), whose `customer_message` parameter *is* the turn's reply — a handoff is a single tool node.

## Runtime semantics by node kind

### CHAT node: completes when the agent speaks

The engine generates a message fulfilling the `chat_state` instruction; that message **ends the turn**. If the outbound transition's condition depends on the customer's answer, the routine waits on the customer before advancing. Two CHAT nodes can never run in the same turn.

### TOOL node: completes when the tool executes

The engine calls the tool(s), appends the results to history, and immediately re-evaluates — walking the node's transitions **within the same turn**. Chains of TOOL nodes execute back-to-back without customer interaction.

Each chained think/tool node consumes one iteration of the per-turn engine loop, bounded by `runtime.max_engine_iterations` (default 5). A routine that chains more nodes than that back-to-back before reaching a message or terminal node has its turn cut off mid-chain — the engine logs a WARNING and responds anyway with whatever it has, nothing surfaced to the caller. Keep such chains within the cap, or raise it.

(Need a node that reasons over typed data instead of speaking or calling a tool? That's a **THINK** node, or a **COMPUTE** node when a formula can work it out — see [autonomous routines](https://docs.interactive.ai/agents/concepts/autonomous-routines.md#node-types).)

### Routing-only node (fork): completes immediately

No action — just conditional transitions. The engine evaluates the outgoing conditions and takes the matching branch. This is the routine's **fork**: use one wherever the flow splits on a decision rather than on a tool call or a message.

"Completes immediately" means it never produces a message or consumes a turn — it does not mean the branch choice is free. A fork with two or more outgoing transitions still requires a model call to pick between them, the same next-step selection used by other node kinds. Only a node with a single outgoing edge (fork or otherwise; a TOOL node once its call for this visit has a result) takes the zero-model fast path — and a TOOL, THINK or COMPUTE node whose transitions are rules, once its call for this visit has a result, which the engine checks itself.

```yaml
  - id: status-route
    transitions:
      - to: active-path
        condition: "account status is ACTIVE"
      - to: suspended-path
        condition: "account status is SUSPENDED"
```

## Transitions, terminals, and movement

* A transition's `condition` decides when that edge is followed. A node with exactly **one** transition may omit the condition (unconditional); a node with **2+** transitions must condition every one. On a TOOL, THINK or COMPUTE node, a lone transition's condition is not checked: the node moves on once its call has a result. To route on that result, use rules (next point).
* In either kind of routine, a TOOL, THINK or COMPUTE node can branch on rules (`when`, and `otherwise` on the node) instead: the engine checks them in order once the node has run, with no model call. See [Rules on transitions](https://docs.interactive.ai/agents/guides/authoring-routines.md#rules-on-transitions).
* **No `transitions` = terminal node.** When a terminal node completes, the routine is done. (In autonomous routines, terminal nodes must call `built-in:emit_output`.)
* **Fan-in and cycles are allowed** — any node id can be the target of multiple transitions, including loops back to earlier nodes ("ask again until the data validates").
* The engine can **backtrack**: if the customer revisits an earlier topic ("actually, change the dates"), evaluation can re-enter a previous node rather than forcing forward-only movement.
* Activation and advancement decisions are evaluation-model calls — see [Conversation lifecycle](https://docs.interactive.ai/agents/concepts/conversation-lifecycle.md).

## Prerequisites

Routines do not declare a prerequisite guard in their content. To keep a routine dormant until a tool has run (for example authentication), declare the guard once on the agent under `context.relationships.requires` — see [Prerequisites](https://docs.interactive.ai/agents/concepts/priorities.md#prerequisites-requires) on the priorities page. The same routine content can then be pinned on a chat agent that guards it and an email agent that does not.

## Referencing from the manifest

```yaml
agent_config:
  context:
    routines:
      - id: car-search
        version: 1
      - id: book-a-car
        version: 1
```

Pins are exact versions from the platform catalog. At boot, the server also pre-computes behavioural metadata for every routine, in two sequential stages: customer-dependence is computed first, then node reachability, which reads the customer-dependence result. On a cold cache this is the slow part of startup — see [Startup evaluation](https://docs.interactive.ai/agents/concepts/startup-evaluation.md).

## See also

* [Authoring routines](https://docs.interactive.ai/agents/guides/authoring-routines.md) — patterns, anti-patterns, checklist
* [Autonomous routines](https://docs.interactive.ai/agents/concepts/autonomous-routines.md) — typed input/output automations
* [Glossaries & macros](https://docs.interactive.ai/agents/concepts/glossaries-and-macros.md) — `${macro-id}` interpolation
* [Priorities](https://docs.interactive.ai/agents/concepts/priorities.md) — when routines compete with each other or with policies
* [Priorities & entailments](https://docs.interactive.ai/agents/concepts/priorities.md#prerequisites-requires) — the manifest `requires:` guard


---

# 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/concepts/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.
