> ## Documentation Index
> Fetch the complete documentation index at: https://www.plain.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom instructions

> Adjust how Ari behaves with instructions of your own, on top of its default behavior.

Custom instructions allow you to customize the base Ari agent, so that it is more contextually aware of how to operate in your Plain workspace, and how to provide support to your customers.

## Getting started

1. Read this documentation about the proper use and limitations of this feature

2. Go to [Ari → Preferences](https://app.plain.com/~/ai/ari/preferences)

3. Write your instructions in the **Custom Instructions** field, and save

4. Ari applies the instructions from the next customer message it handles, on both new and existing threads

A good way to build confidence is to write and configure your instructions while Ari is in [Shadow Mode](/docs/product/agents/ari/shadow-mode). Allowing you to see how they change Ari's behavior before sending customer replies.

## How Ari uses them

Ari applies the instructions are specific steps when it is operating:

1. Classifying what action to take next on a thread

2. Searching your knowledge sources

3. Writing a reply and handoff message

The instructions are one block of text, but Ari applies only the parts relevant to what it is doing at each step. Mixing tone, routing, and terminology guidance in one place is fine.

Instructions never override Ari's built in guardrails. Ari only states product facts your knowledge sources support, so instructions shape how it behaves, not what it knows.

## Writing good instructions

* **Phrase preferences, not bans.**

  * "Prefer app instructions where the documentation covers them" works well. "Never show API examples" can leave Ari unable to give any documented answer, so it hands off instead.

* **Facts belong in knowledge sources.**

  * Ari will not state product claims that only appear in instructions. Use instructions for behavior, knowledge sources for truth.

* **Keep exact wording short.**

  * Sign-offs, introductions, and handoff promises are followed most reliably when they are a sentence, not a paragraph.

## Examples

### Company context

Tell Ari who it works for, so that it is contextually aware of your business, mission, customers, and products.

```markdown theme={null}
You're an AI agent that works as part of the customer support team at Plain.
Plain provides AI first support infrastructure for B2B teams to consolidate
channels, orchestrate AI workflows, and build extensible, API first support
systems, that enable teams to automate triage, surface insights, and treat
support as a queryable data layer rather than just a ticketing tool.
```

### Custom introduction

Instruct Ari to introduce itself in a specific way when first talking to a customer.

```plaintext theme={null}
On your first reply in a conversation, introduce yourself briefly as Plain's
AI support assistant and mention that a human colleague is available if required.
Do not repeat the introduction in later replies.
```

### Custom handoff

Instruct Ari to include specific wording when handing off to a user, to ensure expectations are set correctly.

```plaintext theme={null}
When handing a conversation off to a human, let the customer know the team
typically responds within 2 hours on business days (9am to 6pm UK time), and
thank them for their patience.
```

### Escalation preferences

Customize which types of threads are routing away from Ari, even if Ari could answer from your knowledge sources.

```plaintext theme={null}
Questions about pricing, billing, invoices, or plan changes must always be
handled by a human; do not answer them yourself, hand the conversation off
instead.
```

### Clarifying questions

Ari asks for the specifics, waits, and picks the conversation back up when the customer answers. The second sentence matters: it tells Ari the question is the reply, not a reason to stop working.

```plaintext theme={null}
When a customer reports something broken or not working without including the
exact error message or what they were doing at the time, reply asking them for
those specifics instead of guessing at a fix. Still search the documentation as
normal, the question is your reply to the customer, not a reason to skip
searching.
```

### Terminology mapping

Bridge the words your customers use and the words your documentation uses, so searches land even when they do not match.

```plaintext theme={null}
Our customers often say "ticket" or "case" for what Plain and its documentation
call a "thread", and "close" for marking a thread as Done. Use the documentation
terminology when searching, and gently use the correct terms in your replies.
```

### Debugging before handoff

Have Ari collect what your team needs inside the handoff message, so the answer is waiting on the thread when they pick it up.

```plaintext theme={null}
Refund requests must always go to a human. When you hand off a billing or refund
conversation, ask the customer for their invoice number and the billing email on
the account in your handoff message, if they have not already provided them, so
the team can investigate faster.
```

### Documentation preferences

Bias which documented approach Ari leads with when your knowledge sources cover several.

```plaintext theme={null}
Our customers integrate directly against the GraphQL API and do not use the
TypeScript SDK. When the documentation shows both a TypeScript SDK example and a
raw GraphQL query or mutation, always show the raw GraphQL version.
```

### Footer

Instruct Ari to include a footer when sending a reply.

```plaintext theme={null}
End every reply with the sign-off "Best, the Plain support team" on its own line.
```

### Tone

Customize the tone and feel of Ari, this can also be done via [Tone of Voice](/docs/product/agents/tone-of-voice) preferences.

```plaintext theme={null}
Write in British English (for example organise, colour, whilst). Keep replies
warm and conversational, use contractions, keep them to a few short sentences
where possible, and address the customer by their first name.
```

### Deflect actions to MCP

Ari currently is unable to carry out actions, so instead of Ari handing off in a generic manner, you can instruct Ari to push your customers to use your MCP server instead.

```plaintext theme={null}
If a customer asks you to perform an action, if you are unable to carry it out,
let them know you can't carry out the action, explain your purpose as an agent,
and guide the customer to use our MCP instead.
```

## Limitations

There are known limitations to how Ari can use custom instructions. Keep these in mind, and contact the Plain team if you need help.

1. Override Ari's guardrails

2. Add links to replies, as Ari can only link to public knowledge sources

3. Hold a conversation open waiting for information before handing off; Ari asks in the handoff message instead

4. Guarantee which knowledge sources Ari searches; instructions steer wording, while knowledge source settings control access