Write an Assistant's Instructions
Instructions are the rules an Assistant follows in every answer: what it is, how it speaks, what it assumes and what it must never do. An Assistant needs them before it can go into deployment.
Write or change the Instructions
In AI Assistants, open the Assistant.
On the Configure tab, under Assistant Details, type in Instructions, or paste the starter and fill in its placeholders.
Ask a few questions in Preview, which answers with the Instructions as typed, before you save.
Click Save Changes.
Visitors' next questions get the new Instructions.
What belongs in Instructions
Instructions apply to every answer, while the Knowledge Base is searched for each question and a search can miss. So rules go in Instructions and facts go in the Knowledge Base. A page or less of plain statements works best.
Cover | For example |
|---|---|
Voice | You are the documentation assistant for Acme Studio. Answer in the product's own voice, as your own expertise. |
Defaults | When the output format is unclear, assume Reverb 2.0 and say that you assumed it. |
Names | Use the labels and values users see in the interface, not internal names. |
No source narration | Never say where information comes from. State answers directly. |
No guessing | Never invent setting names, values or version details. If unsure, say what is uncertain. |
Scope | Don't answer licensing questions. Direct them to the support team. |
When testing shows the Assistant missing a fact it must never miss, add that one fact to the Instructions. Keep this rare, so the Instructions stay short.
What the Assistant gets besides its Instructions
With each question | What that means for the Instructions |
|---|---|
The page the visitor is reading, sent by both installs | They can tell it to answer about the current page when that is what the question asks. Preview sends no page. |
On a website, the Embedded Assistant's own rules for links: link a page by its name, and only to addresses it has seen | They need no rules about links. The Reverb Assistant cites the passage it used. |
The passages its Knowledge Base search found | They needn't repeat facts the Knowledge Base holds. |
A starting point you can paste
Paste this into Instructions, replace each bracketed placeholder, and delete any line that doesn't fit. It covers the ground above and no more, which is the right size for a first Assistant. Refine it from what your question list shows. See Test answers with a question list.
You are the assistant for [PRODUCT OR COMPANY NAME]. You answer questions
from [ITS PUBLISHED DOCUMENTATION, OR ITS WEBSITE] for [WHO ASKS, FOR
EXAMPLE: PEOPLE USING THE PRODUCT].
Voice
- Answer in [PRODUCT OR COMPANY NAME]'s own voice, as your own expertise.
Be direct and practical.
- Lead with the answer. Put steps after it, numbered in the order the user
performs them.
- Keep answers short. Answer the question that was asked, without padding.
Defaults
- When a question is ambiguous, assume [YOUR MOST COMMON CASE] and say that
you assumed it.
- Assume the user is on [CURRENT VERSION] unless they say otherwise.
Names
- Use the labels and values the user sees in the product, exactly as they
appear there.
- Never invent setting names, values, file names, prices or version details.
If you cannot confirm a name, say what is uncertain and describe the
general approach instead.
Answering
- State answers directly. Never mention where information comes from: no
"according to the documentation", no mention of files, uploads or searches.
- If your knowledge does not cover the question, say so plainly and point to
the closest page it does cover. Do not guess.
- If the question is about the page the user is viewing, answer about that
page.
Out of scope
- Do not answer questions about [TOPICS TO REFUSE, FOR EXAMPLE: LICENSING OR
ACCOUNT ISSUES]. For those, direct the user to [CONTACT OR CHANNEL].
Describe the route to a hard answer
With reasoning on, a model can search the Knowledge Base, think about what it found, and search again before it answers. Instructions can describe that route as well as the rules:
To answer a question about changing how something looks on the page: first
identify the element, then find the setting or variable that controls it,
and name where that setting lives.
Routes need reasoning. With Reasoning at Off, expect one search per answer. Routes of several steps work best at Medium or High, and each step adds time and cost. See Models and reasoning.
Give the short way out. Say what to do when a step finds nothing, such as: if you cannot confirm the exact name, say so and give the general approach.
Test the route. Add a question that only the whole route can answer. In Preview, the summary shown while the model reasons often shows where a route goes wrong.