> 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/reference/built-in-tools.md).

# Built-in tools

Call contracts for the built-in tools: emit\_output (terminates autonomous runs), reason (typed think-step inference), initiate\_human\_handoff (human escalation), current\_datetime (engine-refreshed time

> **Context** — The runtime ships five synthetic tools under the `built-in` namespace. Authors normally meet them through manifest or routine syntax (`think:` steps; autonomous terminal steps; handoff nodes; the `context.current_datetime` block; a policy or routine node listing `built-in:date_math`); this page is the exact call contract — what the model is asked to supply and every result the handler can return.

`emit_output` and `reason` take nested JSON **as a JSON-encoded string parameter** (`output_json`) — tool parameters are primitive-typed, so objects are marshalled through strings. Both return `{"ok": true, ...}` on success and `{"ok": false, "error": <code>, ...}` on failure; a failed call is visible to the model, which can retry with corrected output within the turn's iteration budget.

## `built-in:emit_output`

Terminates an [autonomous run](https://docs.interactive.ai/agents/concepts/autonomous-routines.md) with its typed result. Every terminal node of an autonomous routine (a node with no outbound transitions) must be a TOOL node calling it.

| Parameter     | Type                         | Meaning                                                                                                                                       |
| ------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `output_json` | string (JSON-encoded object) | The run's final output. Must parse as JSON and validate against the routine's `output_schema` (tightened with `additionalProperties: false`). |

On success the run transitions to `succeeded` and the callback watcher fires. Schema violations transition the run to `failed` with error code `output_validation_failed`; the tool result's `message` and `path` name the violation (so the model can correct the payload) and the callback's `error.details` carries the violating path.

| Result `error`             | Meaning                                                                                                        |
| -------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `output_validation_failed` | `output_json` didn't parse, or violated `output_schema` — the run fails. `message`/`path` carry the violation. |
| `not_an_autonomous_run`    | Called in a session that isn't an autonomous run.                                                              |
| `routine_not_registered`   | Session metadata names a routine the runtime doesn't know.                                                     |
| `session_not_found`        | The session disappeared mid-run.                                                                               |
| `not_configured`           | Autonomous runtime not wired (server misconfiguration).                                                        |

Usage in a routine:

```yaml
- id: finish
  tools: built-in:emit_output
  tool_instruction: >
    Call emit_output with output_json set to a JSON object
    containing exactly the decision and explanation fields
    produced by the assess node.
```

## `built-in:reason`

Backs the `think:` node kind — typed structured inference that does **not** end the turn. The loader compiles each `think:` + `output:` node into a TOOL node calling this tool with the node's id baked into the instruction.

| Parameter     | Type                         | Meaning                                                                                                                                        |
| ------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `step_id`     | string                       | The think node's id (the parameter keeps its historical wire name; the value is compiled into the node's instruction — not chosen at runtime). |
| `output_json` | string (JSON-encoded object) | The inference result. Must validate against the node's `output` (tightened with `additionalProperties: false`).                                |

On success the validated object is merged into `session.metadata.step_outputs[<node-id>]` and returned in the tool result, so downstream steps see the typed fields in history.

| Result `error`             | Meaning                                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------------------- |
| `output_validation_failed` | `output_json` didn't parse or violated the node's schema — the model can correct and retry.          |
| `missing_step_id`          | Empty `step_id` argument.                                                                            |
| `step_not_registered`      | No `output` schema registered for this node id (in an autonomous run, for this routine and node id). |
| `session_not_found`        | The session disappeared.                                                                             |
| `persist_failed`           | Writing `step_outputs` to the session failed.                                                        |
| `not_configured`           | Reason-step registry not wired (server misconfiguration).                                            |

Authoring guidance for think nodes: [Routines](https://docs.interactive.ai/agents/concepts/routines.md#node-types-read-this-first) and [Autonomous routines](https://docs.interactive.ai/agents/concepts/autonomous-routines.md#node-types).

## `built-in:compute`

Backs the `compute:` node kind. The engine works the node's formulas out itself, with no model call, and calls this tool with the values; the tool returns them as the node's result, which later steps read with `step_output` (`output.<name>`).

| Parameter     | Type                         | Meaning                                      |
| ------------- | ---------------------------- | -------------------------------------------- |
| `step_id`     | string                       | The compute node's id.                       |
| `output_json` | string (JSON-encoded object) | The values the formulas worked out, by name. |

A formula that fails never reaches this tool: the request fails with `failed_stage: compute`, the value and the reason in `error_details`, and `on_tool_error` applies. Formulas and functions: [Working values out](https://docs.interactive.ai/agents/guides/authoring-routines.md#working-values-out-compute-nodes).

## `built-in:initiate_human_handoff`

Escalates the conversation to a human. The handler records the intent on session metadata (`agent_handoff` — see [Session metadata](https://docs.interactive.ai/agents/reference/session-metadata.md)), settles what the customer sees on this turn, and, unless opted out, flips the session to `manual` mode via the tool result's control channel — the engine stops auto-replying from the next turn until the integration hands the session back with `set_automatic_mode()`.

| Parameter          | Type                                   | Meaning                                                                                                                                                                                                                                              |
| ------------------ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reason`           | string                                 | Why the escalation happened.                                                                                                                                                                                                                         |
| `internal_note`    | string (optional)                      | Comment for the human taking over. Staff-facing only: the engine never emits it, and the integration must never show it to the customer.                                                                                                             |
| `customer_message` | string (optional)                      | The customer's reply for this turn, emitted verbatim by the engine as an ordinary agent message. When set, response generation is skipped.                                                                                                           |
| `silent`           | boolean (default `false`)              | Send nothing to the customer on this turn and skip response generation — for channels where a human answers directly (email). Ignored when `customer_message` is set.                                                                                |
| `metadata_json`    | string (optional, JSON-encoded object) | Extra integration-facing values (e.g. ticket classification), stored verbatim as the payload's `metadata` and never interpreted by the engine. A value that isn't a JSON object is dropped (the handoff still proceeds; the result message says so). |
| `disable_agent`    | boolean (default `true`)               | When false, the session stays in `auto` mode — for channels whose integration manages lockout itself.                                                                                                                                                |

Exactly one of three things happens on the customer channel: `customer_message` is sent as written; `silent` sends nothing; with neither, the response stage generates the reply as on any other turn. The engine decides from the tool result, never from the model's judgement about whether to reply — so a handoff cannot duplicate the farewell or improvise one. In the first two cases the turn also ends at the tool: the engine runs no further preparation iteration, so no other tool executes after the escalation. Pin `customer_message` / `silent` and `disable_agent` per channel in `tool_instruction`; don't leave them to the model.

First write wins: once a session carries a handoff, later calls return `Human handoff was already initiated.` without overwriting it (the channel directive of the later call is still honored). The tool never fails the turn — on a storage error the model is still told the handoff is initiated (operators see an ERROR log) and the mode flip and channel directive still apply.

The full payload (`{reason, internal_note, customer_message, silent, metadata}`) is also mirrored into the tool result's `metadata` (invisible to the model), so the session's `tool` event carries it under `tool_calls[].result.metadata.agent_handoff` — including when the session-metadata write failed. When the tool ran, the turn's trace output is this payload plus the requested `mode`, in place of the list of agent messages.

The integration commits the handoff when the turn's `status: ready` event arrives (ordered after the customer message, when there is one): read `agent_handoff` from session metadata (or take it from the tool event), attach the internal note as a private comment, perform channel-side effects (ticket reassignment, tags), and track its own committed marker. There is nothing to deliver to the customer.

Usage in a routine — a single tool node; the customer-facing text is a parameter, so no chat node follows:

```yaml
- id: handoff
  tools: built-in:initiate_human_handoff
  tool_instruction: >
    Call initiate_human_handoff with the escalation reason, an
    internal_note for the human team summarizing the customer's issue
    and what was attempted, and a short customer_message telling the
    customer a human agent is taking over.
```

On a channel where the human replies directly (email), instruct `silent: true` and no `customer_message` instead.

## `built-in:current_datetime`

Backs the `current_datetime` context variable declared by the manifest's `context.current_datetime` block. Unlike the other built-ins it is **never called by the model**: the engine invokes it deterministically at the start of every turn to refresh the variable, and the result lands in the model's context via the VARIABLES prompt section. It takes no parameters and cannot fail.

Result data:

| Field      | Meaning                                                                                              |
| ---------- | ---------------------------------------------------------------------------------------------------- |
| `datetime` | Current local time, minute-precision ISO-8601 with UTC offset (e.g. `2026-09-01T14:37+01:00`).       |
| `weekday`  | English weekday name (e.g. `Tuesday`).                                                               |
| `timezone` | The IANA timezone the timestamp is rendered in (`context.current_datetime.timezone`, default `UTC`). |

Enabling it in the manifest:

```yaml
context:
  current_datetime:
    timezone: Europe/Lisbon  # optional, defaults to UTC
```

## `built-in:date_math`

Exact date and time arithmetic. Models miscount days, months and hours, so the model only turns the customer's words into dates and signed numbers, and the tool computes the result. Like any other tool, it runs only when a routine node or a matched policy lists it in `tools`. It does not count business days or parse natural language.

**One rule decides how a unit counts.** Days, weeks, months and years move the calendar date and give a date, even when `date` had a time. Hours and minutes add exact elapsed time and give a date and time. Sunday 21:06 plus 1 day is reached at any time on Monday; plus 24 hours, it is reached at 21:06 on Monday. Across a daylight-saving change, 24 hours stays 24 real hours: in Europe/Lisbon, `2026-03-28T12:00` plus 24 hours is `2026-03-29T13:00:00+01:00`, and plus 1 day is the date `2026-03-29`. A day the target month lacks becomes the month's last day (`2026-01-31` plus 1 month is `2026-02-28`); days and weeks never clamp.

| Parameter      | Type                                                                        | Meaning                                                                                                                          |
| -------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `date`         | string                                                                      | The date or moment to start from: `YYYY-MM-DD` with the full year, an ISO 8601 timestamp, or `now` (`today` is the same moment). |
| `add`          | integer (optional)                                                          | How many units to move `date` by. Negative goes back: tomorrow is `date: today, add: 1`, yesterday is `add: -1`. Adds `shifted`. |
| `unit`         | string (optional): `minutes`, `hours`, `days`, `weeks`, `months` or `years` | What `add` counts. Defaults to `days`. Sent without `add`, the result is `missing_add`.                                          |
| `until`        | string (optional)                                                           | A second date or moment, written and read the same way as `date`. Adds `until`, the gap from `date` to it, and `reached`.        |
| `next_weekday` | string (optional): `monday` to `sunday`                                     | Adds `next_weekday`: the first such weekday strictly after the date of `date`, or of the shifted value when `add` is set.        |
| `timezone`     | string (optional)                                                           | An IANA timezone name. Defaults to `context.current_datetime.timezone` (default `UTC`); an empty string also means the default.  |

The effective timezone is `timezone` when set, otherwise the agent's. It decides how `date` and `until` are read:

* `now` and `today` are the current moment in the effective timezone, with its time of day.
* `YYYY-MM-DD` is a date with no time. Where an exact time is needed, it counts as the first moment of that date in the effective timezone. That moment is 00:00 unless a clock change skips midnight: in America/Sao\_Paulo, `2018-11-04` starts at `01:00-02:00`. Its date stays `2018-11-04`.
* A timestamp without an offset is read in the effective timezone. A timestamp with an offset, `Z` included, is converted to it. Either way, its date is its date in that timezone.
* A local time that a clock change skips moves forward by the length of the gap. A local time that a clock change repeats is the first of the two. In Europe/Lisbon, `2026-03-29T01:30` is `2026-03-29T02:30:00+01:00` and `2026-10-25T01:30` is `2026-10-25T01:30:00+01:00`. This is the `compatible` rule of java.time and JavaScript Temporal. Neither case is an error, so a routine that binds a timestamp does not stall on one.

One `timezone` sets how timestamps without an offset are read and which calendar date every timestamp falls on, with or without an offset. For `hours` and `minutes`, only the reading matters. For days and longer, choose the calendar the rule counts in. A rule counted on UTC dates, such as a 12-month exclusion stored in UTC, binds `timezone: UTC` even when the timestamps end in `Z`: otherwise `2026-06-22T23:15:00Z` falls on 23 June in Europe/Lisbon. A rule counted on the agent's local dates leaves `timezone` unset, and its system should send timestamps with an offset.

Result data:

| Field                              | Present                                       | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ok`                               | always                                        | `true` on success.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `now`, `today`, `timezone`         | always                                        | The current moment (ISO 8601 to the second, with offset), its date, and the effective timezone.                                                                                                                                                                                                                                                                                                                                                             |
| `date`                             | always                                        | `{date, weekday}` of `date`, plus `datetime` (ISO 8601 to the second, with offset) when it has a time. `now` and `today` have one.                                                                                                                                                                                                                                                                                                                          |
| `shifted`, `until`, `next_weekday` | `add` (even `0`), `until`, `next_weekday` set | One block each for the shifted value, `until` and the next weekday: `{date, weekday, days, summary}`, plus `datetime` when the value has a time, plus the fields below. `days` is signed and counts calendar dates from the date the block counts from: `date` for `shifted` and `until` (never the shifted value), and the shifted date, else `date`, for `next_weekday`. Equal dates are `0` and consecutive dates `1`, so `next_weekday.days` is 1 to 7. |
| `shifted.clamped_to_month_end`     | `add` set                                     | `true` when a `months` or `years` shift landed on the last day of a shorter month.                                                                                                                                                                                                                                                                                                                                                                          |
| `until.calendar`                   | `until` set                                   | The same gap as `{years, months, days}`, with the sign of `days`.                                                                                                                                                                                                                                                                                                                                                                                           |
| `until.elapsed`                    | `date` and `until` both have a time           | `{total_seconds, hours, minutes, seconds}`. `total_seconds` is `until` minus `date` in whole seconds, signed and truncated toward zero, so one second short of 24 hours never reads as 24 hours. `hours`, `minutes` and `seconds` split its absolute value, and `hours` is not wrapped into days.                                                                                                                                                           |
| `reached`                          | `until` set                                   | `true` when `until` is at or after `date`, moved by `add` when set, so exactly 24 hours reaches `add: 24, unit: hours`. Compared by exact time when that value has a time of day (a timestamp, or an `hours`/`minutes` shift), otherwise by date. Without `add` it answers "has this deadline passed?": `date: <deadline>, until: now`.                                                                                                                     |

Every `summary` is one plain sentence the model can repeat: the block's date is N days after or before the date it counts from, or the same day as it. A `shifted` in `hours` or `minutes`, and an `until` with `elapsed`, also name both times with their UTC offsets and the exact elapsed time with its direction, such as `13 hours 48 minutes 18 seconds after` or `the same time`. A local time that a clock change repeats shows a different offset on each occurrence.

A withdrawal requested at `2026-10-18T21:06:17` (UTC) and checked at `2026-10-19T10:54:35` has not reached 24 hours. Called with `add: 24`, `unit: hours`, `until: 2026-10-19T10:54:35` and `timezone: UTC`, these three fields of the result, keyed by path, show why:

```json
{
  "shifted.datetime": "2026-10-19T21:06:17+00:00",
  "until.elapsed": {"total_seconds": 49698, "hours": 13, "minutes": 48, "seconds": 18},
  "reached": false
}
```

An invalid value returns `ok: false` instead of failing the tool call, so `on_tool_error` does not run:

```json
{"ok": false, "error": "invalid_date", "parameter": "until", "message": "Use YYYY-MM-DD with the full year, an ISO 8601 timestamp, 'today' or 'now'."}
```

| Result `error`     | Meaning                                                                                                         |
| ------------------ | --------------------------------------------------------------------------------------------------------------- |
| `invalid_date`     | `parameter` (`date` or `until`) is not `YYYY-MM-DD` (with a real day), an ISO 8601 timestamp, `today` or `now`. |
| `invalid_timezone` | `timezone` is not an IANA timezone name. `parameter` is `timezone`.                                             |
| `missing_add`      | `unit` was sent without `add`. `parameter` is `add`.                                                            |
| `out_of_range`     | A date, the shift or the next weekday falls before year 1 or after year 9999. No `parameter`.                   |

An argument of the wrong type or outside its allowed values, such as `unit: hour`, gets no `ok: false` result. It is rejected before the call: a bound literal fails boot, and a generated one fails the tool request.

Usage in a policy, so the model computes dates instead of guessing:

```yaml
id: exact-dates
name: Exact Dates
condition: >
  The customer asks about a deadline, an expiry, how long ago something
  happened, or a date some days, weeks or months away.
action: Compute the date with the tool before answering; never work out dates yourself.
tools: [built-in:date_math]
```

Usage in an autonomous routine, as a gate on whether a withdrawal has been pending at least 24 hours. The input's `requested_at` is a UTC timestamp without an offset, so `timezone` is bound to `UTC`. The transitions branch on `reached` instead of asking the model to compare numbers. A third transition handles `ok: false`, which a malformed `requested_at` returns:

```yaml
- id: pending-24-hours
  tools: built-in:date_math
  input:
    built-in:date_math:
      date:
        source: input
        path: requested_at
      add:
        source: literal
        value: 24
      unit:
        source: literal
        value: hours
      until:
        source: literal
        value: now
      timezone:
        source: literal
        value: UTC
  transitions:
    - to: escalate-delay
      condition: "the date_math result has reached: true"
    - to: explain-processing-time
      condition: "the date_math result has reached: false"
    - to: report-bad-timestamp
      condition: "the date_math result has ok: false"
```


---

# 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/reference/built-in-tools.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.
