3.0.0

---

Agents

Compatibility Matrix

Agent Version	Schema Version
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

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 <key>. 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 <value> (default; matches the OTel-spec recommendation for OTLP HTTP). basic sends Authorization: Basic <base64(value)> (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 <key>. 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 <key>. 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