The operation tree

operations is the ordered list that runs, top to bottom, when the model calls the tool. Each entry is an operation whose kind decides its other fields; an if holds two more lists, then and else.

[
  {
    "kind": "http",
    "config": {
      "method": "GET",
      "url": "https://api.example.com/orders/{{args.order_id}}",
      "headers": { "Authorization": "Bearer {{secrets.SHOP_API_KEY}}" }
    },
    "silent": true,
    "publish_fields": [{ "path": "status", "store": "tooldata" }]
  },
  {
    "kind": "say",
    "config": { "text": "Order {{args.order_id}} is {{tooldata.status}}." }
  }
]

Sending operations replaces the whole tree. PATCH /v1/tools/{tool_id} leaves omitted fields alone, but a tree you send is the entire tree: read it, change it, send it back.

The twelve kinds

Kind	What it does	Terminal
`http`	Calls a REST API and reads the JSON response
`code`	Runs TypeScript in a sandbox
`frontend_rpc`	Calls a handler your web page registered and waits for its answer
`if`	Compares two values and runs `then` or `else`	yes
`set_variable`	Writes one templated value into `tooldata` or `userdata`
`say`	Speaks a fixed line
`generate_reply`	Has the model phrase a line from your instructions
`add_message`	Adds a system message to the model’s context, without a reply
`send_dtmf`	Presses keys on the call’s keypad
`end_call`	Ends the call or chat	yes
`handoff`	Moves the conversation to another agent	yes
`transfer`	Puts a phone caller through to a person	yes

Fields on an operation

Each kind accepts only its own fields. A field from another kind — then on an http, publish_fields on a say — is rejected with a 422, not ignored.

Field	On	Default	Meaning
`kind`	every kind	required	One of the twelve above
`config`	every kind	required, except on `end_call`	The kind’s settings, documented on its page
`on_error`	every kind	`"abort"`	`abort` or `continue`, see below
`silent`	`http`, `code`, `frontend_rpc`	`false`	Run and publish, but keep the result away from the model
`publish_fields`	`http`, `code`, `frontend_rpc`	`[]`	Values to keep from the result — see templating and data
`background_execution`	`http`, `code`, `frontend_rpc`	`false`	Fire and forget: the tree does not wait, nothing is published, a failure only reaches our logs
`then`, `else`	`if`	`null`	The two branch chains

background_execution with publish_fields on the same operation is a publish error. silent still waits and still publishes; background_execution does neither.

`on_error`

Value	What happens
`abort` (default)	The tool stops. Nothing after the failing operation runs, and the model is handed `Sorry, I wasn't able to complete that just now.` as an error result. See when a tool fails.
`continue`	The failure is logged and the next operation in the same chain runs.

Under continue, the failed operation publishes nothing, so later templates that read its values resolve to empty. Validation cannot catch this: it checks what an operation declares, not whether it ran. On an if, continue means a condition that could not be evaluated runs neither branch and ends the tree, because nothing can follow an if.

Terminal operations and branches

if, handoff, end_call and transfer must be the last operation in their chain — the top-level list or any then / else list. A tree with an operation after one is refused at save, naming the operations that follow it. Branches never rejoin. There is no point after an if that both paths reach, so:

work needed on both paths is written into both;
a third path is a second if as the only operation in the first one’s else;
an early exit puts the exit in one branch and the rest of the flow in the other.

Anything that must happen before the call ends — logging an outcome, filing a lead — goes above the end_call or transfer.

What the model is told

After the tree runs, the model is handed one of:

Case	The model gets
The tool is silent, or the run reached `end_call` or a completed `transfer`	Nothing. It does not speak again on top of the tool
The tree handed off	Nothing; the target agent takes over
Otherwise	`{"responses": [{"operation": "http", "response": {...}}, ...]}`, one entry per non-silent `http`, `code` or `frontend_rpc` that ran, in order
Otherwise, with no entries	The string `Done.`

A tool is silent whenever no operation in it can return a response, whatever its own silent flag says. Only http, code and frontend_rpc return responses, and one with silent: true or background_execution: true does not count. So a tool that is a silent lookup plus a say speaks the say line and nothing else. This is derived at publish and cannot be turned off; to have the model add a line, add a generate_reply.

Timeouts

Every timeout in a tree is in seconds.

Kind	Field	Default	Range
`http`	`timeout`	20	above 0, at most 120
`code`	`timeout`	10	above 0, at most 30
`frontend_rpc`	`timeout`	5	above 0, at most 60
`transfer`	`ringing_timeout`	30	5 to 120

For an endpoint that is genuinely slow, set long_running_task on the tool so the agent keeps talking while it runs, rather than raising a timeout.

Where a kind is refused

Some kinds only work in some places. Each rule is enforced where it can first be known.

Rule	Enforced
A `long_running_task` tool cannot contain `transfer` or `handoff`	Tool publish
A tool wired to a lifecycle hook cannot contain `transfer`	Agent publish
`add_message` with `scope: "turn"` only in a tool wired to `on_user_turn_completed`	Agent publish
A tool attached to an agent task cannot contain `handoff`	Agent and task publish
`transfer` runs only on phone calls	At run time: the operation fails elsewhere
`frontend_rpc` runs only on web calls	At run time: the operation fails on text and phone
`send_dtmf` runs only where the call has a keypad	At run time: see keypad

The run-time rules cannot be checked at publish because one tool can be attached to a phone agent and a chat agent. A failure there is an ordinary operation failure, handled by on_error.

Templating and data

Template roots, tooldata vs userdata, and publish_fields.

Conditionals

The if operators and nested branches.

Patterns

Complete trees to start from.

Get started

Build

Guides

The operation tree

The twelve kinds

Fields on an operation

`on_error`

Terminal operations and branches

What the model is told

Timeouts

Where a kind is refused

Next

Templating and data

Conditionals

Patterns

​The twelve kinds

​Fields on an operation

​on_error

​Terminal operations and branches

​What the model is told

​Timeouts

​Where a kind is refused

​Next

Templating and data

Conditionals

Patterns

The twelve kinds

Fields on an operation

`on_error`

Terminal operations and branches

What the model is told

Timeouts

Where a kind is refused

Next