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

> Define who your agent is, how it should behave, and when it has succeeded.

<Info>
  **Field reference:** [`purpose`](/reference/purpose) — every field, type, default, and tier for this page.
</Info>

The Purpose page is where you define your agent's core identity. This is the most important configuration — it shapes every response the agent produces. A well-written purpose results in an agent that stays on-topic, keeps a consistent voice, and handles edge cases gracefully.

The page is organised into the sections below.

## 1. Purpose, Goals and Guidelines

A free-form Markdown body where you describe the agent's intent. A good entry covers three areas:

* **Purpose** — What problem does this agent solve?
* **Goals** — Any specific objectives the agent should strive for.
* **Guidelines** — How to achieve those goals, and the boundaries the agent must respect.

## 2. Identity, Behaviour, Preferences and Principles

A second free-form Markdown body that controls how the agent acts:

* **Identity** — What role does the agent play? Give it a name and a clear role.
* **Behaviour** — Tone and personality.
* **Preferences** — How the agent should respond (concise vs. verbose, what to prefer, what to avoid).
* **Principles** — Core values and non-negotiable boundaries.

Splitting the two sections keeps "what to do" separate from "how to do it" — easier to iterate on each independently.

## Agent Effort Level

Controls how much reasoning the agent puts into each reply — more effort means more thorough reasoning (and a higher cost per reply); less effort means faster, cheaper responses. Choose from six presets, in increasing order of effort and cost:

**Fast → Low → Medium → High → Extra → Max**

**Medium** is the default. This setting **autosaves** the moment you change it — it is not part of the page's **Save Changes** flow.

## Response Limits

Optional circuit breakers that stop a single reply from running away. Both also autosave:

* **Max response time** — once reached, the agent returns whatever it has so far instead of continuing. Leave as **No limit** for none.
* **Max tool loops** — how many tool-call rounds the agent may take before it must answer. Leave as **Platform default** for none.

## 3. Success Criteria

A structured checklist the agent must satisfy before declaring a task complete. The agent self-checks this list before calling the built-in `mark_goal_complete` tool.

### When is the goal complete?

A plain-language finish line (max 1000 characters). The agent uses this as a semantic gate in addition to the required-field check below.

Example: *"When the customer has confirmed a date and time they will attend the demo."*

### Criteria list

Each criterion has:

| Setting                        | What it does                                                                                                                   |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| **Label**                      | Human-friendly name (e.g. "Customer's preferred time").                                                                        |
| **Description**                | What the agent needs to gather or confirm for this criterion to count as satisfied.                                            |
| **REQUIRED / OPTIONAL toggle** | Required items are hard must-haves — the goal is incomplete until every one is met. Optional items count toward the threshold. |
| **Key** (schema details)       | Auto-derived `snake_case` identifier from the label. Edit manually to pin a custom key.                                        |
| **Type** (schema details)      | `text`, `enum`, `number`, or `boolean`.                                                                                        |
| **Allowed values** (enum only) | Comma-separated list, max 64 chars each.                                                                                       |

If you have any optional criteria, an **"Need at least N of M optional items"** threshold appears. Set to 0 to make optional items truly optional.

A live status footer tells you whether the criteria look correct, warns about rows missing a label, and flags when everything is optional with no threshold set.

### Verifying goals: Auto-check and Code Checks

Two optional layers verify that goals are *actually* met rather than self-reported:

* **AUTO-CHECK** (toggle at the top of the Goals card) — after every reply, all
  active goals are assessed and per-subscriber met / partial / unmet progress is
  persisted and shown to the agent next turn.
* **Add Code Check** (per goal) — attach your own JS/Python that verifies the
  goal against real data; an `unmet` verdict blocks `mark_goal_complete`.

See the dedicated [Goals & Goal Checks](/sidebar-menu/goals) page for the full contract,
the `goal` / `ctx` objects, the goal status map, and complete worked examples.

## Stages

Stages are optional. Leave them empty and the agent works toward your Success Criteria in a single open conversation. Define them and the agent walks each subscriber through a **sequence of stages** — a step-by-step workflow. While a stage is active, that stage's goals rebind `mark_goal_complete`, and the agent gets `advance_stage` / `go_to_stage` tools to move through the flow.

<Info>
  **Branching is a Pro feature.** Basic linear stages are available to everyone; the branch conditions, the "This stage ends the workflow" flag, and the flow-preview diagram require the Pro plan. The **Custom expression** branch guard additionally requires the Business plan.
</Info>

### Each stage

| Field                            | What it does                                                                                                                                                                                                                                                              |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**                         | The stage's display name. A stable id is derived from it and used to remember which stage each user is on.                                                                                                                                                                |
| **Description**                  | What the stage is for. Shown to the agent in the system prompt while the stage is active.                                                                                                                                                                                 |
| **Stage goals**                  | Same shape as [Success Criteria](#3-success-criteria) — each goal has a name, description, a REQUIRED / OPTIONAL toggle, a type (`text`, `enum`, `number`, `boolean`) and, for enums, allowed values. The agent won't advance until every **required** stage goal is met. |
| **This stage ends the workflow** | Marks the stage as terminal (`final`) — the flow stops here, and terminal stages have no branches.                                                                                                                                                                        |
| **Branches**                     | Where the agent goes next. See below.                                                                                                                                                                                                                                     |

### Branches

Each non-terminal stage can define **Branches** — ordered rules that decide the next stage. They are **evaluated top-down, and the first match wins**. **Leave Branches empty to auto-advance** to the next stage in order once the stage's goals are met.

Each branch pairs a **condition** with a target ("go to stage…"). The condition kinds are:

| Condition                                             | What it checks                                                                                                   |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **When this stage's goals are complete** (`complete`) | Fires as soon as the stage's required goals are met.                                                             |
| **When a goal equals a value** (`enum_equals`)        | A named goal equals a specific value (you pick the goal and the value).                                          |
| **When a goal compares** (`compare`)                  | A named goal compares against a value using an operator — `≥`, `≤`, `>`, `<`, `=`, `≠`, or `contains`.           |
| **Let the assistant choose** (`llm_choice`)           | The model decides, reading a plain-language **label** you write (e.g. *"Customer explicitly asks for a human"*). |
| **Custom expression** (`code`, Business plan)         | An advanced guard that fires when a sandboxed expression is true — revealed behind the **Advanced** toggle.      |
| **Otherwise (fallback)** (`default`)                  | A catch-all that routes wherever the earlier conditions didn't match.                                            |

A branch's condition may key on any goal from the current stage or an earlier stage. A read-only **Flow preview** diagram shows how the agent moves between stages, flagging any unreachable (amber) or dead-end (red) stages.

### Example: a simple linear flow

No branches — each stage auto-advances once its required goals are met:

```
Stage 1 — Qualify
  Goals:
    company_size  (enum: solo / small / mid / enterprise)  — required
    budget_band   (enum: under_10k / 10k_50k / over_50k)   — required
  Branches: none — auto-advances to "Book demo" once the goals are met

Stage 2 — Book demo   [ends the workflow]
  Goals:
    demo_time  (text)  — required
```

### Example: a branching flow

This triage flow exercises every condition kind. Branches are evaluated top-down, first match wins:

```
Stage — Triage
  Goals:
    issue_type  (enum: billing / technical / account)
    severity    (number)
  Branches:
    1. When a goal compares:        severity ≥ 4           → Escalate
    2. When a goal equals a value:  issue_type = billing   → Billing flow
    3. Otherwise (fallback)                                → General support

Stage — Escalate
  Branches:
    1. Let the assistant choose:  "Customer explicitly asks for a human"  → Human handoff
    2. Otherwise (fallback)                                → General support

Stages — Billing flow, General support, Human handoff   [all end the workflow]
```

## Examples

**Hello world — a focused helper.** The minimum that works is one clear sentence of Purpose:

```
Purpose: You answer questions about Acme's products using the uploaded documentation, and politely decline anything off-topic.
```

That alone gives the agent a clear job. Everything below refines it.

**Medium — a defined persona with guidelines.** Fill in both sections to give the agent a job *and* a personality:

```
Purpose: Help small business owners understand their financial statements and make better decisions about cash flow and growth.

Goals: Walk owners through a P&L, balance sheet, or cash-flow statement and answer follow-up questions.

Guidelines: Always recommend consulting a qualified accountant for tax advice. Never make specific investment recommendations.
```

```
Identity: You are Alex, a friendly financial advisor with expertise in small business accounting.

Behaviour: Warm, plainspoken, never condescending.

Preferences: Default to short answers and offer to expand. Always check that the user has understood before moving on.

Principles: Honesty over reassurance. If a question is outside your expertise, say so and suggest where to get help.
```

**Complex — a goal-driven agent with Success Criteria.** For agents that must *accomplish* something (qualify a lead, complete an onboarding, resolve a ticket), add structured **Success Criteria** (section 3). Each criterion has a key, type, and description, and the agent gets a `mark_goal_complete` tool whose arguments match your criteria:

```
Purpose: Qualify inbound sales leads and book a demo with sales-ready prospects.

Success Criteria:
- company_size   (enum: solo / small / mid / enterprise)  — required
- budget_band    (enum: under_10k / 10k_50k / over_50k)    — required
- timeline       (text)  — when they want to start
- demo_booked    (boolean)  — required
Done when: all required criteria are met and demo_booked is true.
```

The agent now works the conversation toward those outcomes, fills each criterion as it learns it, and calls `mark_goal_complete` when the goal is reached — giving you a structured, measurable definition of "done" instead of an open-ended chat.

## Expected Output

The **Expected Output** card defines what your agent should return as its *final* answer and how it should be formatted. This applies to every reply the agent produces — in chat, and when another agent or API client calls it. It's especially useful when your agent is consumed by other agents over [A2A](/a2a) or its [per-agent MCP URL](/mcp), where a predictable return shape matters.

* **Expected final return** — a plain-English description of what the 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.
* **Output format** — whether, and how, the reply is formatted:
  * **Auto** — the agent decides (no formatting directive).
  * **Plain text** — no Markdown, tables, or code fences.
  * **Markdown** — formatted Markdown.
  * **JSON** — a single valid JSON value and nothing else.
* **JSON structure** (JSON only) — paste a sample JSON object or an informal schema describing the shape you want back. It's shown to the agent and, for A2A/MCP callers, attached to the response so they know what to expect.
* **Strict JSON validation** (JSON only) — when on, the platform checks that the final reply parses as valid JSON before returning it to API / agent callers (A2A, MCP, and non-streaming OpenAI-compatible calls), repairing it once if it doesn't. Live token-streamed replies are still guided by the prompt but not post-validated.

When a contract is set, A2A and MCP responses also carry an `agentheya/output-contract` descriptor (format, expected return, JSON schema) so the calling agent knows the shape you promised to return.

## Tips

* Write in second person ("You are…") — this is the most effective framing for LLMs.
* Be specific rather than vague. "You help software engineers debug Python code" outperforms "You are a helpful assistant."
* Keep it focused. A narrow, well-defined purpose beats a broad, generic one.
* Use the **AI Helper** to generate and refine your Purpose and Behaviour sections.

## Character limit

Each of the Purpose and Behaviour text bodies supports up to the configured system-prompt limit. For most agents, a few hundred words per section is plenty. Longer prompts increase cost and can dilute focus.

## Manage via the Management MCP

This page can be configured programmatically through the [Management MCP](/manage-mcp) — useful for AI agents and CI pipelines.

|               |                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------- |
| Endpoint      | `https://manage.agentheya.com/mcp`                                                          |
| Tool          | `config.set`                                                                                |
| Section       | `purpose`                                                                                   |
| Schema (HTTP) | [`GET /api/manage-mcp/schema/purpose`](https://agentheya.com/api/manage-mcp/schema/purpose) |

Example:

```json theme={null}
{
  "tool": "config.set",
  "owner_id": "<your owner_id>",
  "agent_id": "<your agent_id>",
  "section": "purpose",
  "data": { /* see schema for accepted fields */ }
}
```

Partial updates are supported — only the fields you include are changed. Call `config.get` to read the current values and `schema.get` (or the HTTP schema URL above) to see the full field list.