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

# Examples

> Provide sample situations and the responses you want, with optional reasoning. They act as few-shot training data for the agent.

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

Examples are sample situation-and-response pairs that demonstrate how your agent should behave. They guide tone, response length, format, and domain focus — without needing to write lengthy instructions.

## Adding an example

1. Open your agent and go to **Examples** in the sidebar.
2. Click **Add example**, give it a name, and **Create**.
3. Fill in the three fields on the example card:
   * **Situation / Input** — what the user says or asks.
   * **Agent Action / Output** — how the agent should respond.
   * **Reasoning (optional)** — why this is the right decision. Useful for capturing intent; the agent sees this alongside the input/output.
4. **Save Changes**.

Examples are included in the agent's context at inference time, so the LLM can learn from them directly.

## Worked examples

**Hello world — set the tone.** Teach the agent to be concise:

* **Situation:** "How do I reset my password?"
* **Output:** "Go to Settings → Security → Reset password, then check your email for the link. Anything else?"
* **Reasoning:** Short, actionable, ends with an offer to help further.

One pair like this, placed first, nudges every reply toward the same crisp style.

**Medium — enforce a format.** Teach the agent to answer comparisons as a table:

* **Situation:** "What's the difference between the Pro and Team plans?"
* **Output:** *(a small markdown table comparing the two plans across price, seats, and features)*
* **Reasoning:** Comparisons are clearer as a table than prose; always use this format for "difference between X and Y" questions.

**Complex — capture a judgement call.** Teach the agent how to handle a tricky edge case:

* **Situation:** "Can you give me a discount? I'm a long-time customer."
* **Output:** "I can't apply discounts directly, but I can flag your account for our retention team who handle loyalty offers — want me to do that?"
* **Reasoning:** Never invent discounts (a policy boundary), but don't just say no — offer the compliant path. This pattern generalises to any "can you do X that you're not allowed to do" request.

The **Reasoning** field is where examples earn their keep on hard cases: it tells the agent not just *what* to do but *why*, so it generalises the principle to similar situations rather than parroting the exact wording.

## When to use examples

Examples are most useful when:

* The agent needs to match a specific tone (formal, casual, concise).
* Responses require a particular format (bullet lists, numbered steps, tables).
* The domain is specialised and general LLM behaviour is too generic.
* You want consistent handling of common questions.

## Ordering

Examples are presented to the LLM in the order they appear in the list. Drag a card by its header to reorder; the new order saves automatically. Put your most representative examples first.

Each card carries an `[EXAMPLE-N]` badge — the example's citation ID, matching its 1-based position in the list. The agent uses that ID to reference the example in its reasoning traces, so a card's ID shifts when you reorder.

## Limits

Each agent supports up to 1000 examples. The Situation, Output, and Reasoning fields each share the same character limit as other text fields.

## Importing examples

Use the **Upload Example Definition** button to bulk-load examples from a file or pasted text. The upload page accepts **Markdown, JSON, YAML, and TOML** (`.md`, `.json`, `.yaml`, `.yml`, `.toml`) — pick a format tab there for a ready-to-copy template. Each entry should include a `name`, `input`, `output`, and optional `reasoning`. Uploaded examples are added to your existing list.

## 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       | `examples`                                                                                    |
| Schema (HTTP) | [`GET /api/manage-mcp/schema/examples`](https://agentheya.com/api/manage-mcp/schema/examples) |

Example:

```json theme={null}
{
  "tool": "config.set",
  "owner_id": "<your owner_id>",
  "agent_id": "<your agent_id>",
  "section": "examples",
  "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.