> 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/5.0.0.md). # 5.0.0 *** ## Agents ### Compatibility Matrix | Agent Version | Schema Version | | ------------- | -------------- | | `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 | - | Name of a platform secret as listed in Interactive Secrets. 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 block for the agent's session/state store. Omit to use in-memory ephemeral storage. | | `mcps` | `list[McpConfig]` | no | - | MCP servers the agent connects to for tool calls. Each entry's tools are namespaced under its `id`. | | `search` | `any` | no | - | Retrieval-grounding source for the agent. Exactly one implementation, chosen by the `type` tag: `pgvector` (the built-in knowledge-base retriever over a Postgres/pgvector store) or `external` (a customer-owned HTTP endpoint that owns query rewriting and search). Omit to run the agent without retrieval grounding. The `type` tag is required when the block is present. | | `webhooks` | `list[WebhookEntry]` | no | - | Third-party webhook bindings. Each entry exposes `POST /webhooks/{name}`, HMAC-verifies the request, and dispatches it to one or more autonomous routines. | #### Runtime Runtime/process configuration: credentials and engine tuning knobs. | Field | Type | Required | Default | Description | | ----------------------- | --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `api_key` | `string` | yes | - | Shared bearer token. The agent verifies inbound `Authorization: Bearer` headers against it and sends the same header on autonomous-routine webhook callbacks. `${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` | Per-turn cap on chained think/tool steps within a single turn. Raise when an agent needs more complex chain of thought/action. | | `policy_batch_size` | `integer` | no | `5` | Number of policies evaluated per LLM call by the guideline matcher. Smaller batches reduce per-call tokens but increase total matching calls. | #### 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. Defaults to the public production host. Also derives the LLM router base URL (`/api/v1/`) and the default OTLP traces endpoint. | | `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` | no | `interactive/agent` | Primary customer-facing model, `provider/model` form (e.g. `interactive/agent`). | | `fallback` | `list[string]` | no | - | Additional customer-facing models forwarded to the LLM router alongside `default`. The router decides traversal when `default` fails. Same form as `default`; each entry must be a non-empty string. | | `api_key` | `string` | yes | - | `${VAR}` env-ref for the InteractiveAI LLM router API key. | | `evaluation` | `string` | no | - | Primary model for engine evaluation calls. Omit for the hardcoded default (`gemini-3-flash-preview`). | | `evaluation_fallback` | `string` | no | - | Model used when `evaluation` exhausts its retry loop. Omit for the hardcoded default (`gemini-3.1-pro-preview`). | #### AgentContext Behavioural context shared by every run of the agent: system prompt, language, routines, policies, glossaries, macros, preamble, and priority relationships. | Field | Type | Required | Default | Description | | -------------------- | ------------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `system_prompt` | `SystemPromptRef` | yes | - | | | `language` | `string` | yes | - | Language directive. `match_user` mirrors the user's language; any other string is treated as an explicit language name. | | `routines` | `list[VersionedRef]` | no | - | Routines the agent can run, as versioned references to the project's routine catalog. | | `reevaluation_tools` | `list[ReevaluationTool]` | no | - | Tools whose successful execution forces the engine to re-evaluate routines and policies on the next turn. | | `policies` | `list[VersionedRef]` | no | - | Behavioural policies (safety, compliance, tone), as versioned references to the project's policy catalog. Layered on top of every routine; the engine matches them against each turn (or applies them unconditionally when the policy is marked `always_match: true`). | | `glossaries` | `list[VersionedRef]` | no | - | Glossaries injected into the agent's context, as versioned references to the project's glossary catalog. | | `macros` | `list[VersionedRef]` | no | - | Reusable text snippets injected into routine `chat_state` via `${macro_id}` interpolation, as versioned references to the project's macro catalog. | | `preamble` | `Preamble` | no | - | Inline preamble configuration. Omit to disable preambles entirely. | | `relationships` | `Relationships` | no | - | Explicit priority overrides between routines and policies. Omit when all routines and policies should remain equal-priority. | **SystemPromptRef** Versioned reference to the prompt that supplies the agent's system prompt. | Field | Type | Required | Default | Description | | ----------- | --------- | -------- | ------- | ------------------------------------------- | | `prompt_id` | `string` | yes | - | Prompt id in the project. | | `version` | `integer` | yes | - | Exact prompt version to bind to (e.g. `3`). | **VersionedRef** Versioned reference to a routine, policy, glossary, macro, or knowledge-base prompt by its project id. | Field | Type | Required | Default | Description | | --------- | --------- | -------- | ------- | ------------------------------------------- | | `id` | `string` | yes | - | Prompt id in the project. | | `version` | `integer` | yes | - | Exact prompt version to bind to (e.g. `3`). | **ReevaluationTool** Tool whose successful execution forces the engine to re-evaluate routines and policies on the next turn. | Field | Type | Required | Default | Description | | ----- | -------- | -------- | ------- | -------------------------------------------------------------------------------------------------------- | | `id` | `string` | yes | - | Tool id whose successful execution triggers reevaluation. Must match a tool exposed by an `mcps` server. | **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. At least one of `examples` or `greeting` must be set. | Field | Type | Required | Default | Description | | ---------- | -------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `examples` | `list[string]` | no | - | Few-shot examples of preamble sentences in the agent's voice (e.g. `"Let me check that for you."`). The model uses these to match tone and length. Omit to disable mid-conversation preambles (a `greeting` may still be set on its own). | | `greeting` | `string` | no | - | First-turn greeting. When set, the agent emits a standalone opening message approximating this string (adapted for language) and the preamble is suppressed on turn one. Subsequent turns are unaffected. | **Relationships** Explicit priority overrides between routines and policies. Without these, all routines and policies have equal priority. | 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 | - | Entailment links: when a source policy matches, additional policies are activated. Policy→policy only. | **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 | - | When `true`, `higher` outranks every routine in the manifest (not policies, even when `higher` is a policy). Mutually exclusive with `over`. | **Entailment** Entailment link: when the `when` policy matches, every policy in `also_apply` is also activated. Policy→policy only (engine entailment is guideline→guideline). | Field | Type | Required | Default | Description | | ------------ | -------------- | -------- | ------- | --------------------------------------------------------------- | | `when` | `string` | yes | - | Source policy (`policy:`) whose match pulls in the targets. | | `also_apply` | `list[string]` | yes | - | Policies (`policy:`) activated whenever `when` matches. | #### Traces OpenTelemetry traces configuration: deployment tag, trace-id derivation, optional backend override. | Field | Type | Required | Default | Description | | ------------------------ | --------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `deployment_environment` | `string` | no | `production` | Deployment environment tag forwarded to OpenTelemetry as `deployment.environment` (e.g. `production`, `staging`, `dev`). | | `trace_id_field` | `string` | no | - | Input-payload key whose value names the OTel trace for autonomous runs (e.g. set to `customer_id` so traces land under `{agent}-cus_abc` instead of the synthetic `autorun_`). Unset = synthetic id. | | `backend` | `TracesBackend` | no | - | Custom OTLP traces backend. Omit to send traces to InteractiveAI's default endpoint 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. | | `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 | - | Autonomous routine ids this webhook can fan out to. Each id must match a routine in `context.routines` whose underlying YAML declares an `autonomous:` block; cross-references are verified at boot. | #### 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. 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 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. Passed through unchanged — `additionalProperties` is not inspected or stripped. | | `timeout_seconds` | `integer` | no | `120` | Maximum runtime for an autonomous run, in seconds. Must be a positive integer; no upper bound is enforced. | | `callback_url_allowlist` | `list[string]` | no | - | Optional allowlist of callback URLs the runtime may post results to. | #### 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 on the next 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 skips re-matching on later turns (fast path); set false to re-evaluate it 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 * 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 on the next 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 skips re-matching on later turns (fast path); set false to re-evaluate it 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`. | ### 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/5.0.0.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.