9.2.0
Agents
Compatibility Matrix
0.17.2
9.2.0
0.17.1
9.1.0
0.17.0
9.0.0
0.16.0
8.4.0
0.15.3
8.3.0
0.15.2
8.3.0
0.15.1
8.3.0
0.15.0
8.3.0
0.14.0
8.3.0
0.13.0
8.2.0
0.12.1
8.1.0
0.12.0
8.1.0
0.11.0
8.1.0
0.10.2
8.0.0
0.10.1
8.0.0
0.10.0
8.0.0
0.9.5
7.0.0
0.9.4
7.0.0
0.9.3
7.0.0
0.9.2
7.0.0
0.9.1
7.0.0
0.9.0
7.0.0
0.8.15
6.1.5
0.8.14
6.1.5
0.8.13
6.1.5
0.8.12
6.1.5
0.8.11
6.1.5
0.8.10
6.1.5
0.8.9
6.1.5
0.8.8
6.1.5
0.8.7
6.1.2
0.8.6
6.1.2
0.8.5
6.1.1
0.8.4
6.1.1
0.8.3
6.1.1
0.8.2
6.1.1
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.
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
-
Platform secrets this manifest draws from. 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 for the agent's session and state store. Without this block sessions live in memory and are lost on restart; the schedules block requires it.
mcps
list[McpConfig]
no
-
MCP servers the agent connects to for tool calls. Each entry's tools are namespaced under its id.
search
ExternalSearch | CollectionsSearch
no
-
Where the agent looks things up to ground its answers; leave the block out to run without lookups. Choose one source with the type tag: external for your own HTTP search endpoint, or collections for a managed collection hosted by InteractiveAI.
webhooks
list[WebhookEntry]
no
-
Incoming webhooks from other systems. Each one gets its own POST /webhooks/{name} URL, checks the sender's signature, and starts the routines listed on it.
schedules
list[ScheduleEntry]
no
-
Recurring autonomous triggers; requires the database block.
replay
Replay
no
-
DEPRECATED and no longer read. Retained so configs that still carry it validate; omit it. Replay endpoints are always registered and a replay request names its own dataset.
Runtime
Runtime/process configuration: credentials and engine tuning knobs.
api_key
string
yes
-
Token callers must send to reach this agent, and that the agent sends back on its own autonomous callbacks. Must be a ${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
How many think-and-act steps the agent may chain in one turn. Raise it for work that needs longer chains of tool calls.
policy_batch_size
integer
no
5
How many policies the agent checks per model call. Smaller batches cost less per call but need more calls.
streaming
boolean
no
False
Send chat replies word by word instead of one whole message. Streamed turns use llms.response but ignore llms.fallback — a stream runs on a single model.
startup_review
boolean
no
True
Run advisory LLM reviews of loaded policies and routines after readiness, using llms.evaluation.judge. Enabled by default; each process start incurs model costs. Set false to disable these reviews. Deterministic startup checks always run.
generation_attempts
integer
no
3
How many times the agent retries a failing model call before giving up on it. Internal stages only escalate to llms.evaluation.fallback once these attempts run out, so a higher number delays that switch.
autonomous_default_timeout_seconds
integer
no
120
Timeout for autonomous runs whose routine sets no timeout_seconds of its own. A routine's own value always wins. Must not exceed autonomous_max_timeout_seconds.
autonomous_max_timeout_seconds
integer
no
600
Ceiling on every autonomous run's timeout. A routine's own timeout_seconds applies while it fits under this; anything longer is cut down to it. Shorter timeouts are never raised.
autonomous_callback_max_retries
integer
no
5
How many times to retry an autonomous callback or event webhook, with backoff, before giving up.
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, defaulting to the public production host. The LLM router and default traces endpoints are derived from it.
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 | ModelSpec
no
-
Main customer-facing model. Used for the reply, the thinking phrase and the search queries unless those are set separately.
fallback
list[string]
no
-
Backup customer-facing models, sent to the router together with the primary in one request; the router decides the order it tries them. Set [] to run on a single model.
api_key
string
yes
-
${VAR} env-ref for the InteractiveAI LLM router API key.
response
string | ModelSpec
no
-
Model that writes the message the customer reads, canned responses included. Omit to use default.
preamble
string | ModelSpec
no
-
Model for the thinking phrase and the tool announcement. Omit to use default.
search_query
string | ModelSpec
no
-
Model that turns the conversation into search queries, one call per query field. If it fails the agent searches with the customer's own message. Omit to use default.
evaluation
string | EvaluationLlms
no
-
Models for the agent's internal decisions — which tool to call, which policies match, where to go next in a routine. One model name sets them all; leave it out for the built-in defaults.
AgentContext
Behavioural context shared by every run of the agent: system prompt, language, routines, policies, glossaries, macros, preamble, greeting, and priority relationships.
system_prompt
PromptRef
yes
-
language
"match_user" | "English" | "French" | "Spanish" | "German" | string
yes
-
Which language the agent replies in. Pick a preset, or name any other language — the value is passed to the model as written, so use Portuguese, not pt.
routines
list[RoutineRef]
no
-
Routines the agent can run, as versioned references to the project's routine catalog.
reevaluation_tools
list[ReevaluationTool]
no
-
Tools that make the agent reconsider which routine and policies apply as soon as they run, instead of waiting for the customer's next message. Use it for tools that change state mid-turn, like an authentication call. It applies whether the tool succeeds or fails.
policies
list[PolicyRef]
no
-
Policies the agent follows — safety, compliance, tone — as versioned references to the project's policy catalog. They sit on top of every routine and are matched turn by turn, or applied always when the policy sets always_match.
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 routines can pull in with ${macro_id}, as versioned references to the project's macro catalog.
preamble
Preamble
no
-
Short phrases the agent may say before it replies, written here rather than referenced. Without this block it says nothing before replying.
greeting
string
no
-
Opening message for the first turn. The agent stays close to this wording, in the language it replies in, and skips its thinking phrase on that turn only.
relationships
Relationships
no
-
Cross-entity rules: priorities, entailments, and prerequisite guards. Omit when all routines and policies remain equal-priority and unguarded.
current_datetime
CurrentDatetime
no
-
Gives the agent the current date and time as the current_datetime variable, refreshed every turn. Without this block the agent has no clock.
PromptRef
Versioned reference to a prompt.
id
string
yes
-
Prompt id.
version
integer
yes
-
Exact prompt version to use.
RoutineRef
Versioned reference to a routine.
id
string
yes
-
Routine id.
version
integer
yes
-
Exact routine version to use.
ReevaluationTool
Tool that makes the agent reconsider which routine and policies apply as soon as it runs, mid-turn, whether it succeeds or fails.
id
string
yes
-
Tool id whose execution triggers reevaluation. Must match a tool exposed by an mcps server.
PolicyRef
Versioned reference to a policy.
id
string
yes
-
Policy id.
version
integer
yes
-
Exact policy version to use.
GlossaryRef
Versioned reference to a glossary.
id
string
yes
-
Glossary id.
version
integer
yes
-
Exact glossary version to use.
MacroRef
Versioned reference to a macro.
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.
examples
list[string]
yes
-
Example phrases in the agent's voice, e.g. "Let me check that for you." The agent does not reuse them word for word — it matches their tone and length.
announce_tools
boolean
no
False
Also say something short once a lookup finishes, while the rest of the reply is still being written. Makes tool-heavy turns feel faster. Example: "I've checked your account."
Relationships
Cross-entity rules declared per agent: priorities, entailments, and
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
-
When one policy matches, activate others with it. Policies only — routines cannot be pulled in this way.
requires
list[RequiresEntry]
no
-
Prerequisite guards. While a guard is unsatisfied the covered routines and policies are not evaluated at all. Declared once per agent; not on routine or policy content.
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
-
Puts higher above every routine in the manifest. Policies are unaffected, even when higher is one. Cannot be combined with over.
Entailment
Entailment link: when the when policy matches, every policy in also_apply is activated with it. Policies only — routines cannot be pulled in this way.
when
string
yes
-
Source policy (policy:<id>) whose match pulls in the targets.
also_apply
list[string]
yes
-
Policies activated whenever the source policy matches, each in policy:<id> form.
RequiresEntry
Prerequisite guard declared on the agent. While unsatisfied, the
tool
string
yes
-
Tool id that must have run successfully before the covered entities are evaluated. Bare (authenticate_customer) or qualified (integration:authenticate_customer), resolved the same way as reevaluate_after.
result_has
string | dict
no
-
What the tool's result must contain. A string names a key that must be present and non-empty; a mapping names keys that must each equal the given value. Omit to require only that the tool ran without a protocol error; a failure reported inside the payload still counts as a clean run.
all_routines
boolean
no
-
When true, every routine pinned on this agent is guarded (not policies). Mutually exclusive with on. Pair with excludes to carve out specific routines.
on
list[string]
no
-
Entities this guard covers, each in routine:<id> or policy:<id> form. Mutually exclusive with all_routines.
excludes
list[string]
no
-
Routines to leave unguarded when all_routines is set, each in routine:<id> form. Invalid with on.
CurrentDatetime
Injects the current date and time into the model's context on every turn.
timezone
string
no
UTC
IANA timezone name (e.g. Europe/Lisbon) the timestamp is rendered in. Defaults to UTC.
Traces
OpenTelemetry traces configuration: deployment tag, trace-id derivation, optional backend override.
deployment_environment
string
no
production
Environment label attached to every trace as deployment.environment, e.g. production, staging, dev.
trace_id_field
string
no
-
Key from an autonomous run's input to name its trace after. Set customer_id and traces read {agent}-cus_abc instead of a random autorun_<hex>.
backend
TracesBackend
no
-
Send traces to your own OTLP endpoint instead. Omit to send them to InteractiveAI 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.
path
string
no
/mcp
URL path of the MCP endpoint, starting with /. Defaults to /mcp. Set when the server mounts its endpoint elsewhere (e.g. /v2/mcp).
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
-
Routines this webhook can start. Each id must be listed in context.routines and the routine must be autonomous; the agent checks both at boot.
ScheduleEntry
A recurring autonomous-routine trigger.
name
string
yes
-
Unique schedule id used in job keys, logs, and traces.
routine
string
yes
-
Autonomous routine id, cross-referenced at boot.
cron
string
yes
-
5-field UTC cron expression, parse-validated at boot.
input
dict
no
-
Static routine input, schema-validated at boot.
callback_url
string
no
-
Optional signed callback URL, allowlist-checked at boot.
max_attempts
integer
no
1
Attempts per tick; values above 1 opt into failed-run retries.
Replay
DEPRECATED. Retained so existing configs validate; nothing reads it.
enabled
boolean
no
False
DEPRECATED and no longer read. Replay endpoints are always registered: they are bearer-authed, and fixtures are served only to sessions carrying a replay scenario, so a real conversation is unaffected. Gating this from the manifest put a deployment concern in content config, where unrelated deploys silently dropped it. The field is retained only so existing configs still validate; it will be removed.
dataset
string
no
-
DEPRECATED and no longer read. A replay request names its own dataset, which is required rather than defaulted so a run cannot silently read from the wrong one.
Validation Rules
Priority: exactly one of
overorover_all_routinesString fields with
minLength >= 1reject whitespace-only values
Context
RoutineSchema
A multi-node conversational or autonomous workflow.
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 (conversational routines only — an autonomous routine activates on its trigger event and ignores these conditions, but a placeholder is still required). 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, and requires participation.
AutonomousConfig
Configuration for autonomous routines that can be triggered via an API endpoint.
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. The server adds additionalProperties: false to every object node before use — you do not need to set it manually.
timeout_seconds
integer
no
120
Maximum runtime for an autonomous run, in seconds. Must be a positive integer. This declared value always wins UNLESS it exceeds the agent manifest's runtime.autonomous_max_timeout_seconds cap (default 600), in which case it is clamped to the cap (a WARNING is logged at config apply). If omitted, the manifest's runtime.autonomous_default_timeout_seconds (default 120) applies instead.
callback_url_allowlist
list[string]
no
-
Optional allowlist of hostnames the runtime may post the result callback to. Each entry is a hostname (api.example.com) or a dot-prefixed suffix (.example.com) matching the apex domain and any subdomain. A full URL is also accepted — only its hostname is compared; the scheme, port, and path are ignored. Wildcards are not supported: omit the field to allow any host. The trigger's callback_url is rejected with HTTP 400 when its hostname matches no entry.
RoutineNode
A single node in a routine's graph.
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).
awaits_customer
boolean
no
-
Whether this chat_state step is complete only once the customer has replied. Unset = derived from the graph: a speaking step the routine continues from (it has transitions) waits for the reply; a terminal speaking step does not. Only valid on chat_state nodes.
Transition
A single outbound edge from a routine node.
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
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.
continuous
boolean
no
False
The policy stays in force on every turn instead of retiring once its action has been carried out — tone and language rules, standing prohibitions.
agent_intention
boolean
no
False
The condition describes the agent's own likely next move ("You are likely to explain the terms") rather than something already in the conversation; the matcher then judges it against the reply being drafted. Word the condition accordingly.
awaits_customer
boolean
no
False
The action is complete only once the customer has responded ("ask for the account number"); the engine then keeps the policy in play until they do.
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 within the same response — on the next engine preparation iteration, not on a later customer 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 is re-matched on later turns with a lighter 'previously-applied' check instead of the full initial matching; set false to force full matching 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_instructionrequirestoolsthinkrequiresoutput_schemaoutput_schemaonly allowed onthink:nodestimeout_secondsminimum is 1callback_url_allowlistentries must be non-empty and wildcard-free (hostnames; a leading.matches subdomains)String fields with
minLength >= 1reject whitespace-only values
PolicySchema
A single condition/action behavioral rule — the manifest-authored form
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.
continuous
boolean
no
False
The policy stays in force on every turn instead of retiring once its action has been carried out — tone and language rules, standing prohibitions.
agent_intention
boolean
no
False
The condition describes the agent's own likely next move ("You are likely to explain the terms") rather than something already in the conversation; the matcher then judges it against the reply being drafted. Word the condition accordingly.
awaits_customer
boolean
no
False
The action is complete only once the customer has responded ("ask for the account number"); the engine then keeps the policy in play until they do.
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 within the same response — on the next engine preparation iteration, not on a later customer 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 is re-matched on later turns with a lighter 'previously-applied' check instead of the full initial matching; set false to force full matching 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 >= 1reject whitespace-only values
GlossarySchema
A collection of domain-specific terms and definitions the agent uses to understand context.
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.
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
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
-
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.
ScenarioSchema
A recorded conversation, replayable against any agent.
scenario
string
yes
-
Scenario name; also the dataset item id it is stored under.
customer_id
string
yes
-
Customer the replay runs as. Must start with replay-: the replay reuses this customer if it already exists and then writes the scenario's context variables onto it, so an id that collides with a real customer would overwrite their variables.
strict
boolean
no
True
When true, a tool with no fixture is refused. When false it falls through to the real service, which has real side effects — leave this on unless you mean it.
context_variables
dict
no
-
Context variables seeded before the first turn. Values are stored as JSON and serialized when seeded, so a recorded "[]" is written here as [].
trigger
Trigger
no
-
Autonomous routine trigger. Set instead of customer messages.
messages
list[string]
no
-
Customer messages, posted in order, one turn each. Record them verbatim — including any timestamp prefix, which may be the only statement of the current date the model sees.
fixtures
list[Fixture]
no
-
Recorded tool results served in place of the real tools.
expect
Expect
no
-
What the replay asserts. Omit to run the scenario and report what happened without gating on it.
Trigger
An autonomous routine and the input payload that starts it.
routine
string
yes
-
Manifest id of the autonomous routine to run.
input
dict
yes
-
JSON input payload validated against the routine input schema.
Fixture
One recorded tool result, served in place of calling the real tool.
tool
string
yes
-
Service-qualified tool id, <service>:<tool> — e.g. tools:get_account_locks. The service prefix is part of the match, so a bare tool name never applies.
arguments
dict
no
-
The arguments the tool was called with when recorded.
match
list[string]
no
-
Argument keys that must be equal for this fixture to apply — the arguments whose correctness the replay is asserting. A call that gets them wrong is refused rather than handed the recording. Omit to let any call to this tool be served.
result
any
no
-
The recorded result, returned verbatim as the tool's data.
optional
boolean
no
False
When true, this fixture going unused is not reported as divergence. Use it for tools a differently-routed replay might reach, so a strict run diverges instead of failing the turn.
Expect
What the replay asserts. Every group is optional.
tools
ExpectGroup
no
-
Assertions about tools called.
steps
ExpectGroup
no
-
Assertions about routine steps reached.
routines
ExpectGroup
no
-
Assertions about routines activated.
policies
ExpectGroup
no
-
Assertions about policies matched.
output
OutputExpectation
no
-
Assertions about emitted autonomous output.
judge
Judge
no
-
An LLM evaluator scored against a rubric. Omit to assert nothing about what the agent actually said.
ExpectGroup
Assertions about one kind of observed fact.
called
list[string]
no
-
Tool ids that must have been called (tools group only).
reached
list[string]
no
-
Routine steps that must have been reached (steps group only). Only resting states appear: a node that hands straight on to another never shows up.
activated
list[string]
no
-
Routine titles or policy names that must have activated (routines and policies groups).
never
list[string]
no
-
Names that must NOT occur anywhere in the conversation.
OutputExpectation
A recursive subset of the emitted autonomous output.
includes
dict
yes
-
Required output fields. Nested objects match recursively as subsets; lists and scalars must be equal.
Judge
A rubric an LLM evaluator scores the replayed conversation against.
rubric
string
yes
-
What makes a reply pass or fail, in plain language. State requirements and prohibitions explicitly and checkably — a vague rubric produces a flaky test, and the evaluator judges against nothing but this text.
Validation Rules
messagesmust have at least one entryA fixture's
toolmust be service-qualified as<service>:<tool>Every key named in a fixture's
matchmust exist in itsargumentsString fields with
minLength >= 1reject whitespace-only values
VariableSchema
A set of named variables with optional defaults, used to parameterize agent behavior.
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.
description
string
yes
-
Human-readable description of the variable.
default_value
any
no
-
Default value; any JSON type is accepted.
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?