> ## Documentation Index > Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](/sidebar-menu/purpose)\ **Related:** [Configuration guide](/configuration) ## 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 \ 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.\ (collected this turn), saved.\ (collected in earlier stages), current.isComplete / current.missing, stages.\.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. |