4.0.0
Agents
Compatibility Matrix
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.
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.
secret_name
string
yes
-
Secret name as listed in Interactive Secrets.
Validation Rules
Priority: exactly one of
overorover_all_routinesString fields with
minLength >= 1reject whitespace-only values
AgentConfig
Agent-specific config: LLMs, behavioural context, tools, integrations, runtime tuning, and traces.
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
KnowledgeBase | ExternalSearch
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.
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.
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:
default
string
yes
-
Primary customer-facing model, provider/model form (e.g. openai/gpt-4o-mini).
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, preamble, and priority relationships.
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.
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.
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, or knowledge-base prompt by its project id.
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.
id
string
yes
-
Tool id whose successful execution triggers reevaluation. Must match a tool exposed by an mcps server or a built-in tool name.
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.
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.
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.
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.
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.
Traces
OpenTelemetry traces configuration: deployment tag, trace-id derivation, optional backend override.
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).
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.
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.
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.
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
overorover_all_routinesString fields with
minLength >= 1reject whitespace-only values
Context
RoutineSchema
A multi-step conversational workflow that guides the agent through a sequence of actions.
id
string
no
-
title
string
yes
-
conditions
string | list[string]
yes
-
description
string
no
-
autonomous
AutonomousConfig
no
-
steps
list[RoutineStep]
yes
-
AutonomousConfig
Configuration for autonomous routines that can be triggered via an API endpoint.
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.
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_instructionrequirestoolsthinkrequiresoutput_schemaoutput_schemarequiresthinkthinkis mutually exclusive withtools,tool_instruction,macro,chat_state,fork,redirecttoolsis mutually exclusive withmacroandchat_stateRouting-only steps (
redirectorfork: true) cannot havetools,macro, orchat_stateEach step must define at least one of
tools,macro,chat_state,think,redirect, orforktimeout_secondsminimum is 1String fields with
minLength >= 1reject whitespace-only values
PolicySchema
A single-step behavioral rule — a condition-action pair that governs how the agent responds in specific situations.
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
actionortoolsis requiredString fields with
minLength >= 1reject whitespace-only values
GlossarySchema
A collection of domain-specific terms and definitions the agent uses to understand context.
id
string
no
-
terms
dict[string, GlossaryEntry]
yes
-
GlossaryEntry
A single glossary term.
name
string
yes
-
description
string
yes
-
synonyms
list[string]
no
-
Validation Rules
termsmust have at least one entryTerm keys must be non-empty and contain at least one non-whitespace character
String fields with
minLength >= 1reject whitespace-only values
MacroSchema
A reusable text block that can be injected into routine steps.
id
string
no
-
text
string
yes
-
VariableSchema
A set of named variables with optional defaults, used to parameterize agent behavior.
id
string
no
-
variables
dict[string, VariableEntry]
yes
-
VariableEntry
A single variable definition.
description
string
yes
-
default_value
any
no
-
Validation Rules
variablesmust have at least one entryVariable keys must be non-empty and contain at least one non-whitespace character
String fields with
minLength >= 1reject whitespace-only values
Last updated
Was this helpful?