Purpose

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

Field reference: purpose — every field, type, default, and tier for this page.

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

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.

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 — 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 or its per-agent MCP URL, 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 — 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

Example:

{
  "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.