# 3.0.0 (latest) *** ## Agents ### Compatibility Matrix | Agent Version | Schema Version | | ------------- | -------------- | | `0.5.0` | `3.0.0` | | `0.4.2` | `2.1.0` | | `0.4.1` | `2.1.0` | ### AgentManifest The complete definition of an agent deployment — identity, version, environment, and agent-specific configuration. | Field | Type | Required | Default | Description | | -------------- | ----------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` | `string` | yes | - | Human-readable display name for the agent. Free text; surfaced in the platform UI and logs. | | `id` | `string` | yes | - | Stable agent identifier, unique within the project. Used in URLs and routing — should be a URL-safe slug. Immutable across deploys; renaming an agent means deploying a new manifest under a new id. | | `version` | `string` | yes | - | Version label for this manifest revision. Free-form string (semver, build sha, calendar version — whatever the deployer tracks). Surfaced in logs and traces and changes whenever the manifest is re-applied with different content. | | `endpoint` | `boolean` | no | `False` | Whether the agent is exposed under a public URL. Defaults to `false` — the agent is reachable only via the platform's internal API. Set to `true` to provision a public-facing endpoint. | | `env` | `list[EnvVar]` | no | - | Plain environment variables injected into the agent process. Stored in cleartext in the manifest — use for non-sensitive configuration only; declare `secrets` for credentials. | | `name` | `string` | yes | - | Environment variable name. Must match the standard POSIX identifier form (letter or underscore followed by letters, digits, or underscores) so the value is reachable by every shell and runtime that reads `os.environ`. | | `value` | `string` | yes | - | Literal value bound to `name`. Stored in cleartext in the manifest — do NOT use this field for secrets; declare a `SecretRef` instead. | | `secrets` | `list[SecretRef]` | no | - | References to platform secrets to expose as env vars on the agent process. Each entry resolves to its stored key/value pairs at boot; values are never inlined into the manifest. | | `secretName` | `string` | yes | - | Identifier of the secret in the deployment's secret store (e.g. a Kubernetes Secret name). Serialized as `secretName` in YAML/JSON to match the platform's manifest syntax. | | `agent_config` | `AgentConfig` | yes | - | | #### EnvVar Environment variable passed to the agent at runtime. | Field | Type | Required | Default | Description | | ------- | -------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | yes | - | Environment variable name. Must match the standard POSIX identifier form (letter or underscore followed by letters, digits, or underscores) so the value is reachable by every shell and runtime that reads `os.environ`. | | `value` | `string` | yes | - | Literal value bound to `name`. Stored in cleartext in the manifest — do NOT use this field for secrets; declare a `SecretRef` instead. | #### SecretRef Reference to a secret made available to the agent as environment variables. | Field | Type | Required | Default | Description | | ------------ | -------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `secretName` | `string` | yes | - | Identifier of the secret in the deployment's secret store (e.g. a Kubernetes Secret name). Serialized as `secretName` in YAML/JSON to match the platform's manifest syntax. | #### Validation Rules * Priority: exactly one of `over` or `over_all_routines` * String fields with `minLength >= 1` reject whitespace-only values ### AgentConfig Configuration specific to the Interactive Agent — defines the LLM, behavioral context, tools, and integrations. | Field | Type | Required | Default | Description | | ---------------- | -------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `llms` | `Llms` | yes | - | | | `context` | `AgentContext` | yes | - | | | `database` | `Database` | no | - | Optional Postgres connection block for the agent's session/state store. When omitted the runtime falls back to its configured `STORAGE_SPEC` (typically `transient` for dev and a managed Postgres for production deployments). | | `traces_backend` | `TracesBackend` | no | - | Optional OTel-compatible traces endpoint. When omitted the runtime emits OTLP traces to the endpoint derived from `INTERACTIVEAI_HOST` using platform credentials. | | `mcps` | `list[McpConfig]` | no | - | MCP servers the agent connects to for tool calls. Each entry exposes its tools under the configured `id` namespace at runtime. Empty list means the agent runs with built-in tools only. | | `id` | `string` | yes | - | Runtime tool-namespace id (NOT a platform reference) | | `hostname` | `string` | yes | - | MCP server hostname. Must include the URL scheme (http\:// or https\://) and contain only the host — no path, query, fragment, port, or whitespace (port is carried by the separate `port` field). | | `port` | `integer` | yes | - | TCP port the MCP server listens on. Standard range 1–65535; no default — every MCP entry must declare its port explicitly. | | `transport` | `string` | yes | - | MCP transport protocol. Must be `streamable-http` — the current MCP spec transport. Legacy SSE transport is not supported by the runtime. | | `api_key` | `string` | no | - | Optional env-var reference for the MCP API key, in `${VAR_NAME}` form. The runtime resolves it and sends `Authorization: Bearer `. Literal keys MUST NOT be inlined here. Omit when the MCP server does not require authentication. | | `knowledge_base` | `KnowledgeBase` | no | - | Optional knowledge-base retrieval configuration. When set, the agent gains a retrieval tool wired to the configured endpoint and a framing prompt; omit to disable KB retrieval. | | `webhooks` | `list[WebhookEntry]` | no | - | Manifest-level third-party webhook bindings. Each entry exposes a `POST /webhooks/{name}` endpoint that HMAC-verifies requests against an env-var secret and dispatches them to one or more autonomous routines. | | `name` | `string` | yes | - | URL slug exposed under `POST /webhooks/{name}`. | | `secret_env` | `string` | yes | - | Env-var reference for the HMAC shared secret, in `${VAR_NAME}` form. The runtime re-reads the bare env var on every request so secret rotation picks up without a restart. Must be set in the runtime environment at boot. Literal secrets MUST NOT be inlined here. | | `header` | `string` | yes | - | HTTP header the provider uses to carry the signature (e.g. `X-Hub-Signature-256` for GitHub-style senders). | | `algorithm` | `string` | no | `sha256` | HMAC digest algorithm the provider signs with. Enum: \['sha256', 'sha1', 'sha512'] | | `prefix` | `string` | no | - | Optional literal prefix the provider prepends to the hex digest in `header` (e.g. `"sha256="` for GitHub). | | `routines` | `list[string]` | yes | - | Autonomous routine ids this webhook can fan out to. Each id must reference a routine declared in `context.routines` with an `autonomous:` block; cross-reference validation runs at boot, not in this schema. | #### Llms LLM selection for the agent: a primary model plus optional fallbacks. | Field | Type | Required | Default | Description | | --------------------- | -------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `default` | `string` | yes | - | Primary routable model id, `provider/specific-model` form (e.g. `openai/gpt-4o-mini`). | | `fallback` | `list[string]` | no | - | Models the runtime falls back to, in order, if `default` fails. Same routable id form as `default`. | | `api_key` | `string` | yes | - | Env-var reference for the InteractiveAI LLM router API key, in `${VAR_NAME}` form. Required whenever the `llms` block is present. Literal keys MUST NOT be inlined here. | | `evaluation` | `string` | no | - | Primary model for the engine's retry-loop evaluation calls. When unset, the runtime applies its hardcoded default. Same `provider/specific-model` form as `default`. | | `evaluation_fallback` | `string` | no | - | Model used when `evaluation` exhausts its retry loop. When unset, the runtime applies its hardcoded default. Pass the literal string `"none"` to disable the fallback layer entirely. | #### AgentContext The behavioural context shared by all runs of the agent. | Field | Type | Required | Default | Description | | -------------------- | ------------------------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `system_prompt` | `SystemPromptRef` | yes | - | | | `language` | `string` | yes | - | Language directive for the agent. Free text in v1; the sentinel value `match_user` instructs the agent to mirror the user's language. Other strings are treated as explicit language names. | | `routines` | `list[PromptRef]` | no | - | Routines the agent can run — each entry is a versioned prompt reference resolved against the project's routine catalog. Order is informational only; the engine matches routines by their declared conditions at runtime. | | `id` | `string` | yes | - | Prompt id/slug in the project | | `version` | `integer \| string` | no | - | Exact version of the prompt to bind to (int or string) | | `reevaluation_tools` | `list[ReevaluationTool]` | no | - | Tools whose successful execution forces the engine to re-evaluate routines and policies on the next turn instead of continuing along the current journey. | | `id` | `string` | yes | - | Tool id whose successful execution triggers a routine/policy reevaluation. Must match a tool exposed by an `mcps` server or a built-in tool name; cross-reference validation runs at boot, not in this schema. | | `policies` | `list[PromptRef]` | no | - | Behavioural policies layered on top of every routine — each entry is a versioned prompt reference resolved against the project's policy catalog. Policies are always-on guardrails (safety, compliance, tone) and do not consume turns. | | `id` | `string` | yes | - | Prompt id/slug in the project | | `version` | `integer \| string` | no | - | Exact version of the prompt to bind to (int or string) | | `glossaries` | `list[PromptRef]` | no | - | Glossary references injected into the agent's context — each entry is a versioned prompt reference resolved against the project's glossary catalog. Useful for domain vocabulary the model would not otherwise know. | | `id` | `string` | yes | - | Prompt id/slug in the project | | `version` | `integer \| string` | no | - | Exact version of the prompt to bind to (int or string) | | `preamble` | `Preamble` | no | - | Inline preamble configuration. When set, the agent emits a short preamble before invoking tools; omit to disable preambles. | | `relationships` | `Relationships` | no | - | Cross-routine / cross-policy priority overrides. Omit when the default priority (declaration order) is fine. | **SystemPromptRef** Reference to the prompt that supplies the agent's system prompt. | Field | Type | Required | Default | Description | | ----------- | ------------------- | -------- | ------- | ------------------------------------------------------ | | `prompt_id` | `string` | yes | - | Prompt id/slug in the project | | `version` | `integer \| string` | no | - | Exact version of the prompt to bind to (int or string) | **PromptRef** A reference to a project prompt at a specific version. | Field | Type | Required | Default | Description | | --------- | ------------------- | -------- | ------- | ------------------------------------------------------ | | `id` | `string` | yes | - | Prompt id/slug in the project | | `version` | `integer \| string` | no | - | Exact version of the prompt to bind to (int or string) | **ReevaluationTool** Entry in `reevaluation_tools` — opaque tool `id` reference. | Field | Type | Required | Default | Description | | ----- | -------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | yes | - | Tool id whose successful execution triggers a routine/policy reevaluation. Must match a tool exposed by an `mcps` server or a built-in tool name; cross-reference validation runs at boot, not in this schema. | **Preamble** Inline preamble configuration. | Field | Type | Required | Default | Description | | ---------- | -------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `examples` | `list[string]` | yes | - | Few-shot example preambles the model conditions on when deciding what to say before invoking a tool. Each entry is a natural-language sentence in the agent's voice (e.g. `"Let me check that for you."`). At least one example is required when the `preamble` block is present. | | `greeting` | `string` | no | - | First-turn greeting. When set, the model is instructed to make its first preamble a greeting close in meaning to this string (adapted for language). Subsequent preambles are unaffected. Omit to let the model choose its own opening. | **Relationships** | Field | Type | Required | Default | Description | | ------------------- | ---------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `priorities` | `list[Priority]` | no | - | | | `higher` | `string` | yes | - | Routine/policy reference that takes priority (manifest-internal name) | | `over` | `list[string]` | no | - | Routines/policies this entry takes priority over (manifest-internal names) | | `over_all_routines` | `boolean` | no | - | When set, this entry takes priority over every routine in the manifest. Only `true` is accepted — omit the key to opt out (use `over` instead). | **Priority** A single priority entry inside :class:`Relationships`. | Field | Type | Required | Default | Description | | ------------------- | -------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `higher` | `string` | yes | - | Routine/policy reference that takes priority (manifest-internal name) | | `over` | `list[string]` | no | - | Routines/policies this entry takes priority over (manifest-internal names) | | `over_all_routines` | `boolean` | no | - | When set, this entry takes priority over every routine in the manifest. Only `true` is accepted — omit the key to opt out (use `over` instead). | #### Database Postgres connection block for the agent's session/state store. | Field | Type | Required | Default | Description | | ---------- | --------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `hostname` | `string` | yes | - | Hostname of the Postgres server. Bare host only — no scheme, path, or port (port is carried by the separate `port` field). | | `port` | `integer` | no | `5432` | TCP port the Postgres server listens on. Defaults to `5432` (Postgres standard). Override only when the server is exposed on a non-default port. | | `user` | `string` | no | `postgres` | Postgres role the agent connects as. Defaults to `postgres`. Use a least-privilege role in production deployments. | | `password` | `string` | yes | - | Env-var reference for the DB password, in `${VAR_NAME}` form. Required whenever the `database` block is present. Literal passwords MUST NOT be inlined here. | | `dbname` | `string` | no | `postgres` | Name of the Postgres database the agent connects to. Defaults to `postgres` (the cluster's bootstrap DB). Override to isolate the agent's state in a dedicated database. | | `sslmode` | `string` | no | `require` | Postgres `sslmode` parameter applied to the connection. Defaults to `require` — encrypted but without certificate verification. Use `verify-ca` or `verify-full` in production when the server has a trusted certificate. `disable`/`allow`/`prefer` are accepted for parity with libpq but should be avoided over untrusted networks. Enum: \['disable', 'allow', 'prefer', 'require', 'verify-ca', 'verify-full'] | #### TracesBackend OTel-compatible traces endpoint. All fields are optional — runtime defaults apply. | Field | Type | Required | Default | Description | | ---------------- | -------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | `string` | no | - | Full OTLP HTTP traces endpoint URL (e.g. `https://cloud.langfuse.com/api/public/otel`). Must include the URL scheme. When unset, the runtime derives the endpoint from `INTERACTIVEAI_HOST`. Must be set together with `api_key` or not at all. | | `api_key` | `string` | no | - | Env-var reference for the traces API key, in `${VAR_NAME}` form. How the resolved value is sent is controlled by `api_key_scheme`. Must be set together with `url` or not at all. | | `api_key_scheme` | `string` | no | `bearer` | HTTP auth scheme the runtime applies to the resolved `api_key`. `bearer` sends `Authorization: Bearer ` (default; matches the OTel-spec recommendation for OTLP HTTP). `basic` sends `Authorization: Basic ` (typical when the resolved value is a `public_key:private_key` pair). Ignored when `api_key` is unset. Enum: \['bearer', 'basic'] | #### McpConfig Connection info for an MCP server (the `mcps` list in the manifest). | Field | Type | Required | Default | Description | | ----------- | --------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | yes | - | Runtime tool-namespace id (NOT a platform reference) | | `hostname` | `string` | yes | - | MCP server hostname. Must include the URL scheme (http\:// or https\://) and contain only the host — no path, query, fragment, port, or whitespace (port is carried by the separate `port` field). | | `port` | `integer` | yes | - | TCP port the MCP server listens on. Standard range 1–65535; no default — every MCP entry must declare its port explicitly. | | `transport` | `string` | yes | - | MCP transport protocol. Must be `streamable-http` — the current MCP spec transport. Legacy SSE transport is not supported by the runtime. | | `api_key` | `string` | no | - | Optional env-var reference for the MCP API key, in `${VAR_NAME}` form. The runtime resolves it and sends `Authorization: Bearer `. Literal keys MUST NOT be inlined here. Omit when the MCP server does not require authentication. | #### KnowledgeBase Knowledge-base retrieval configuration. | Field | Type | Required | Default | Description | | ---------- | ----------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `prompt` | `PromptRef` | yes | - | | | `hostname` | `string` | yes | - | Hostname of the knowledge-base server. Either a bare host (defaults to `http://`) or a `http://`/`https://` prefixed value; the port is carried by the separate `port` field, and path/query/fragment must not be embedded. | | `port` | `integer` | yes | - | TCP port the knowledge-base server listens on. Standard range 1–65535; no default — every KB block must declare its port explicitly. | | `path` | `string` | yes | - | HTTP path on the knowledge-base host that the runtime issues retrieval requests against (e.g. `/search`). Must begin with a slash and exclude scheme, host, query, and fragment. | | `api_key` | `string` | no | - | Optional env-var reference for the knowledge-base API key, in `${VAR_NAME}` form. The runtime resolves it and sends `Authorization: Bearer `. Literal keys MUST NOT be inlined here. | #### WebhookEntry Manifest-level entry that groups one or more autonomous routines | Field | Type | Required | Default | Description | | ------------ | -------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | yes | - | URL slug exposed under `POST /webhooks/{name}`. | | `secret_env` | `string` | yes | - | Env-var reference for the HMAC shared secret, in `${VAR_NAME}` form. The runtime re-reads the bare env var on every request so secret rotation picks up without a restart. Must be set in the runtime environment at boot. Literal secrets MUST NOT be inlined here. | | `header` | `string` | yes | - | HTTP header the provider uses to carry the signature (e.g. `X-Hub-Signature-256` for GitHub-style senders). | | `algorithm` | `string` | no | `sha256` | HMAC digest algorithm the provider signs with. Enum: \['sha256', 'sha1', 'sha512'] | | `prefix` | `string` | no | - | Optional literal prefix the provider prepends to the hex digest in `header` (e.g. `"sha256="` for GitHub). | | `routines` | `list[string]` | yes | - | Autonomous routine ids this webhook can fan out to. Each id must reference a routine declared in `context.routines` with an `autonomous:` block; cross-reference validation runs at boot, not in this schema. | #### Validation Rules * Priority: exactly one of `over` or `over_all_routines` * String fields with `minLength >= 1` reject whitespace-only values *** ## Context ### RoutineSchema A multi-step conversational workflow that guides the agent through a sequence of actions. | Field | Type | Required | Default | Description | | ------------------ | ------------------------ | -------- | ------- | ----------- | | `id` | `string` | no | - | | | `title` | `string` | yes | - | | | `conditions` | `string \| list[string]` | no | - | | | `description` | `string` | no | - | | | `extends` | `string` | no | - | | | `autonomous` | `AutonomousConfig` | no | - | | | `steps` | `list[RoutineStep]` | yes | - | | | `id` | `string` | no | - | | | `description` | `string` | no | - | | | `condition` | `string` | no | - | | | `source` | `string` | no | - | | | `fork` | `boolean` | no | - | | | `redirect` | `string` | no | - | | | `tools` | `list[string]` | no | - | | | `tool_instruction` | `string` | no | - | | | `chat_state` | `string` | no | - | | | `macro` | `string` | no | - | | | `think` | `string` | no | - | | | `output_schema` | `dict` | no | - | | #### AutonomousConfig Configuration for autonomous routines that can be triggered via an API endpoint. | Field | Type | Required | Default | Description | | ------------------------ | -------------- | -------- | ------- | ----------- | | `input_schema` | `dict` | yes | - | | | `output_schema` | `dict` | yes | - | | | `timeout_seconds` | `integer` | no | `120` | | | `callback_url_allowlist` | `list[string]` | no | - | | #### RoutineStep A single step within a routine workflow. | Field | Type | Required | Default | Description | | ------------------ | -------------- | -------- | ------- | ----------- | | `id` | `string` | no | - | | | `description` | `string` | no | - | | | `condition` | `string` | no | - | | | `source` | `string` | no | - | | | `fork` | `boolean` | no | - | | | `redirect` | `string` | no | - | | | `tools` | `list[string]` | no | - | | | `tool_instruction` | `string` | no | - | | | `chat_state` | `string` | no | - | | | `macro` | `string` | no | - | | | `think` | `string` | no | - | | | `output_schema` | `dict` | no | - | | #### Validation Rules * Step IDs must be unique across steps (`uniqueItemProperties`) * `tool_instruction` requires `tools` * `think` requires `output_schema` * `output_schema` requires `think` * `think` is mutually exclusive with `tools`, `tool_instruction`, `macro`, `chat_state`, `fork`, `redirect` * `tools` is mutually exclusive with `macro` and `chat_state` * Routing-only steps (`redirect` or `fork: true`) cannot have `tools`, `macro`, or `chat_state` * Each step must define at least one of `tools`, `macro`, `chat_state`, `think`, `redirect`, or `fork` * `conditions` is required unless `extends` is present * `timeout_seconds` minimum is 1 * String fields with `minLength >= 1` reject whitespace-only values ### PolicySchema A single-step behavioral rule — a condition-action pair that governs how the agent responds in specific situations. | Field | Type | Required | Default | Description | | -------------- | -------------- | -------- | -------- | -------------------------------- | | `id` | `string` | no | - | | | `name` | `string` | yes | - | | | `condition` | `string` | yes | - | | | `action` | `string` | no | - | | | `criticality` | `string` | no | `MEDIUM` | Enum: \['HIGH', 'MEDIUM', 'LOW'] | | `description` | `string` | no | - | | | `tools` | `list[string]` | no | - | | | `always_match` | `boolean` | no | - | | | `kind` | `string` | no | - | | #### Validation Rules * At least one of `action` or `tools` is required * 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 | - | | | `terms` | `dict[string, GlossaryEntry]` | yes | - | | #### GlossaryEntry A single glossary term. | Field | Type | Required | Default | Description | | ------------- | -------------- | -------- | ------- | ----------- | | `name` | `string` | yes | - | | | `description` | `string` | yes | - | | | `synonyms` | `list[string]` | no | - | | #### 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 | - | | | `text` | `string` | yes | - | | ### VariableSchema A set of named variables with optional defaults, used to parameterize agent behavior. | Field | Type | Required | Default | Description | | ----------- | ----------------------------- | -------- | ------- | ----------- | | `id` | `string` | no | - | | | `variables` | `dict[string, VariableEntry]` | yes | - | | #### VariableEntry A single variable definition. | Field | Type | Required | Default | Description | | --------------- | -------- | -------- | ------- | ----------- | | `description` | `string` | yes | - | | | `default_value` | `any` | no | - | | #### 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: 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: ``` GET https://docs.interactive.ai/schemas/readme.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.