6.1.1 (latest)

---

Agents

Compatibility Matrix

Agent Version	Schema Version
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	-	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 (<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, greeting, and priority relationships.

Field	Type	Required	Default	Description
system_prompt	PromptRef	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[RoutineRef]	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[PolicyRef]	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[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 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.
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	Relationships	no	-	Explicit priority overrides between routines and policies. Omit when all routines and policies should remain equal-priority.

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 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.

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	-	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 the preamble block entirely to disable mid-conversation preambles.
announce_tools	boolean	no	False	When true, the agent also emits a short status message right after it finishes a background operation (e.g. a tool lookup) while the full reply is still being composed — e.g. "I've checked your account." Reduces perceived waiting time on tool-heavy turns. Defaults to false.

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:<id> or policy:<id> form.
over	list[string]	no	-	References that higher outranks, each in routine:<id> or policy:<id> form. Mutually exclusive with over_all_routines.
over_all_routines	boolean	no	-	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:<id>) whose match pulls in the targets.
also_apply	list[string]	yes	-	Policies (policy:<id>) 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_<hex>). 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 <value>; basic sends Authorization: Basic <base64(value)> (use for public_key:secret_key pairs). Enum: ['bearer', 'basic']

Database

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

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

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[<node-id>] 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/<id>); the agent server keys the guideline on it.
name	string	no	-	Human-readable display label for the InteractiveAI platform UI. Cosmetic — not used for matching. Defaults to id when unset.
condition	string	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/<id>); the agent server keys the guideline on it.
name	string	no	-	Human-readable display label for the InteractiveAI platform UI. Cosmetic — not used for matching. Defaults to id when unset.
condition	string	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