Custom Instructions

Custom instructions allow you to customise 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

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. Allowing you to see how they change Ari's behaviour 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 a single block of text, but Ari applies whichever parts are relevant to what it is doing at each step, so it is fine to mix tone, routing, and terminology guidance etc in one place.

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

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

On your first reply in a conversation, introduce yourself briefly as Plain's
AI support assistant and mention that a human teammate 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 teammate, to ensure expectations are set correctly.

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

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

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.

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.

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.

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.

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.

End every reply with the sign-off "Best, the Plain support team" on its own line.

Tone

Customise the tone and feel of Ari, this can also be done via Tone of Voice preferences.

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.

Limitations

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