Assistants
What an assistant is
An assistant is a version of Merlin with its own name, face and instructions. You choose it in the chat, from the list beside the Voice control, and from then on your questions are answered by that assistant until you choose another one or go back to Merlin. The list shows Merlin first, then your assistants in alphabetical order, and ends with [+] New Assistant, which opens the Assistants page so you can make one. Each answer in the chat shows the face and name of the assistant that gave it, and Merlin's own answers show Merlin's icon.
An assistant is a good way to keep a set of instructions you would otherwise type every time: "you help the service desk triage tickets", "answer in two sentences", "always say which help page you used". Merlin's own rules still apply to every assistant, and they always win.
You make and change assistants on the Assistants page of the Merlin app, at /merlin/assistants. The list on the left shows every assistant you can see; select one to see and change it on the right. Drag the bar between them to give the definition more room.
Creating an assistant
Select New. Your new assistant appears straight away with a random face and a name such as "New assistant", and it starts as a personal assistant that only you can see. Give it a name, change its face if you like, write its definition, then select Save.
Nothing is saved until you select Save. While there are unsaved changes the page says so, and if you try to leave the page or choose another assistant it asks before discarding them. Undo changes puts back what was last saved.
Writing a good definition
The definition is written in Markdown. It starts with a few settings between two lines of three dashes, followed by the assistant's instructions in your own words:
--- model: the model to use tools: [SearchDocumentation, GetTickets] voice: the voice for Voice Mode speed: 1.1 language: en-GB guardrails: - concise - british-english --- You help the service desk triage new tickets. Read the ticket, say which team should own it and why, and suggest a priority. If you are not sure, say so.
Some tips for the instructions:
- Say who it helps and what with. "You help account managers prepare for customer reviews" is more useful than "You are helpful".
- Say how to answer. How long, how formal, whether to use lists, what to do when it does not know.
- Be specific about what matters. If an answer must always name its source, or must never suggest changing anything, say so plainly.
- Keep it short. A clear page of instructions works better than a long one, and costs less (see below).
The settings
You do not have to type voice, speed or language yourself. The Voice, Speed and Language choices above the definition write the matching line into the settings for you, and choosing "Merlin's voice", "Normal speed" or "Same as the question" removes that line. If you edit the line by hand, the choice follows. A value that is not offered, such as a voice this environment does not have, is shown with "(not available)" and left as you wrote it.
| Setting | What it does |
|---|---|
model | The AI model the assistant asks for. It is used only where your tenant allows that model; otherwise Merlin's own model answers, and the chat says so. |
tools | The Merlin tools the assistant may use, such as searching the documentation or reading tickets. This can only narrow what Merlin may do, never add to it. Leave it out to allow all of Merlin's tools. |
voice | The voice the assistant speaks with in Voice Mode. A voice this environment does not have falls back to Merlin's voice. |
speed | How fast the assistant talks in Voice Mode, from 0.75 (three quarters of normal speed) to 2 (twice as fast). 1 is normal, and is used when no speed is set. The pitch of the voice stays the same at every speed. A speed outside that range is ignored, and the assistant talks at normal speed. |
language | The language the assistant answers in, whatever language the question is asked in, such as fr for French or en-GB for British English. Leave it out to answer in the language of the question. The languages offered are British English (en-GB), American English (en-US), French (fr), German (de), Spanish (es), Italian (it), Dutch (nl), Portuguese (pt), Polish (pl), Swedish (sv), Danish (da), Norwegian (nb), Finnish (fi) and Japanese (ja). Any other value is ignored. It changes the language of the answer only: Voice Mode still listens for questions in the same way. |
guardrails | Named behaviours added after Merlin's own rules: read-only (it cannot change anything), concise, british-english, cite-documentation and no-speculation. |
inherits | Another assistant whose guardrails this one also applies, by its id. See Inheriting guardrails below. |
Lines starting with # in the settings are comments and are ignored. A setting the assistant does not recognise is ignored too, rather than stopping it working.
Why a long definition costs more
A definition can be up to 32,000 characters, and the page shows its length and roughly how many tokens it uses. Above 16,000 characters the page warns you, for two reasons:
- It is sent with every question. The whole definition goes to the AI model each time anyone asks the assistant something, so a long definition makes every question cost more.
- It leaves less room for the conversation. The model can only consider so much text at once. The longer the definition, the less room is left for the conversation so far and for the question itself.
If a definition is getting long, look for repetition and for instructions that only matter occasionally, and keep the ones that matter every time.
Inheriting guardrails, and the Merlin base
Guardrails are named behaviours, such as concise or read-only, that an assistant applies on top of its instructions. An assistant can have guardrails of its own, can inherit the guardrails of another assistant, and always applies the Merlin base.
Inheriting from another assistant. Choose another assistant in the Inherits from list on the Assistants page, and this assistant applies that assistant's guardrails as well as its own. If that assistant inherits from a third, this one applies the third's guardrails too, and so on up the line. Choose Nothing to stop inheriting. The choice is written into the definition as a line such as inherits: 42, where 42 is the other assistant's id, so renaming an assistant never changes what inherits from it; the editor shows the name. Only guardrails are inherited: instructions, the model, tools, voice, speed and language always come from the assistant's own definition.
Who gets what. Each person inherits only from assistants they can see. If an assistant inherits from someone's personal assistant, the owner gets those guardrails and a colleague does not; for the colleague, inheritance stops at the assistant they cannot see, and nothing above it applies either. The same happens when the assistant it inherits from is deleted, and the editor says so. An assistant cannot inherit from itself, directly or through others: saving one that would is refused, with a message naming each assistant in the loop.
The Merlin base is a set of guardrails that applies to every assistant. A Super Admin sets it in Admin, Global Settings, as Merlin: Assistant Base Guardrails: guardrail names separated by commas, such as concise, british-english. An assistant cannot remove the Merlin base, and neither can the assistant it inherits from. Leave the setting empty for no base.
Guardrails apply in this order, and a guardrail named in more than one place applies once, in the first place it appears:
- Merlin's built-in rules, which always come first and always win.
- The Merlin base.
- Guardrails inherited from other assistants, the nearest first.
- The assistant's own guardrails.
The Guardrails section of the Assistants page shows every guardrail that applies, grouped by where it comes from. Only the assistant's own guardrails are changed there, in its definition; the Merlin base and inherited guardrails are shown read-only, and are changed where they are set.
Who can see it: personal, tenant, or both
Every assistant has one of three kinds of ownership. The page shows a plain sentence saying who will see the assistant once you save.
| Ownership | Who can see and use it | Who can change it | Who can create it, or move an assistant to it |
|---|---|---|---|
| Personal | Only you, in whichever tenant you are working. Nobody else can see it, not even a tenant administrator. | You | Anyone |
| Tenant, with an owner | Everyone in your tenant. | Its owner and your tenant's administrators | A tenant administrator only |
| Tenant only | Everyone in your tenant. | Only your tenant's administrators | A tenant administrator only |
Anyone can create a personal assistant and keep it for as long as they like. An assistant that the whole tenant can use speaks to every colleague with the tenant's authority, so only a tenant administrator can create one as "Tenant, with an owner" or "Tenant only", or change an existing assistant to either. If you are not a tenant administrator, those two choices are shown but cannot be selected, with the reason "Only a tenant administrator can share an assistant with the whole tenant."
You can make your own assistant personal at any time. If you already own an assistant that is shared with the tenant, it keeps working as it is, and you can still edit it and make it personal; once it is personal, only a tenant administrator can share it with the tenant again. A tenant administrator can also take ownership of a tenant assistant that nobody owns, or make one belong to the tenant alone. A tenant administrator can never see or change anyone's personal assistant.
Connections
An assistant can use your Connections, such as Jira or LogicMonitor, only when it has been granted them. The Connections section lists the Connections the assistant could be given, and the ones it has been given. Tenant Connections and personal Connections are marked differently.
- A personal assistant can be given your own personal Connections.
- A tenant assistant can be given your tenant's Connections, and one with an owner can also be given that owner's personal Connections, by the owner.
An assistant can never reach more than the person using it. A grant only allows an assistant to use a Connection that the person asking could already use. If a colleague asks your assistant something and they cannot use a Connection, neither can the assistant.
A grant can show a status that needs attention:
- Missing: the Connection has been deleted. The grant shows the name it had and allows nothing. Remove it to tidy up.
- Invalid: the assistant's ownership no longer permits the Connection, for example after a personal assistant was made tenant-only. The grant allows nothing until you remove it or change the ownership back.
When you choose a different ownership, the page tells you before you save which grants would become Invalid. Grants are never deleted by an ownership change.
Deleting an assistant
Select Delete and confirm. An assistant can be deleted even if someone is using it: any conversation that was using it is answered by Merlin from its next question, with a note in the chat saying the assistant was deleted. Deleting cannot be undone.
