> 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/schemas/readme.md).

# Schemas 1.4.0

***

## Agents

### Compatibility Matrix

| Agent Version | Schema Version |
| ------------- | -------------- |
| `1.4.0`       | `1.4.0`        |
| `1.3.0`       | `1.3.0`        |
| `1.2.2`       | `1.2.0`        |
| `1.2.1`       | `1.2.0`        |
| `1.2.0`       | `1.2.0`        |
| `1.1.0`       | `1.1.0`        |
| `1.0.1`       | `1.0.0`        |
| `1.0.0`       | `1.0.0`        |
| `0.21.9`      | `9.10.0`       |
| `0.21.8`      | `9.10.0`       |
| `0.21.7`      | `9.10.0`       |
| `0.21.6`      | `9.8.0`        |
| `0.21.5`      | `9.8.0`        |
| `0.21.4`      | `9.7.0`        |
| `0.21.3`      | `9.6.1`        |
| `0.21.2`      | `9.6.1`        |
| `0.21.1`      | `9.6.1`        |
| `0.21.0`      | `9.6.1`        |
| `0.20.1`      | `9.6.0`        |
| `0.20.0`      | `9.6.0`        |
| `0.19.0`      | `9.5.0`        |
| `0.18.3`      | `9.4.0`        |
| `0.18.2`      | `9.4.0`        |
| `0.18.1`      | `9.3.0`        |
| `0.18.0`      | `9.3.0`        |
| `0.17.2`      | `9.2.0`        |
| `0.17.1`      | `9.1.0`        |
| `0.17.0`      | `9.0.0`        |

### AgentManifest

Agent deployment definition: identity, version, secrets, platform deploy settings, and agent config.

| Field          | Type                 | Required | Default | Description                                                                                                                                                                                                                                                                    |
| -------------- | -------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`         | `string`             | yes      | -       | Agent name, surfaced in the platform UI and logs. The deployment operator takes it from the request URL path (`/agents/{agentName}`), not from the request body.                                                                                                               |
| `id`           | `string`             | yes      | -       | Stable URL-safe slug, unique within the project. Letters, digits, hyphens, and underscores only — no spaces, dots, slashes, or other URL-reserved characters. Immutable across deploys — rename by deploying a new manifest under a new id.                                    |
| `version`      | `string`             | yes      | -       | Version label, surfaced in logs and traces. The deployment operator deploys it as the agent image tag, e.g. `0.21.4`.                                                                                                                                                          |
| `description`  | `string`             | no       | -       | Human-readable description of the agent, shown in the platform. Not read by the agent runtime.                                                                                                                                                                                 |
| `appearance`   | `AgentAppearance`    | no       | -       | Avatar icon and colour keys from the platform palette.                                                                                                                                                                                                                         |
| `endpoint`     | `boolean`            | no       | `False` | Platform-side deploy flag. When `true`, the platform provisions a public-facing URL; when `false` (default), the agent is reachable only via the platform's internal API. Not read by the agent runtime.                                                                       |
| `secrets`      | `list[SecretRef]`    | no       | -       | Platform secrets this manifest draws from. Every `${VAR}` referenced elsewhere in the manifest must be a key in one of these secrets. Sent to the deployment operator as `secretRefs`, each entry as `{secretName}`.                                                           |
| `schedule`     | `DeploymentSchedule` | no       | -       | Uptime or downtime windows for the deployment. Omit to keep the agent running at all times.                                                                                                                                                                                    |
| `stack_id`     | `string`             | no       | -       | Stack the agent belongs to, grouping it with related platform resources; resource lists can filter by it. Lowercase letters, digits, hyphens and underscores, starting and ending with a letter or digit, at most 63 characters. Sent to the deployment operator as `stackId`. |
| `agent_config` | `AgentConfig`        | yes      | -       |                                                                                                                                                                                                                                                                                |

#### AgentAppearance

Avatar the platform shows for the agent. Not read by the agent runtime.

| Field   | Type     | Required | Default | Description                                                                                                                 |
| ------- | -------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `icon`  | `string` | yes      | -       | Icon key from the platform palette, e.g. `rounded`. Lowercase letters, digits and single hyphens, at most 32 characters.    |
| `color` | `string` | yes      | -       | Colour key from the platform palette, e.g. `twilight`. Lowercase letters, digits and single hyphens, at most 32 characters. |

#### SecretRef

Reference to a platform secret. Resolved platform-side at deploy time — the secret's key/value pairs are injected as env vars on the agent process before boot. Not read by the agent runtime.

| Field         | Type     | Required | Default | Description                                   |
| ------------- | -------- | -------- | ------- | --------------------------------------------- |
| `secret_name` | `string` | yes      | -       | Secret name as listed in Interactive Secrets. |

#### DeploymentSchedule

When the platform keeps the agent running; outside it the agent is scaled down. The deployment operator requires exactly one of `uptime` or `downtime` and validates both formats. Unrelated to `agent_config.schedules`, which triggers autonomous routines.

| Field      | Type     | Required | Default | Description                                                                                                                                                                                                                                                                       |
| ---------- | -------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uptime`   | `string` | no       | -       | When the agent runs: comma-separated `WEEKDAY-WEEKDAY HH:MM-HH:MM` entries, e.g. `Mon-Fri 07:30-20:30`. Weekdays are Mon to Sun (case-insensitive); start times run 00:00–23:59 and end times 00:00–24:00, where 24:00 is the end of the day. Mutually exclusive with `downtime`. |
| `downtime` | `string` | no       | -       | When the agent is scaled down, in the same format as `uptime`, e.g. `Sat-Sun 00:00-24:00`. Mutually exclusive with `uptime`.                                                                                                                                                      |
| `timezone` | `string` | yes      | -       | IANA timezone the windows are read in, e.g. `Europe/Berlin` or `UTC`.                                                                                                                                                                                                             |

#### Validation Rules

* Priority: exactly one of `over` or `over_all_routines`
* `context.language` is `match_user` on its own, or comma-separated languages, each a language name, an ISO 639-1 code (`fr`, `pt-BR`) or a name with its country in parentheses (`Portuguese (Brazil)`); anything else, such as free text, is rejected. Checked when the agent starts, not by the JSON Schema, which accepts any non-empty string (since 9.6.0)
* String fields with `minLength >= 1` reject whitespace-only values

### AgentConfig

Agent-specific config: LLMs, behavioural context, tools, integrations, runtime tuning, and traces.

| Field                  | Type                                        | Required | Default | Description                                                                                                                                                                                                                                                                                                                     |
| ---------------------- | ------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `runtime`              | `Runtime`                                   | yes      | -       |                                                                                                                                                                                                                                                                                                                                 |
| `interactive_platform` | `InteractivePlatform`                       | yes      | -       |                                                                                                                                                                                                                                                                                                                                 |
| `llms`                 | `Llms`                                      | yes      | -       |                                                                                                                                                                                                                                                                                                                                 |
| `context`              | `AgentContext`                              | yes      | -       |                                                                                                                                                                                                                                                                                                                                 |
| `traces`               | `Traces`                                    | no       | -       |                                                                                                                                                                                                                                                                                                                                 |
| `database`             | `Database`                                  | no       | -       | Postgres connection for the agent's session and state store. Without this block sessions live in memory and are lost on restart; the `schedules` block requires it.                                                                                                                                                             |
| `mcps`                 | `list[string \| McpReference \| McpConfig]` | no       | -       | MCP connections registered in the project that the agent uses for tool calls. Give each one by name, or as `{ref, id, endpoint}` to set its tool namespace or endpoint. A raw `{id, hostname, port}` connection is still accepted but deprecated. Each entry's tools are namespaced under its `id`, which defaults to the name. |
| `search`               | `ExternalSearch \| CollectionsSearch`       | no       | -       | Where the agent looks things up to ground its answers; leave the block out to run without lookups. Choose one source with the `type` tag: `external` for your own HTTP search endpoint, or `collections` for a managed collection hosted by InteractiveAI.                                                                      |
| `event_webhook`        | `EventWebhook`                              | no       | -       | Outbound conversational event delivery: optional destination override and context allowlists. Sessions marked autonomous or webhook\_match keep legacy SDK delivery without overrides or added context. Omit to preserve SDK-configured delivery and the existing event payload.                                                |
| `webhooks`             | `list[WebhookEntry]`                        | no       | -       | Incoming webhooks from other systems. Each one gets its own `POST /webhooks/{name}` URL, checks the sender's signature, and starts the routines listed on it.                                                                                                                                                                   |
| `schedules`            | `list[ScheduleEntry]`                       | no       | -       | Recurring autonomous triggers; requires the database block.                                                                                                                                                                                                                                                                     |
| `replay`               | `Replay`                                    | no       | -       | DEPRECATED and no longer read. Retained so configs that still carry it validate; omit it. Replay endpoints are always registered and a replay request names its own dataset.                                                                                                                                                    |

#### Runtime

Runtime/process configuration: credentials and engine tuning knobs.

| Field                                | Type                              | Required | Default | Description                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------ | --------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api_key`                            | `string`                          | yes      | -       | Token callers must send to reach this agent, and that the agent sends back on its own autonomous callbacks. Must be a `${VAR}` env-ref — literal values are rejected.                                                                                                                                                             |
| `log_level`                          | `string`                          | no       | `INFO`  | Log level for the agent process. One of `TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` (case-insensitive). Keep at `INFO` in production.                                                                                                                                                                                |
| `max_engine_iterations`              | `integer`                         | no       | `5`     | How many think-and-act steps the agent may chain in one turn. Raise it for work that needs longer chains of tool calls.                                                                                                                                                                                                           |
| `policy_batch_size`                  | `integer`                         | no       | `5`     | How many policies the agent checks per model call. Smaller batches cost less per call but need more calls.                                                                                                                                                                                                                        |
| `streaming`                          | `boolean`                         | no       | `False` | Send the reply, preambles and tool announcements word by word instead of as whole messages. Only the delivery changes: the prompts, the text, the models and `llms.fallback` are the same either way.                                                                                                                             |
| `startup_review`                     | `boolean`                         | no       | `True`  | Run advisory LLM reviews of loaded policies and routines after readiness, using `llms.evaluation.judge`. Enabled by default; each process start incurs model costs. Set false to disable these reviews. Deterministic startup checks always run.                                                                                  |
| `generation_attempts`                | `integer`                         | no       | `3`     | How many times the agent tries a model call before giving up on that model. A call that fails or exceeds its time limit uses one attempt. The reply moves to `llms.fallback` and internal stages to `llms.evaluation.fallback` only once these attempts run out, so a higher number delays that switch.                           |
| `autonomous_default_timeout_seconds` | `integer`                         | no       | `120`   | Timeout for autonomous runs whose routine sets no `timeout_seconds` of its own. A routine's own value always wins. Must not exceed `autonomous_max_timeout_seconds`.                                                                                                                                                              |
| `autonomous_max_timeout_seconds`     | `integer`                         | no       | `600`   | Ceiling on every autonomous run's timeout. A routine's own `timeout_seconds` applies while it fits under this; anything longer is cut down to it. Shorter timeouts are never raised.                                                                                                                                              |
| `autonomous_callback_max_retries`    | `integer`                         | no       | `5`     | How many times to retry an autonomous callback or event webhook, with backoff, before giving up.                                                                                                                                                                                                                                  |
| `run_retention_days`                 | `integer`                         | no       | `30`    | How many days finished autonomous runs and their steps are kept for the agent UI before they are deleted. Runs hold their input, output and tool results, which can be personal data.                                                                                                                                             |
| `turn_recording`                     | `boolean`                         | no       | `True`  | Record each conversation turn's decisions, steps, knowledge-base searches and timings for the agent UI's conversation view. Recording never delays a turn: rows are stored in the background and dropped if storage is slow. Kept for `run_retention_days`. Set `false` to store nothing per turn on an agent with heavy traffic. |
| `on_tool_error`                      | `ConversationalToolErrorHandling` | no       | -       |                                                                                                                                                                                                                                                                                                                                   |
| `prompt_cache`                       | `PromptCache`                     | no       | -       |                                                                                                                                                                                                                                                                                                                                   |

**ConversationalToolErrorHandling**

What a conversational turn does when a tool request fails: its

| Field     | Type                   | Required | Default    | Description                                                                                                                                                                                                    |
| --------- | ---------------------- | -------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default` | `string`               | no       | `continue` | Action for tools not listed in `tools`. `continue`: the reply is generated knowing the tool failed. `silent`: no reply this turn. `handoff`: escalate with `handoff`. Enum: \['continue', 'silent', 'handoff'] |
| `tools`   | `dict[string, string]` | no       | -          | Per-tool overrides of `default`, keyed by tool id (`service:tool` or a bare tool name, resolved like routine `tools`).                                                                                         |
| `handoff` | `HandoffArguments`     | no       | -          | Handoff arguments; required when any action is `handoff`.                                                                                                                                                      |

**HandoffArguments**

Arguments for the `built-in:initiate_human_handoff` call that

| Field              | Type      | Required | Default | Description                                                                                                      |
| ------------------ | --------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `reason`           | `string`  | yes      | -       | Why the conversation was escalated.                                                                              |
| `internal_note`    | `string`  | no       | -       | Comment for the human team; never shown to the customer.                                                         |
| `customer_message` | `string`  | no       | -       | Reply sent verbatim to the customer this turn. Without it and without `silent`, the reply is generated as usual. |
| `silent`           | `boolean` | no       | `False` | Send nothing to the customer this turn, for channels where the human answers directly (email).                   |

**PromptCache**

How the agent asks model providers to reuse the start of a prompt it

| Field          | Type      | Required | Default | Description                                                                                                                                                                                |
| -------------- | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled`      | `boolean` | no       | `True`  | Mark the stable start of each prompt for the provider to cache and keep a conversation's calls on one provider host. Set false only to rule caching out while diagnosing a provider error. |
| `tool_results` | `string`  | no       | -       | Which turns cache the tool results gathered during the turn. Enum: \['off', 'autonomous', 'always']                                                                                        |

#### InteractivePlatform

InteractiveAI platform host and credentials. The agent uses these to fetch content (routines, policies, …) and to reach the LLM router.

| Field        | Type     | Required | Default                      | Description                                                                                                                                        |
| ------------ | -------- | -------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `base_url`   | `string` | no       | `https://app.interactive.ai` | Base URL of the InteractiveAI platform, defaulting to the public production host. The LLM router and default traces endpoints are derived from it. |
| `public_key` | `string` | yes      | -                            | `${VAR}` env-ref for the InteractiveAI public key.                                                                                                 |
| `secret_key` | `string` | yes      | -                            | `${VAR}` env-ref for the InteractiveAI secret key.                                                                                                 |

#### Llms

LLM selection for the agent. Two independent lanes:

| Field          | Type                    | Required | Default | Description                                                                                                                                                                                                                                                                      |
| -------------- | ----------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default`      | `any \| ModelSpec`      | no       | -       | Main customer-facing model. Used for the reply, the thinking phrase and the search queries unless those are set separately.                                                                                                                                                      |
| `fallback`     | `list[any]`             | no       | -       | Backup customer-facing models, in order. When the reply's attempts on its model fail or time out, the reply is retried on each backup in turn, with the same number of attempts. The preamble sends them to the router as alternates instead. Set `[]` to run on a single model. |
| `api_key`      | `string`                | yes      | -       | `${VAR}` env-ref for the InteractiveAI LLM router API key.                                                                                                                                                                                                                       |
| `response`     | `any \| ModelSpec`      | no       | -       | Model that writes the message the customer reads, canned responses included. Omit to use `default`.                                                                                                                                                                              |
| `preamble`     | `any \| ModelSpec`      | no       | -       | Model for the thinking phrase and the tool announcement. Omit to use `default`.                                                                                                                                                                                                  |
| `search_query` | `any \| ModelSpec`      | no       | -       | Model that turns the conversation into search queries, one call per query field. If it fails the agent searches with the customer's own message. Omit to use `default`.                                                                                                          |
| `evaluation`   | `any \| EvaluationLlms` | no       | -       | Models for the agent's internal decisions — which tool to call, which policies match, where to go next in a routine. One model name sets them all; leave it out for the built-in defaults.                                                                                       |

#### AgentContext

Behavioural context shared by every run of the agent: system prompt, language, routines, policies, glossaries, macros, preamble, greeting, and priority relationships.

| Field                | Type                                                                       | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| -------------------- | -------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `system_prompt`      | `PromptRef`                                                                | yes      | -       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `language`           | `"match_user" \| "English" \| "French" \| "Spanish" \| "German" \| string` | yes      | -       | Which language the agent replies in: `match_user` on its own, or one or more languages separated by commas. Each language is one of: a language name, case-insensitive for names in the ISO 639-1 list (`French`), otherwise one to three capitalized words of letters only (`Brazilian Portuguese`); an ISO 639-1 code, read as its name and keeping a country subtag (`pt-BR` becomes `Portuguese (Brazil)`); or an ISO 639-1 language name followed by the country's full English name in parentheses (`English (United Kingdom)`, not `English (UK)`). Anything else, such as instructions in prose, is rejected when the agent starts. This JSON Schema accepts any non-empty string here, so a value can pass editor validation and still stop the agent from starting. Put reply-language nuances in the system prompt or a policy. |
| `routines`           | `list[RoutineRef]`                                                         | no       | -       | Routines the agent can run, as versioned references to the project's routine catalog.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `reevaluation_tools` | `list[ReevaluationTool]`                                                   | no       | -       | Tools that make the agent reconsider which routine and policies apply as soon as they run, instead of waiting for the customer's next message. Use it for tools that change state mid-turn, like an authentication call. It applies whether the tool succeeds or fails.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `policies`           | `list[PolicyRef]`                                                          | no       | -       | Policies the agent follows — safety, compliance, tone — as versioned references to the project's policy catalog. They sit on top of every routine and are matched turn by turn, or applied always when the policy sets `always_match`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `glossaries`         | `list[GlossaryRef]`                                                        | no       | -       | Glossaries injected into the agent's context, as versioned references to the project's glossary catalog.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `macros`             | `list[MacroRef]`                                                           | no       | -       | Reusable text snippets routines can pull in with `${macro_id}`, as versioned references to the project's macro catalog.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `preamble`           | `Preamble`                                                                 | no       | -       | Short phrases the agent may say before it replies, written here rather than referenced. Without this block it says nothing before replying.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `greeting`           | `string`                                                                   | no       | -       | Opening message for the first turn. The agent stays close to this wording, in the language it replies in, and skips its thinking phrase on that turn only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `relationships`      | `Relationships`                                                            | no       | -       | Cross-entity rules: priorities, entailments, and prerequisite guards. Omit when all routines and policies remain equal-priority and unguarded.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `current_datetime`   | `CurrentDatetime`                                                          | no       | -       | Gives the agent the current date and time as the `current_datetime` variable, refreshed every turn. Without this block the agent has no clock.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `variables`          | `list[DeclaredVariable]`                                                   | no       | -       | Context variables declared by the manifest. Routine `tool_arguments` may only bind declared variables. Names are unique and exclude `current_datetime`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

**PromptRef**

Versioned reference to a prompt.

| Field     | Type      | Required | Default | Description                  |
| --------- | --------- | -------- | ------- | ---------------------------- |
| `id`      | `string`  | yes      | -       | Prompt id.                   |
| `version` | `integer` | yes      | -       | Exact prompt version to use. |

**RoutineRef**

Versioned reference to a routine.

| Field     | Type      | Required | Default | Description                   |
| --------- | --------- | -------- | ------- | ----------------------------- |
| `id`      | `string`  | yes      | -       | Routine id.                   |
| `version` | `integer` | yes      | -       | Exact routine version to use. |

**ReevaluationTool**

Tool that makes the agent reconsider which routine and policies apply as soon as it runs, mid-turn, whether it succeeds or fails.

| Field | Type     | Required | Default | Description                                                                                   |
| ----- | -------- | -------- | ------- | --------------------------------------------------------------------------------------------- |
| `id`  | `string` | yes      | -       | Tool id whose execution triggers reevaluation. Must match a tool exposed by an `mcps` server. |

**PolicyRef**

Versioned reference to a policy.

| Field     | Type      | Required | Default | Description                  |
| --------- | --------- | -------- | ------- | ---------------------------- |
| `id`      | `string`  | yes      | -       | Policy id.                   |
| `version` | `integer` | yes      | -       | Exact policy version to use. |

**GlossaryRef**

Versioned reference to a glossary.

| Field     | Type      | Required | Default | Description                    |
| --------- | --------- | -------- | ------- | ------------------------------ |
| `id`      | `string`  | yes      | -       | Glossary id.                   |
| `version` | `integer` | yes      | -       | Exact glossary version to use. |

**MacroRef**

Versioned reference to a macro.

| Field     | Type      | Required | Default | Description                 |
| --------- | --------- | -------- | ------- | --------------------------- |
| `id`      | `string`  | yes      | -       | Macro id.                   |
| `version` | `integer` | yes      | -       | Exact macro version to use. |

**Preamble**

Optional preamble configuration. When set, the agent may emit a short utterance before replying — e.g. "Let me check that for you." Not always emitted; the model chooses based on context.

| Field            | Type           | Required | Default | Description                                                                                                                                                                      |
| ---------------- | -------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `examples`       | `list[string]` | yes      | -       | Example phrases in the agent's voice, e.g. `"Let me check that for you."` The agent does not reuse them word for word — it matches their tone and length.                        |
| `announce_tools` | `boolean`      | no       | `False` | Also say something short once a lookup finishes, while the rest of the reply is still being written. Makes tool-heavy turns feel faster. Example: `"I've checked your account."` |

**Relationships**

Cross-entity rules declared per agent: priorities, entailments, and

| Field         | Type                  | Required | Default | Description                                                                                                                                                              |
| ------------- | --------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `priorities`  | `list[Priority]`      | no       | -       | List of priority entries. Each promotes one routine or policy above one or more others; pairs not covered remain equal-priority.                                         |
| `entailments` | `list[Entailment]`    | no       | -       | When one policy matches, activate others with it. Policies only — routines cannot be pulled in this way.                                                                 |
| `requires`    | `list[RequiresEntry]` | no       | -       | Prerequisite guards. While a guard is unsatisfied the covered routines and policies are not evaluated at all. Declared once per agent; not on routine or policy content. |

**Priority**

Cross-routine/policy priority entry. `higher` wins against the targets in `over` or, when `over_all_routines: true`, against every routine. Exactly one of the two scope fields is required.

| Field               | Type           | Required | Default | Description                                                                                                                            |
| ------------------- | -------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `higher`            | `string`       | yes      | -       | Reference that takes priority, in `routine:<id>` or `policy:<id>` form.                                                                |
| `over`              | `list[string]` | no       | -       | References that `higher` outranks, each in `routine:<id>` or `policy:<id>` form. Mutually exclusive with `over_all_routines`.          |
| `over_all_routines` | `boolean`      | no       | -       | Puts `higher` above every routine in the manifest. Policies are unaffected, even when `higher` is one. Cannot be combined with `over`. |

**Entailment**

Entailment link: when the `when` policy matches, every policy in `also_apply` is activated with it. Policies only — routines cannot be pulled in this way.

| Field        | Type           | Required | Default | Description                                                                        |
| ------------ | -------------- | -------- | ------- | ---------------------------------------------------------------------------------- |
| `when`       | `string`       | yes      | -       | Source policy (`policy:<id>`) whose match pulls in the targets.                    |
| `also_apply` | `list[string]` | yes      | -       | Policies activated whenever the source policy matches, each in `policy:<id>` form. |

**RequiresEntry**

Prerequisite guard declared on the agent. While unsatisfied, the

| Field          | Type             | Required | Default | Description                                                                                                                                                                                                                                                                                  |
| -------------- | ---------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tool`         | `string`         | yes      | -       | Tool id that must have run successfully before the covered entities are evaluated. Bare (`authenticate_customer`) or qualified (`integration:authenticate_customer`), resolved the same way as `reevaluate_after`.                                                                           |
| `result_has`   | `string \| dict` | no       | -       | What the tool's result must contain. A string names a key that must be present and non-empty; a mapping names keys that must each equal the given value. Omit to require only that the tool ran without a protocol error; a failure reported inside the payload still counts as a clean run. |
| `all_routines` | `boolean`        | no       | -       | When `true`, every routine pinned on this agent is guarded (not policies). Mutually exclusive with `on`. Pair with `excludes` to carve out specific routines.                                                                                                                                |
| `on`           | `list[string]`   | no       | -       | Entities this guard covers, each in `routine:<id>` or `policy:<id>` form. Mutually exclusive with `all_routines`.                                                                                                                                                                            |
| `excludes`     | `list[string]`   | no       | -       | Routines to leave unguarded when `all_routines` is set, each in `routine:<id>` form. Invalid with `on`.                                                                                                                                                                                      |

**CurrentDatetime**

Injects the current date and time into the model's context on every turn.

| Field      | Type     | Required | Default | Description                                                                              |
| ---------- | -------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
| `timezone` | `string` | no       | `UTC`   | IANA timezone name (e.g. `Europe/Lisbon`) the timestamp is rendered in. Defaults to UTC. |

**DeclaredVariable**

A context variable declared by the manifest so routines can bind it.

| Field         | Type     | Required | Default | Description                                                                                               |
| ------------- | -------- | -------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `name`        | `string` | yes      | -       | Variable name, referenced by `tool_arguments` bindings.                                                   |
| `description` | `string` | no       | -       | What the variable holds; shown wherever variables are listed.                                             |
| `value`       | `any`    | no       | -       | Global value owned by the manifest; any JSON value, including `null`. Omit when the SDK sets every value. |

#### Traces

OpenTelemetry traces configuration: deployment tag, trace-id derivation, optional backend override.

| Field                    | Type            | Required | Default      | Description                                                                                                                                          |
| ------------------------ | --------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deployment_environment` | `string`        | no       | `production` | Environment label attached to every trace as `deployment.environment`, e.g. `production`, `staging`, `dev`.                                          |
| `trace_id_field`         | `string`        | no       | -            | Key from an autonomous run's input to name its trace after. Set `customer_id` and traces read `{agent}-cus_abc` instead of a random `autorun_<hex>`. |
| `backend`                | `TracesBackend` | no       | -            | Send traces to your own OTLP endpoint instead. Omit to send them to InteractiveAI using the platform credentials.                                    |

**TracesBackend**

Custom OTLP traces backend. Omit the whole block to send traces to InteractiveAI's default endpoint. When set, `url` is required; `api_key` is optional (omit for endpoints that don't require auth, e.g. an internal/sidecar OTLP collector).

| Field            | Type     | Required | Default  | Description                                                                                                                                                                                              |
| ---------------- | -------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`            | `string` | no       | -        | Full OTLP HTTP traces endpoint (e.g. `https://otel.your-provider.com/v1/traces`). Scheme required.                                                                                                       |
| `api_key`        | `string` | no       | -        | `${VAR}` env-ref for the traces backend API key. Sent per `api_key_scheme`. Omit for endpoints that don't require auth.                                                                                  |
| `api_key_scheme` | `string` | no       | `bearer` | HTTP auth scheme for `api_key`. `bearer` sends `Authorization: Bearer <value>`; `basic` sends `Authorization: Basic <base64(value)>` (use for `public_key:secret_key` pairs). Enum: \['bearer', 'basic'] |

#### Database

Postgres connection block for the agent's session/state store. Omit to use in-memory ephemeral storage. A minimal block only needs `hostname` and `password`.

| Field      | Type      | Required | Default    | Description                                                                                                                                                         |
| ---------- | --------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hostname` | `string`  | yes      | -          | Postgres server host. Bare host only — no scheme, path, or port.                                                                                                    |
| `port`     | `integer` | no       | `5432`     | TCP port the Postgres server listens on. Defaults to `5432`.                                                                                                        |
| `user`     | `string`  | no       | `postgres` | Postgres role the agent connects as.                                                                                                                                |
| `password` | `string`  | yes      | -          | `${VAR}` env-ref for the Postgres password.                                                                                                                         |
| `dbname`   | `string`  | no       | `postgres` | Postgres database name. Defaults to `postgres`.                                                                                                                     |
| `sslmode`  | `string`  | no       | `require`  | Postgres `sslmode` parameter. Defaults to `require` (encrypted, no cert verification). Enum: \['disable', 'allow', 'prefer', 'require', 'verify-ca', 'verify-full'] |

#### McpReference

An MCP connection registered in the project, attached to the agent by name.

| Field      | Type     | Required | Default   | Description                                                                                                                                                                       |
| ---------- | -------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ref`      | `string` | yes      | -         | Name of the MCP connection registered in the project.                                                                                                                             |
| `id`       | `string` | no       | -         | Namespace prefix applied to this MCP's tools at runtime (e.g. `crm` → tools called as `crm:search`). Defaults to `ref`.                                                           |
| `endpoint` | `string` | no       | `private` | Which endpoint of the MCP the agent connects to: `private` (default) or `public`. `public` needs a self-hosted MCP with its public endpoint enabled. Enum: \['private', 'public'] |

#### McpConfig

A raw MCP connection. Deprecated: register the MCP in the project and reference it by name instead. Its tools become available to the agent under the `id` namespace.

| Field       | Type      | Required | Default           | Description                                                                                                                              |
| ----------- | --------- | -------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `id`        | `string`  | yes      | -                 | Namespace prefix applied to this server's tools at runtime (e.g. `crm` → tools called as `crm:search`).                                  |
| `hostname`  | `string`  | yes      | -                 | MCP server host, including the URL scheme (`http://` or `https://`). Host only — no path, query, fragment, or port.                      |
| `port`      | `integer` | yes      | -                 | TCP port the MCP server listens on (1–65535).                                                                                            |
| `transport` | `string`  | no       | `streamable-http` | MCP transport protocol. Only `streamable-http` is supported.                                                                             |
| `path`      | `string`  | no       | `/mcp`            | URL path of the MCP endpoint, starting with `/`. Defaults to `/mcp`. Set when the server mounts its endpoint elsewhere (e.g. `/v2/mcp`). |
| `api_key`   | `string`  | no       | -                 | `${VAR}` env-ref for the MCP server's API key. Sent as `Authorization: Bearer`. Omit when the server doesn't require auth.               |

#### EventWebhook

Outbound conversation events, distinct from inbound autonomous webhooks.

| Field     | Type                  | Required | Default | Description                                                                                                                                                                                                                  |
| --------- | --------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`     | `string`              | no       | -       | Full HTTP(S) integration endpoint. Overrides the SDK's session webhook URL for conversational sessions only; omit to retain the SDK destination. Uses the runtime API key as bearer authentication. No userinfo or fragment. |
| `include` | `EventWebhookInclude` | no       | -       |                                                                                                                                                                                                                              |

**EventWebhookInclude**

Explicit allowlists for context attached to conversation events.

| Field                | Type           | Required | Default | Description                                                                                                                                                                                                                                                                                           |
| -------------------- | -------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customer_id`        | `boolean`      | no       | `False` | Include the session's customer ID.                                                                                                                                                                                                                                                                    |
| `session_metadata`   | `list[string]` | no       | -       | Exact session metadata keys to include; missing keys are omitted.                                                                                                                                                                                                                                     |
| `customer_variables` | `list[string]` | no       | -       | Exact customer variable names to include, read at delivery time. Only values stored for this customer are sent, with no global or tag fallback. Stored value types are preserved; missing values are omitted. Variable names are resolved once per flush; duplicate names use the lowest variable ID. |

#### WebhookEntry

Third-party webhook entry point that fans out to one or more autonomous routines. The agent verifies the provider's HMAC signature against the env-var secret. With multiple routines, the engine picks which one(s) fire per call.

| Field        | Type           | Required | Default  | Description                                                                                                                                      |
| ------------ | -------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`       | `string`       | yes      | -        | URL slug exposed under `POST /webhooks/{name}`.                                                                                                  |
| `secret_env` | `string`       | yes      | -        | `${VAR}` env-ref for the HMAC shared secret. Re-read per request, so rotation picks up without restart.                                          |
| `header`     | `string`       | yes      | -        | HTTP header carrying the provider's signature (e.g. `X-Hub-Signature-256`).                                                                      |
| `algorithm`  | `string`       | no       | `sha256` | HMAC digest algorithm the provider signs with. Enum: \['sha256', 'sha1', 'sha512']                                                               |
| `prefix`     | `string`       | no       | -        | Literal prefix the provider prepends to the hex digest (e.g. `"sha256="` for GitHub).                                                            |
| `routines`   | `list[string]` | yes      | -        | Routines this webhook can start. Each id must be listed in `context.routines` and the routine must be autonomous; the agent checks both at boot. |

#### ScheduleEntry

A recurring autonomous-routine trigger.

| Field          | Type      | Required | Default | Description                                                    |
| -------------- | --------- | -------- | ------- | -------------------------------------------------------------- |
| `name`         | `string`  | yes      | -       | Unique schedule id used in job keys, logs, and traces.         |
| `routine`      | `string`  | yes      | -       | Autonomous routine id, cross-referenced at boot.               |
| `cron`         | `string`  | yes      | -       | 5-field UTC cron expression, parse-validated at boot.          |
| `input`        | `dict`    | no       | -       | Static routine input, schema-validated at boot.                |
| `callback_url` | `string`  | no       | -       | Optional signed callback URL, allowlist-checked at boot.       |
| `max_attempts` | `integer` | no       | `1`     | Attempts per tick; values above 1 opt into failed-run retries. |

#### Replay

DEPRECATED. Retained so existing configs validate; nothing reads it.

| Field     | Type      | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                         |
| --------- | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | `boolean` | no       | `False` | DEPRECATED and no longer read. Replay endpoints are always registered: they are bearer-authed, and fixtures are served only to sessions carrying a replay scenario, so a real conversation is unaffected. Gating this from the manifest put a deployment concern in content config, where unrelated deploys silently dropped it. The field is retained only so existing configs still validate; it will be removed. |
| `dataset` | `string`  | no       | -       | DEPRECATED and no longer read. A replay request names its own dataset, which is required rather than defaulted so a run cannot silently read from the wrong one.                                                                                                                                                                                                                                                    |

#### Validation Rules

* Priority: exactly one of `over` or `over_all_routines`
* `context.language` is `match_user` on its own, or comma-separated languages, each a language name, an ISO 639-1 code (`fr`, `pt-BR`) or a name with its country in parentheses (`Portuguese (Brazil)`); anything else, such as free text, is rejected. Checked when the agent starts, not by the JSON Schema, which accepts any non-empty string (since 9.6.0)
* String fields with `minLength >= 1` reject whitespace-only values

***

## Context

### RoutineSchema

A multi-node conversational or autonomous workflow.

| Field         | Type                                               | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------- | -------------------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | `string`                                           | no       | -       | Optional stable identifier; the storage name is the primary key. Must be non-empty when provided.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `title`       | `string`                                           | yes      | -       | Human-readable routine title. Surfaced in the platform UI, traces, and eval logs.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `conditions`  | `string \| PromptRef \| list[string \| PromptRef]` | yes      | -       | When the routine activates: one natural-language condition or a list of alternatives, matched against the conversation (conversational routines only — an autonomous routine activates on its trigger event and ignores these conditions, but a placeholder is still required). A bare string is normalized to a one-element list; at least one non-empty entry is required. Each is text, or `{id, version}` of a prompt in the prompt library.                                                                                          |
| `description` | `string`                                           | no       | -       | Free-form description of what the routine does. Not used for matching.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `autonomous`  | `AutonomousConfig`                                 | no       | -       | Declaring this block promotes the routine to an autonomous workflow triggerable via `POST /routines/{id}/trigger` (typed input/output, result delivered via signed webhook callback).                                                                                                                                                                                                                                                                                                                                                     |
| `entry`       | `string`                                           | yes      | -       | Id of the node where execution starts. Must match a declared node id.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `functions`   | `dict[string, string]`                             | no       | -       | Functions this routine names, for its formulas: the key is the name and its inputs, `name(input, …)`, the value the formula, which reads only its inputs and calls the formula functions and the functions above it. Any formula of the routine (a compute value, a rule check, a bound value) can call them. A call is checked and run as the function's formula with its inputs written in, so a node of a validated model holds its formulas expanded. A name can't be a formula function or `input`, `variable`, `step` or `message`. |
| `nodes`       | `list[RoutineNode]`                                | yes      | -       | The routine's graph nodes, each declared exactly once; edges live on each node's `transitions` and `otherwise`. Node ids must be unique. Cycles and fan-in are allowed.                                                                                                                                                                                                                                                                                                                                                                   |
| `policies`    | `list[ScopedPolicySchema]`                         | no       | -       | Journey-scoped policies declared inline: condition/action rules active only while this routine is active. Each requires an explicit `id`. Not referenceable from the manifest's `relationships:` block — use top-level policies for priority, entailment, and `requires` participation.                                                                                                                                                                                                                                                   |

#### AutonomousConfig

Configuration for autonomous routines that can be triggered via an API endpoint.

| Field                    | Type                          | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------ | ----------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `input_schema`           | `dict`                        | yes      | -       | Draft 2020-12 JSON Schema describing the trigger-endpoint input payload. Passed through unchanged — `additionalProperties` is not inspected or stripped.                                                                                                                                                                                                                                                                                                                       |
| `output_schema`          | `dict`                        | yes      | -       | Draft 2020-12 JSON Schema describing the routine's final output, validated when the routine emits its result. The server adds `additionalProperties: false` to every object node before use — you do not need to set it manually.                                                                                                                                                                                                                                              |
| `timeout_seconds`        | `integer`                     | no       | `120`   | Maximum runtime for an autonomous run, in seconds. Must be a positive integer. This declared value always wins UNLESS it exceeds the agent manifest's `runtime.autonomous_max_timeout_seconds` cap (default 600), in which case it is clamped to the cap (a WARNING is logged at config apply). If omitted, the manifest's `runtime.autonomous_default_timeout_seconds` (default 120) applies instead.                                                                         |
| `callback_url_allowlist` | `list[string]`                | no       | -       | Optional allowlist of hostnames the runtime may post the result callback to. Each entry is a hostname (`api.example.com`) or a dot-prefixed suffix (`.example.com`) matching the apex domain and any subdomain. A full URL is also accepted — only its hostname is compared; the scheme, port, and path are ignored. Wildcards are not supported: omit the field to allow any host. The trigger's `callback_url` is rejected with HTTP 400 when its hostname matches no entry. |
| `on_tool_error`          | `AutonomousToolErrorHandling` | no       | -       | What a run does when a tool request fails — its definition cannot be read, its arguments cannot be prepared, a value bound to it is missing, or its execution fails. Unset, the run continues.                                                                                                                                                                                                                                                                                 |

**AutonomousToolErrorHandling**

What an autonomous run does when a tool request fails.

| Field     | Type                   | Required | Default    | Description                                                                                                                                                                       |
| --------- | ---------------------- | -------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default` | `string`               | no       | `continue` | Action for tools not listed in `tools`. `continue`: the run carries on knowing the tool failed. `emit_output`: the run settles with `output`. Enum: \['continue', 'emit\_output'] |
| `tools`   | `dict[string, string]` | no       | -          | Per-tool overrides of `default`, keyed by tool id (`service:tool` or a bare tool name, resolved like routine `tools`).                                                            |
| `output`  | `dict`                 | no       | -          | The run's output when `emit_output` fires; validated against the routine's `output_schema`. Required when any action is `emit_output`.                                            |

#### RoutineNode

A single node in a routine's graph.

| Field              | Type                                                                                                                                                                                                                                                                                  | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | `string`                                                                                                                                                                                                                                                                              | yes      | -       | Node identifier, unique within the routine. Referenced by the root `entry` field, by `transitions[].to` and by `otherwise`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `title`            | `string`                                                                                                                                                                                                                                                                              | no       | -       | Short name of the step, shown as its heading in the agent UI. Not used by the engine. Without it, the UI shows the node id.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `description`      | `string`                                                                                                                                                                                                                                                                              | no       | -       | Free-form note on the node's purpose, shown in the agent UI when the step is expanded. Not used by the engine.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `tools`            | `string \| list[string]`                                                                                                                                                                                                                                                              | no       | -       | Tool id(s) this node calls, namespaced by MCP server id (e.g. `crm:search`); a bare string is normalized to a one-element list. The node completes when the tools execute — customer-facing output belongs in a follow-up `chat_state` node. Mutually exclusive with `chat_state`, `think`, `compute` and `parallel`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `tool_instruction` | `string \| PromptRef`                                                                                                                                                                                                                                                                 | no       | -       | Guidance for filling the tools' arguments in this node. The tools always run when the routine reaches the node: conditions for running them belong on the transitions that lead here. Known values belong in `input`. Requires `tools`. Text, or `{id, version}` of a prompt in the prompt library.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `tool_arguments`   | `dict[string, dict[string, LiteralArgument \| VariableBinding \| InputBinding \| StepOutputBinding \| MessageArgument \| TodayArgument \| NowArgument \| LlmArgument \| FormulaBinding]]`                                                                                             | no       | -       | Former name of a tool node's `input`; read as it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `output_schema`    | `dict`                                                                                                                                                                                                                                                                                | no       | -       | Former name of a `think:` node's `output`; read as it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `chat_state`       | `string \| PromptRef`                                                                                                                                                                                                                                                                 | no       | -       | Instruction for what the agent should communicate; the node completes when the agent sends a message fulfilling it. Supports `${macro-id}` interpolation, filled in once when the agent starts, and `${input.name}` placeholders, filled in with the values the node declares in `input` on every turn the node is active. Mutually exclusive with `tools`, `think`, `compute` and `parallel`. Text, or `{id, version}` of a prompt in the prompt library.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `think`            | `string \| PromptRef`                                                                                                                                                                                                                                                                 | no       | -       | Typed-inference instruction (REASON node): the LLM emits structured output matching `output` without ending the turn, so think/tool nodes can chain within a single turn. Mutually exclusive with every other action field; requires `output`. Text, or `{id, version}` of a prompt in the prompt library.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `compute`          | `dict[string, string]`                                                                                                                                                                                                                                                                | no       | -       | Named values worked out with formulas, with no model call: name → formula, in order, each formula reading `input` (in autonomous routines), `message` (in conversational ones), `variable`, `step` (an earlier step's result) and the values above it. Formulas are CEL written one way: the functions of the formula list, `+ - * /`, comparisons, \`\`&&                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `input`            | `dict[string, VariableValue \| InputValue \| StepOutputValue \| MessageValue \| TodayValue \| NowValue \| dict[string, LiteralArgument \| VariableBinding \| InputBinding \| StepOutputBinding \| MessageArgument \| TodayArgument \| NowArgument \| LlmArgument \| FormulaBinding]]` | no       | -       | What the step reads. On a tool node, its argument sources, keyed by an entry of `tools` and then by parameter name. `literal`, `variable`, `input` and `step_output` bind a known value, and `formula` one worked out as a `compute:` node's formulas are: the parameter is hidden from the model and the value injected unchanged, and a value that cannot be resolved blocks the call instead of being generated; with `omit_if_empty`, an optional parameter whose value is empty is left out instead. `llm` adds guidance for a generated parameter. Unlisted required parameters are generated from the tool's own description; unlisted optional parameters are left out (list one as `llm` to have it generated). Built-in tools can be bound except `built-in:reason` and `built-in:compute`, which only `think:` and `compute:` nodes call (`built-in:compute` can't be listed in `tools` either); `built-in:emit_output` binds only `output_json`, the whole routine output, from a `literal` object or a `step_output`. On a `think:` or `compute:` node, the values it reads, by name: each a `type` (a JSON Schema, read as `output` is) and the source it is read from, as an argument binds one (`input`, `variable`, `step_output`, `message`, `today`, `now`). Each read is checked on save: the source exists, runs before on every path, and its type fits when known. A `think:` step then sees only these values instead of the whole conversation, and a `compute:` step's formulas read them by name instead of `input`, `variable`, `step` and `message`. A value missing or of the wrong type blocks the step, as a bound argument blocks its call; one marked `optional: true` reads as empty instead. A name is a formula name that is not a word formulas use nor a value the step computes. Without it, a step reads what it reads today. On a chat node, the values its `chat_state` places with `${input.name}`, declared and checked the same way: each is read when the turn's policies are matched and filled in for every model call that shows the step, and one that can't be read fills in as empty text instead of blocking; text goes in as it is, any other value as compact JSON. The reply still sees the whole conversation. A placeholder the node doesn't declare is rejected on save, or at start when it comes from a macro. Not on routing-only or parallel nodes. |
| `output`           | `dict`                                                                                                                                                                                                                                                                                | no       | -       | The result the step returns, as a Draft 2020-12 JSON Schema. Required on a `think:` node: the model's structured output must match it, and it is stored in `session.metadata.step_outputs[<node-id>]` for later nodes. Optional on a node calling one tool or a `compute:` node: every field it declares is required unless marked `optional: true`, so it takes no `required` lists, and a result that doesn't match fails the step with `ok: false`; fields it doesn't declare are allowed in the result, unless `additionalProperties: false`, but can't be read. A `compute:` node's names only values it computes. Each read of the step is checked against it when saved: the path is declared, with a position into a list (`output.brands.0.id`), and the rule's operator fits the field's type. Without it, any path can be read, and a tool step takes its shape from the tool's MCP `outputSchema`, checked when the agent starts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `parallel`         | `list[string]`                                                                                                                                                                                                                                                                        | no       | -       | Ids of the steps this node runs together, in one go: each is an ordinary tool, `think:` or `compute:` step of this routine with no transitions of its own. The node finishes once every member has a result, success or failure, and its own transitions route on them; later steps read each member by its id. A member belongs to one parallel step, is not the entry, a transition target or `built-in:emit_output`, and reads no other member's result. Autonomous routines only. Mutually exclusive with every other action field.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `transitions`      | `list[Transition]`                                                                                                                                                                                                                                                                    | no       | -       | Outbound edges. Empty or omitted = terminal node. With 2+ entries every transition requires a `condition`, or the node routes by rules: `when` on every transition, and `otherwise` on the node. A node without an action must declare at least one transition (routing-only node).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `otherwise`        | `string`                                                                                                                                                                                                                                                                              | no       | -       | The node taken when none of this node's `when` rules holds. Required on a node whose transitions have `when`, and only there. May be this node itself, to run it again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `awaits_customer`  | `boolean`                                                                                                                                                                                                                                                                             | no       | -       | Whether this `chat_state` step is complete only once the customer has replied. Unset = derived from the graph: a speaking step the routine continues from (it has transitions) waits for the reply; a terminal speaking step does not. Only valid on `chat_state` nodes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

**Transition**

A single outbound edge from a routine node.

| Field       | Type                                                                                                                                        | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `to`        | `string`                                                                                                                                    | yes      | -       | Target node id. Must match the `id` of a node declared in this routine. Any node may be targeted by multiple transitions — fan-in and cycles are allowed.                                                                                                                                                                                                                                                     |
| `condition` | `string \| PromptRef`                                                                                                                       | no       | -       | Natural-language condition deciding when this edge is followed. Omitted or empty = unconditional. Required on every transition when the node declares 2+ transitions, unless the node routes by rules (`when`). Text, or `{id, version}` of a prompt in the prompt library.                                                                                                                                   |
| `when`      | `InputCheck \| VariableCheck \| StepOutputCheck \| MessageCheck \| TodayCheck \| NowCheck \| FormulaCheck \| AllRule \| AnyRule \| NotRule` | no       | -       | A rule deciding this edge with no model call: a check of one value (a `source` and one operator), a check that is a `formula` giving true or false, or `all` / `any` / `not` of rules. A node's rules are checked top to bottom once it has run, and the first that holds is taken; when none does, the node's `otherwise` step is. On tool, `think:` and `compute:` nodes, and not into a routing-only node. |

#### ScopedPolicySchema

A policy declared inline inside a routine's `policies:` block, scoped

| Field              | Type                                                                                                                                                                                      | Required | Default  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | `string`                                                                                                                                                                                  | yes      | -        | Stable identifier. For stored policies this matches the prompt's storage name (`policies_v0/<id>`); the agent server keys the guideline on it.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `name`             | `string`                                                                                                                                                                                  | no       | -        | Human-readable display label for the InteractiveAI platform UI. Cosmetic — not used for matching. Defaults to `id` when unset.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `condition`        | `string \| PromptRef`                                                                                                                                                                     | yes      | -        | When this policy applies, in natural language (the engine's guideline matching condition). Text, or `{id, version}` of a prompt in the prompt library.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `action`           | `string \| PromptRef`                                                                                                                                                                     | no       | -        | What the agent should do when the condition matches. Omit for an observation (condition only). Text, or `{id, version}` of a prompt in the prompt library.                                                                                                                                                                                                                                                                                                                                                                                                             |
| `description`      | `string`                                                                                                                                                                                  | no       | -        | Free-form rationale shown to operators; not used for matching.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `continuous`       | `boolean`                                                                                                                                                                                 | no       | `False`  | The policy stays in force on every turn instead of retiring once its action has been carried out — tone and language rules, standing prohibitions.                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `agent_intention`  | `boolean`                                                                                                                                                                                 | no       | `False`  | The condition describes the agent's own likely next move ("You are likely to explain the terms") rather than something already in the conversation; the matcher then judges it against the reply being drafted. Word the condition accordingly.                                                                                                                                                                                                                                                                                                                        |
| `awaits_customer`  | `boolean`                                                                                                                                                                                 | no       | `False`  | The action is complete only once the customer has responded ("ask for the account number"); the engine then keeps the policy in play until they do.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `criticality`      | `string`                                                                                                                                                                                  | no       | `MEDIUM` | Priority weight the engine gives this policy when rules compete. Enum: \['HIGH', 'MEDIUM', 'LOW']                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `tools`            | `list[string]`                                                                                                                                                                            | no       | -        | Tool ids this policy runs every time it is selected; the policy's `condition` is the only gate, so state there when the tools should run.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `tool_instruction` | `string \| PromptRef`                                                                                                                                                                     | no       | -        | Guidance for filling the tools' arguments, alongside `action`. Requires `tools`. Text, or `{id, version}` of a prompt in the prompt library.                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `tool_arguments`   | `dict[string, dict[string, LiteralArgument \| VariableBinding \| InputBinding \| StepOutputBinding \| MessageArgument \| TodayArgument \| NowArgument \| LlmArgument \| FormulaBinding]]` | no       | -        | Argument sources, keyed by an entry of `tools` and then by parameter name — the same sources and rules routine nodes use, except `step_output` and `formula`, including leaving unlisted optional parameters out. `input` is only available to policies scoped to an autonomous routine, and `message` only to policies scoped to a conversational one. Requires `tools`. Built-in tools can be bound except `built-in:reason`, `built-in:compute` and `built-in:emit_output`; `built-in:compute` can't be listed in `tools` either, as only `compute:` nodes call it. |
| `reevaluate_after` | `list[string]`                                                                                                                                                                            | no       | -        | Tools whose execution re-triggers matching of this policy within the same response — on the next engine preparation iteration, not on a later customer turn (an engine re-evaluation relationship, guideline→tool).                                                                                                                                                                                                                                                                                                                                                    |
| `track`            | `boolean`                                                                                                                                                                                 | no       | `True`   | Controls the engine's guideline tracking. When true (default), an already-applied guideline is re-matched on later turns with a lighter 'previously-applied' check instead of the full initial matching; set false to force full matching every turn.                                                                                                                                                                                                                                                                                                                  |
| `always_match`     | `boolean`                                                                                                                                                                                 | no       | `False`  | When true, the runtime registers a custom always-fire matcher so the policy applies on every turn without LLM matching.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `metadata`         | `dict`                                                                                                                                                                                    | no       | -        | Arbitrary key/value metadata attached to the engine guideline; merged with server-derived keys at apply time.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

#### Validation Rules

* Node IDs must be unique across nodes (`uniqueItemProperties`)
* `tool_instruction` requires `tools`
* `tool_arguments` (former name of a tool node's `input`) requires `tools`
* `think` requires `output` (or its former name, `output_schema`)
* `output_schema` only allowed on `think:` nodes
* `output` only allowed on tool, `think:` and `compute:` nodes
* `input` only allowed on tool, `think:`, `compute:` and chat nodes
* `timeout_seconds` minimum is 1
* `callback_url_allowlist` entries must be non-empty and wildcard-free (hostnames; a leading `.` matches subdomains)
* String fields with `minLength >= 1` reject whitespace-only values

### PolicySchema

A single condition/action behavioral rule — the manifest-authored form

| Field              | Type                                                                                                                                                                                      | Required | Default  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | `string`                                                                                                                                                                                  | yes      | -        | Stable identifier. For stored policies this matches the prompt's storage name (`policies_v0/<id>`); the agent server keys the guideline on it.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `name`             | `string`                                                                                                                                                                                  | no       | -        | Human-readable display label for the InteractiveAI platform UI. Cosmetic — not used for matching. Defaults to `id` when unset.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `condition`        | `string \| PromptRef`                                                                                                                                                                     | yes      | -        | When this policy applies, in natural language (the engine's guideline matching condition). Text, or `{id, version}` of a prompt in the prompt library.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `action`           | `string \| PromptRef`                                                                                                                                                                     | no       | -        | What the agent should do when the condition matches. Omit for an observation (condition only). Text, or `{id, version}` of a prompt in the prompt library.                                                                                                                                                                                                                                                                                                                                                                                                             |
| `description`      | `string`                                                                                                                                                                                  | no       | -        | Free-form rationale shown to operators; not used for matching.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `continuous`       | `boolean`                                                                                                                                                                                 | no       | `False`  | The policy stays in force on every turn instead of retiring once its action has been carried out — tone and language rules, standing prohibitions.                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `agent_intention`  | `boolean`                                                                                                                                                                                 | no       | `False`  | The condition describes the agent's own likely next move ("You are likely to explain the terms") rather than something already in the conversation; the matcher then judges it against the reply being drafted. Word the condition accordingly.                                                                                                                                                                                                                                                                                                                        |
| `awaits_customer`  | `boolean`                                                                                                                                                                                 | no       | `False`  | The action is complete only once the customer has responded ("ask for the account number"); the engine then keeps the policy in play until they do.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `criticality`      | `string`                                                                                                                                                                                  | no       | `MEDIUM` | Priority weight the engine gives this policy when rules compete. Enum: \['HIGH', 'MEDIUM', 'LOW']                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `tools`            | `list[string]`                                                                                                                                                                            | no       | -        | Tool ids this policy runs every time it is selected; the policy's `condition` is the only gate, so state there when the tools should run.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `tool_instruction` | `string \| PromptRef`                                                                                                                                                                     | no       | -        | Guidance for filling the tools' arguments, alongside `action`. Requires `tools`. Text, or `{id, version}` of a prompt in the prompt library.                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `tool_arguments`   | `dict[string, dict[string, LiteralArgument \| VariableBinding \| InputBinding \| StepOutputBinding \| MessageArgument \| TodayArgument \| NowArgument \| LlmArgument \| FormulaBinding]]` | no       | -        | Argument sources, keyed by an entry of `tools` and then by parameter name — the same sources and rules routine nodes use, except `step_output` and `formula`, including leaving unlisted optional parameters out. `input` is only available to policies scoped to an autonomous routine, and `message` only to policies scoped to a conversational one. Requires `tools`. Built-in tools can be bound except `built-in:reason`, `built-in:compute` and `built-in:emit_output`; `built-in:compute` can't be listed in `tools` either, as only `compute:` nodes call it. |
| `reevaluate_after` | `list[string]`                                                                                                                                                                            | no       | -        | Tools whose execution re-triggers matching of this policy within the same response — on the next engine preparation iteration, not on a later customer turn (an engine re-evaluation relationship, guideline→tool).                                                                                                                                                                                                                                                                                                                                                    |
| `track`            | `boolean`                                                                                                                                                                                 | no       | `True`   | Controls the engine's guideline tracking. When true (default), an already-applied guideline is re-matched on later turns with a lighter 'previously-applied' check instead of the full initial matching; set false to force full matching every turn.                                                                                                                                                                                                                                                                                                                  |
| `always_match`     | `boolean`                                                                                                                                                                                 | no       | `False`  | When true, the runtime registers a custom always-fire matcher so the policy applies on every turn without LLM matching.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `metadata`         | `dict`                                                                                                                                                                                    | no       | -        | Arbitrary key/value metadata attached to the engine guideline; merged with server-derived keys at apply time.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

#### Validation Rules

* `tool_instruction` requires `tools`
* `tool_arguments` requires `tools`
* String fields with `minLength >= 1` reject whitespace-only values

### GlossarySchema

A collection of domain-specific terms and definitions the agent uses to understand context.

| Field   | Type                          | Required | Default | Description                                                                                      |
| ------- | ----------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------ |
| `id`    | `string`                      | no       | -       | Optional stable identifier for this glossary set. When provided, must be a non-empty string.     |
| `terms` | `dict[string, GlossaryEntry]` | yes      | -       | Glossary terms keyed by term identifier. At least one entry is required; keys must be non-empty. |

#### GlossaryEntry

A single glossary term.

| Field         | Type           | Required | Default | Description                                   |
| ------------- | -------------- | -------- | ------- | --------------------------------------------- |
| `name`        | `string`       | yes      | -       | The term being defined.                       |
| `description` | `string`       | yes      | -       | Human-readable definition; must not be empty. |
| `synonyms`    | `list[string]` | no       | -       | Alternative names for this term.              |

#### Validation Rules

* `terms` must have at least one entry
* Term keys must be non-empty and contain at least one non-whitespace character
* String fields with `minLength >= 1` reject whitespace-only values

### MacroSchema

A reusable text block that can be injected into routine steps.

| Field  | Type     | Required | Default | Description                                                                                                                                                           |
| ------ | -------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`   | `string` | no       | -       | Optional stable identifier for this macro. When provided, must be a non-empty string. Routines reference macros by their storage name; `id` is authoring convenience. |
| `text` | `string` | yes      | -       | The macro body injected at each `${macro-id}` call site in a routine's `chat_state`.                                                                                  |

### ScenarioSchema

A recorded conversation, replayable against any agent.

| Field               | Type                           | Required | Default | Description                                                                                                                                                                                                                                                       |
| ------------------- | ------------------------------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scenario`          | `string`                       | yes      | -       | Scenario name; also the dataset item id it is stored under.                                                                                                                                                                                                       |
| `customer_id`       | `string`                       | yes      | -       | Customer the replay runs as. Must start with `replay-`: the replay reuses this customer if it already exists and then writes the scenario's context variables onto it, so an id that collides with a real customer would overwrite their variables.               |
| `strict`            | `boolean`                      | no       | `True`  | When `true`, a tool with no fixture is refused. When `false` it falls through to the real service, which has real side effects — leave this on unless you mean it.                                                                                                |
| `context_variables` | `dict`                         | no       | -       | Context variables seeded before the first turn. Values are stored as JSON and serialized when seeded, so a recorded `"[]"` is written here as `[]`.                                                                                                               |
| `trigger`           | `Trigger`                      | no       | -       | Autonomous routine trigger. Set instead of customer messages.                                                                                                                                                                                                     |
| `messages`          | `list[string \| InternalNote]` | no       | -       | Customer messages and internal notes, posted in order, one turn each (a note with `trigger: false` runs none, so it cannot come last). Record them verbatim — including any timestamp prefix, which may be the only statement of the current date the model sees. |
| `fixtures`          | `list[Fixture]`                | no       | -       | Recorded tool results served in place of the real tools.                                                                                                                                                                                                          |
| `expect`            | `Expect`                       | no       | -       | What the replay asserts. Omit to run the scenario and report what happened without gating on it.                                                                                                                                                                  |

#### Trigger

An autonomous routine and the input payload that starts it.

| Field     | Type     | Required | Default | Description                                                    |
| --------- | -------- | -------- | ------- | -------------------------------------------------------------- |
| `routine` | `string` | yes      | -       | Manifest id of the autonomous routine to run.                  |
| `input`   | `dict`   | yes      | -       | JSON input payload validated against the routine input schema. |

#### InternalNote

A note from the business's support team, posted as an internal note

| Field           | Type      | Required | Default        | Description                                                                                  |
| --------------- | --------- | -------- | -------------- | -------------------------------------------------------------------------------------------- |
| `internal_note` | `string`  | yes      | -              | The note's text, verbatim.                                                                   |
| `author`        | `string`  | no       | `Support team` | Display name of the note's author, as the integration sends it.                              |
| `trigger`       | `boolean` | no       | `True`         | When `true`, the note runs a turn. When `false` it is only recorded, for the turns after it. |

#### Fixture

One recorded tool result, served in place of calling the real tool.

| Field       | Type           | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------- | -------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tool`      | `string`       | yes      | -       | Service-qualified tool id, `<service>:<tool>` — e.g. `tools:get_account_locks`. The service prefix is part of the match, so a bare tool name never applies.                                                                                                                                                                                                                                  |
| `arguments` | `dict`         | no       | -       | The arguments the tool was called with when recorded.                                                                                                                                                                                                                                                                                                                                        |
| `match`     | `list[string]` | no       | -       | Argument keys that must be equal for this fixture to apply — the arguments whose correctness the replay is asserting. Values are compared in the type the tool declares, so a recorded `"10"` equals `10` for an integer parameter; string parameters compare exactly. A call that gets them wrong is refused rather than handed the recording. Omit to let any call to this tool be served. |
| `result`    | `any`          | no       | -       | The recorded result, returned verbatim as the tool's data.                                                                                                                                                                                                                                                                                                                                   |
| `optional`  | `boolean`      | no       | `False` | When `true`, this fixture going unused is not reported as divergence. Use it for tools a differently-routed replay might reach, so a strict run diverges instead of failing the turn.                                                                                                                                                                                                        |

#### Expect

What the replay asserts. Every group is optional.

| Field      | Type                | Required | Default | Description                                                                                          |
| ---------- | ------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------- |
| `tools`    | `ExpectGroup`       | no       | -       | Assertions about tools called.                                                                       |
| `steps`    | `ExpectGroup`       | no       | -       | Assertions about routine steps reached.                                                              |
| `routines` | `ExpectGroup`       | no       | -       | Assertions about routines activated.                                                                 |
| `policies` | `ExpectGroup`       | no       | -       | Assertions about policies matched.                                                                   |
| `output`   | `OutputExpectation` | no       | -       | Assertions about emitted autonomous output.                                                          |
| `judge`    | `Judge`             | no       | -       | An LLM evaluator scored against a rubric. Omit to assert nothing about what the agent actually said. |

**ExpectGroup**

Assertions about one kind of observed fact.

| Field       | Type           | Required | Default | Description                                                                                                                                          |
| ----------- | -------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `called`    | `list[string]` | no       | -       | Tool ids that must have been called (`tools` group only).                                                                                            |
| `reached`   | `list[string]` | no       | -       | Routine steps that must have been reached (`steps` group only). Only resting states appear: a node that hands straight on to another never shows up. |
| `activated` | `list[string]` | no       | -       | Routine titles or policy names that must have activated (`routines` and `policies` groups).                                                          |
| `never`     | `list[string]` | no       | -       | Names that must NOT occur anywhere in the conversation.                                                                                              |

**OutputExpectation**

A recursive subset of the emitted autonomous output.

| Field      | Type   | Required | Default | Description                                                                                           |
| ---------- | ------ | -------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `includes` | `dict` | yes      | -       | Required output fields. Nested objects match recursively as subsets; lists and scalars must be equal. |

**Judge**

A rubric an LLM evaluator scores the replayed conversation against.

| Field    | Type     | Required | Default | Description                                                                                                                                                                                                      |
| -------- | -------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rubric` | `string` | yes      | -       | What makes a reply pass or fail, in plain language. State requirements and prohibitions explicitly and checkably — a vague rubric produces a flaky test, and the evaluator judges against nothing but this text. |

#### Validation Rules

* `messages` must have at least one entry
* A fixture's `tool` must be service-qualified as `<service>:<tool>`
* Every key named in a fixture's `match` must exist in its `arguments`
* String fields with `minLength >= 1` reject whitespace-only values

### VariableSchema

A set of named variables with optional defaults, used to parameterize agent behavior.

| Field       | Type                          | Required | Default | Description                                                                                          |
| ----------- | ----------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------- |
| `id`        | `string`                      | no       | -       | Optional stable identifier for this variable set. When provided, must be a non-empty string.         |
| `variables` | `dict[string, VariableEntry]` | yes      | -       | Variable definitions keyed by variable name. At least one entry is required; keys must be non-empty. |

#### VariableEntry

A single variable definition.

| Field           | Type     | Required | Default | Description                                 |
| --------------- | -------- | -------- | ------- | ------------------------------------------- |
| `description`   | `string` | yes      | -       | Human-readable description of the variable. |
| `default_value` | `any`    | no       | -       | Default value; any JSON type is accepted.   |

#### Validation Rules

* `variables` must have at least one entry
* Variable keys must be non-empty and contain at least one non-whitespace character
* String fields with `minLength >= 1` reject whitespace-only values


---

# 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/schemas/readme.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.
