> 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). # 8.4.0 (latest) *** ## Agents ### Compatibility Matrix | Agent Version | Schema Version | | ------------- | -------------- | | `0.16.0` | `8.4.0` | | `0.15.3` | `8.3.0` | | `0.15.2` | `8.3.0` | | `0.15.1` | `8.3.0` | | `0.15.0` | `8.3.0` | | `0.14.0` | `8.3.0` | | `0.13.0` | `8.2.0` | | `0.12.1` | `8.1.0` | | `0.12.0` | `8.1.0` | | `0.11.0` | `8.1.0` | | `0.10.2` | `8.0.0` | | `0.10.1` | `8.0.0` | | `0.10.0` | `8.0.0` | | `0.9.5` | `7.0.0` | | `0.9.4` | `7.0.0` | | `0.9.3` | `7.0.0` | | `0.9.2` | `7.0.0` | | `0.9.1` | `7.0.0` | | `0.9.0` | `7.0.0` | | `0.8.15` | `6.1.5` | | `0.8.14` | `6.1.5` | | `0.8.13` | `6.1.5` | | `0.8.12` | `6.1.5` | | `0.8.11` | `6.1.5` | | `0.8.10` | `6.1.5` | | `0.8.9` | `6.1.5` | | `0.8.8` | `6.1.5` | | `0.8.7` | `6.1.2` | | `0.8.6` | `6.1.2` | | `0.8.5` | `6.1.1` | | `0.8.4` | `6.1.1` | | `0.8.3` | `6.1.1` | | `0.8.2` | `6.1.1` | | `0.8.1` | `6.1.1` | | `0.8.0` | `6.0.0` | | `0.7.6` | `5.0.0` | | `0.7.5` | `5.0.0` | | `0.7.4` | `5.0.0` | | `0.7.3` | `5.0.0` | | `0.7.2` | `5.0.0` | | `0.7.1` | `5.0.0` | | `0.7.0` | `5.0.0` | | `0.6.4` | `4.0.0` | | `0.6.3` | `4.0.0` | | `0.6.1` | `4.0.0` | | `0.6.0` | `4.0.0` | | `0.5.1` | `3.0.0` | | `0.5.0` | `3.0.0` | | `0.4.2` | `2.1.0` | | `0.4.1` | `2.1.0` | ### AgentManifest Agent deployment definition: identity, version, env vars, secrets, and agent config. | Field | Type | Required | Default | Description | | -------------- | ----------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | yes | - | Display name. Surfaced in the platform UI and logs. | | `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 for this manifest revision. Surfaced in logs and traces. | | `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. | | `agent_config` | `AgentConfig` | yes | - | | #### 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. | #### Validation Rules * Priority: exactly one of `over` or `over_all_routines` * 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[McpConfig]` | no | - | MCP servers the agent connects to for tool calls. Each entry's tools are namespaced under its `id`. | | `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. | | `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 chat replies word by word instead of one whole message. Streamed turns use `llms.response` but ignore `llms.fallback` — a stream runs on a single model. | | `generation_attempts` | `integer` | no | `3` | How many times the agent retries a failing model call before giving up on it. Internal stages only escalate to `llms.evaluation.fallback` 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. | #### 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` | `string \| ModelSpec` | no | - | Main customer-facing model. Used for the reply, the thinking phrase and the search queries unless those are set separately. | | `fallback` | `list[string]` | no | - | Backup customer-facing models, sent to the router together with the primary in one request; the router decides the order it tries them. Set `[]` to run on a single model. | | `api_key` | `string` | yes | - | `${VAR}` env-ref for the InteractiveAI LLM router API key. | | `response` | `string \| ModelSpec` | no | - | Model that writes the message the customer reads, canned responses included. Omit to use `default`. | | `preamble` | `string \| ModelSpec` | no | - | Model for the thinking phrase and the tool announcement. Omit to use `default`. | | `search_query` | `string \| 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` | `string \| 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. Pick a preset, or name any other language — the value is passed to the model as written, so use `Portuguese`, not `pt`. | | `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. | **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:` or `policy:` form. | | `over` | `list[string]` | no | - | References that `higher` outranks, each in `routine:` or `policy:` 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:`) whose match pulls in the targets. | | `also_apply` | `list[string]` | yes | - | Policies activated whenever the source policy matches, each in `policy:` 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:` or `policy:` form. Mutually exclusive with `all_routines`. | | `excludes` | `list[string]` | no | - | Routines to leave unguarded when `all_routines` is set, each in `routine:` 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. | #### 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_`. | | `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 `; `basic` sends `Authorization: Basic ` (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'] | #### McpConfig An MCP server the agent connects to. 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. | #### 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` * 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 \| list[string]` | 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. | | `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. | | `nodes` | `list[RoutineNode]` | yes | - | The routine's graph nodes, each declared exactly once; edges live on each node's `transitions`. 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. | #### 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 and by `transitions[].to`. | | `description` | `string` | no | - | Free-form note on the node's purpose. Not used by the engine; surfaced in traces and logs. | | `tools` | `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` and `think`. | | `tool_instruction` | `string` | no | - | Tells the LLM *how* to call `tools` — parameter mapping and derivation, not customer-facing messaging. Requires `tools`. | | `chat_state` | `string` | no | - | Instruction for what the agent should communicate; the node completes when the agent sends a message fulfilling it. Supports `${macro-id}` interpolation. Mutually exclusive with `tools` and `think`. | | `think` | `string` | no | - | Typed-inference instruction (REASON node): the LLM emits structured output matching `output_schema` without ending the turn, so think/tool nodes can chain within a single turn. Mutually exclusive with every other action field; requires `output_schema`. | | `output_schema` | `dict` | no | - | Draft 2020-12 JSON Schema validating the `think` node's structured output. The result is stored in `session.metadata.step_outputs[]` for downstream nodes. Required on `think:` nodes; rejected on any other node. | | `transitions` | `list[Transition]` | no | - | Outbound edges. Empty or omitted = terminal node. With 2+ entries every transition requires a `condition`. A node without an action must declare at least one transition (routing-only node). | **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` | no | - | Natural-language condition deciding when this edge is followed. Omitted or empty = unconditional. Required on every transition when the node declares 2+ transitions. | #### 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/`); 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` | yes | - | When this policy applies, in natural language (the engine's guideline matching condition). | | `action` | `string` | no | - | What the agent should do when the condition matches. Omit for an observation (condition only). | | `description` | `string` | no | - | Free-form rationale shown to operators; not used for matching. | | `criticality` | `string` | no | `MEDIUM` | Priority weight the engine gives this policy when rules compete. Enum: \['HIGH', 'MEDIUM', 'LOW'] | | `tools` | `list[string]` | no | - | Tool ids the agent may call when this policy applies (registered as engine guideline→tool associations). | | `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` * `think` requires `output_schema` * `output_schema` only allowed on `think:` 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/`); 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` | yes | - | When this policy applies, in natural language (the engine's guideline matching condition). | | `action` | `string` | no | - | What the agent should do when the condition matches. Omit for an observation (condition only). | | `description` | `string` | no | - | Free-form rationale shown to operators; not used for matching. | | `criticality` | `string` | no | `MEDIUM` | Priority weight the engine gives this policy when rules compete. Enum: \['HIGH', 'MEDIUM', 'LOW'] | | `tools` | `list[string]` | no | - | Tool ids the agent may call when this policy applies (registered as engine guideline→tool associations). | | `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 * 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]` | no | - | Customer messages, posted in order, one turn each. 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. | #### 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, `:` — 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. 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 `:` * 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.interactive.ai/schemas/readme.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.