purpose

The heart of the agent: what it does (overview), how it should behave (behaviour, used as the system prompt), output preferences, an optional structured…

purpose — Purpose & behaviour

The heart of the agent: what it does (overview), how it should behave (behaviour, used as the system prompt), output preferences, an optional structured success checklist, and optional staged flows.

Section key purpose · Shape object · Tier All plans
Edit in the dashboard: Purpose page
Related: Configuration guide

Fields

Field	Required	Type	Allowed values / constraints	Default	Description
overview	no	string	—	—	A concise description of what this agent does, written in plain English. Shown to power-users and to MCP hosts in the tool description. Keep under 200 words.
behaviour	no	string	—	—	Detailed behavioural instructions — how the agent should approach problems, what to prioritise, what to avoid. Injected into the system prompt.
other_instructions	no	string	—	—	Any additional system-prompt instructions that don’t fit in behaviour — e.g. output format rules, language preferences, persona notes.
success_criteria	no	object	—	—	Structured checklist the agent uses to track whether it has met the user’s goal. Auto-registers a mark_goal_complete chat tool with a dynamic input_schema. Item fields below.
stages	no	array of object	—	—	Optional ordered list of stages the agent walks a power-user through. When non-empty, the active stage’s criteria replace top-level success_criteria for that power-user; mark_goal_complete uses the active stage’s items; advance_stage / go_to_stage chat tools become available. Item fields below.
output_contract	no	object	—	—	The agent’s expected final output: what its final reply must deliver, whether/how it should be formatted, and — for JSON — whether the platform hard-validates the output before returning it to API/agent callers. Injected into the system prompt for every reply, and (for A2A/MCP) attached to the response so calling agents know the expected shape. Item fields below.

success_criteria fields

Structured checklist the agent uses to track whether it has met the user’s goal. Auto-registers a mark_goal_complete chat tool with a dynamic input_schema.

Field	Required	Type	Allowed values / constraints	Default	Description
items	no	array of object	—	—	Ordered list of outcome checkpoints. Item fields below.
optional_min	no	integer	—	—	Minimum number of optional (non-required) criteria that must also be met.
done_when	no	string	—	—	Free-text description of the overall completion condition, injected into the system prompt.

stages items

Optional ordered list of stages the agent walks a power-user through. When non-empty, the active stage’s criteria replace top-level success_criteria for that power-user; mark_goal_complete uses the active stage’s items; advance_stage / go_to_stage chat tools become available.

Field	Required	Type	Allowed values / constraints	Default	Description
id	yes	string	—	—	Stable snake_case identifier (lower, digits, underscore; starts with a letter). Used to persist ‘current stage’ in power-user memory — must stay constant across renames.
name	yes	string	—	—	Human-friendly stage name shown to the owner in the dashboard and rendered into the system prompt as the active stage’s heading.
description	no	string	—	—	What this stage is for. Rendered into the system prompt when this stage is active.
criteria	no	array of object	—	—	Per-stage goals — same shape as success_criteria.items. Mark_goal_complete is rebound to these when this stage is active. Item fields below.
collapsed	no	boolean	—	false	Dashboard editor UI state.
final	no	boolean	Pro+	false	When true this is a TERMINAL stage (state-machine final state): the workflow ends here, the agent stops advancing, and the stage is exempt from the ‘no outgoing path’ dead-end check.
transitions	no	array of object	Pro+	—	Owner-declared outgoing transitions (branches) from this stage, evaluated in declared order, FIRST MATCH WINS. When present they REPLACE the default linear ‘advance to the next stage’. A stage with no transitions advances to the next stage in array order (backward-compatible). Always end a set of conditioned branches with a {when:{kind:‘default’}} transition so there is a guaranteed fallback path. Item fields below.

output_contract fields

The agent’s expected final output: what its final reply must deliver, whether/how it should be formatted, and — for JSON — whether the platform hard-validates the output before returning it to API/agent callers. Injected into the system prompt for every reply, and (for A2A/MCP) attached to the response so calling agents know the expected shape.

Field	Required	Type	Allowed values / constraints	Default	Description
expected_return	no	string	—	—	Plain-English description of what the agent’s final reply must deliver, e.g. ‘a one-paragraph summary followed by 3 recommended next steps’. Injected into the system prompt. Leave blank for no specific requirement.
format	no	enum	one of auto, plain, markdown, json	—	How the final reply must be formatted. ‘auto’ = the agent decides; ‘plain’ = plain text only (no Markdown); ‘markdown’ = Markdown; ‘json’ = a single valid JSON value and nothing else.
json_schema	no	string	—	—	Only used when format=‘json’. A sample JSON object or informal schema describing the desired structure. Shown to the agent and (for A2A/MCP) to calling agents.
strict_json	no	boolean	—	—	Only used when format=‘json’. When true, the platform validates that the final reply parses as JSON before returning it to API / agent callers (A2A, MCP, and non-streaming OpenAI-compatible calls), repairing it once if needed.

success_criteria.items items

Ordered list of outcome checkpoints.

Field	Required	Type	Allowed values / constraints	Default	Description
label	yes	string	—	—	Human-friendly name shown in chat and the dashboard.
key	yes	string	—	—	snake_case identifier, unique within this agent. Becomes the argument name in mark_goal_complete.
type	yes	enum	one of text, enum, number, boolean	—	Data type of the criterion value.
description	no	string	—	—	What meeting this criterion means in practice.
enum_values	no	array of string	—	—	Allowed values when type=‘enum’.
required	no	boolean	—	—	If true, all required criteria must be met before the goal can be marked complete.

stages.criteria items

Per-stage goals — same shape as success_criteria.items. Mark_goal_complete is rebound to these when this stage is active.

Field	Required	Type	Allowed values / constraints	Default	Description
label	yes	string	—	—	Human-friendly display name shown in chat and the dashboard when this stage goal is rendered. When empty, the agent UI falls back to displaying the key.
key	yes	string	—	—	snake_case identifier for this goal, unique within the stage. Becomes the argument name in mark_goal_complete when the stage is active, and appears in the XML context block fed to the agent.
type	yes	enum	one of text, enum, number, boolean	—	Data type of the criterion value. One of: text (free-text up to 2000 chars), enum (one of fixed string values), number (numeric), or boolean (true once satisfied).
description	no	string	—	—	Explains what meeting this criterion means in practical terms. Injected into the system prompt so the agent understands the goal’s intent and into the mark_goal_complete tool description so the agent knows what value to provide.
enum_values	no	array of string	—	—	Array of allowed string values when type=‘enum’. Required for enum criteria; ignored for other types. Injected into both the agent context and mark_goal_complete’s input schema.
required	no	boolean	—	—	When true, this goal must be satisfied (supplied with a value) before advance_stage can fire or mark_goal_complete succeeds. Required goals are rendered in the agent’s active-stage context block as mandatory checkpoints.

stages.transitions items

Owner-declared outgoing transitions (branches) from this stage, evaluated in declared order, FIRST MATCH WINS. When present they REPLACE the default linear ‘advance to the next stage’. A stage with no transitions advances to the next stage in array order (backward-compatible). Always end a set of conditioned branches with a {when:{kind:‘default’}} transition so there is a guaranteed fallback path.

Field	Required	Type	Allowed values / constraints	Default	Description
target	yes	string	—	—	Destination stage id. Must reference an existing stage in this agent’s stages[].
label	no	string	—	—	Short human label for this branch, shown to the owner in the dashboard and given to the agent as the decision rubric when when.kind=‘llm_choice’.
description	no	string	—	—	Optional longer explanation of when this branch should be taken.
when	yes	object	—	—	The guard that decides whether this transition may fire. Tagged union keyed by ‘kind’. Item fields below.

stages.transitions.when fields

The guard that decides whether this transition may fire. Tagged union keyed by ‘kind’.

Field	Required	Type	Allowed values / constraints	Default	Description
kind	yes	enum	one of complete, enum_equals, compare, default, llm_choice, tool_result, code	—	complete = fires once every REQUIRED goal of this stage is filled (the natural ‘this stage is done -> go here’); enum_equals = fires when a collected goal value equals a constant (data-driven branch); compare = numeric/boolean comparison on a collected goal (Business); default = unconditional else, MUST be last; llm_choice = the agent chooses among the declared targets; code = fires when the boolean expr evaluates truthy over the routing context — values/saved/current/stages (Business); tool_result = reserved for a later phase (never fires yet).
key	no	string	—	—	For enum_equals/compare: the goal key on THIS stage whose collected value is tested.
value	no	string	—	—	For enum_equals/compare: the value to test against (stored as a string; parsed to a number for numeric compares).
op	no	enum	one of ==, !=, >=, <=, >, <, contains	—	For compare: the comparison operator applied as (collected <op> value).
expr	no	string	Business+	—	For kind=‘code’ (REQUIRED then): a JS-like boolean expression evaluated over the routing context, fires when truthy. Available variables: values.<goalKey> (collected this turn), saved.<goalKey> (collected in earlier stages), current.isComplete / current.missing, stages.<stageId>.isComplete. Operators: == != === !== < <= > >= && || ! + - * / % and ternary; functions len(), lower(), upper(), includes(). Evaluated in a strict sandbox (no I/O, no globals); a parse/eval error fails open (edge does not fire). Example: saved.severity >= 4 && stages.kyc.isComplete.