How do I write an effective system prompt?

What does the system prompt decide?

The system prompt tells the agent in the AI Assistant step who it is, what job it does on this step and how it talks. The agent follows it in every reply.

We add some rules to every agent ourselves, so you don't need to write them in your prompt:

• It replies in whatever language the visitor writes in.
• Replies are shown on screen and read aloud, so the agent writes plain text without emoji, bold text or bullet points.
• When the knowledge base is on, it only says what is in the knowledge base and tool results; it doesn't make up what it can't find, it says it doesn't know.
• It doesn't do general tasks unrelated to your business (such as writing code, solving homework or writing long texts).
• On a step where it can't take tickets (“Can take tickets” is off and there's no handoff to a Request step), it doesn't promise things like “I've passed this on to the team”.
• If tool results include other people's details, it doesn't tell them to the visitor.

If you want something different (for example, also answering general questions), say so clearly in your prompt.

What goes where?

The easiest way to keep your prompt short is to put everything in the place the dashboard has for it:

• Information about your business (prices, opening hours, terms, frequently asked questions): the Knowledge base. When the knowledge base is on, the agent takes information only from it and from tools; it doesn't use information written in the system prompt in its answers.
• Which questions a tool is for: the tool's “When should it be used?” field. The format of a value the tool expects: the field's description (for example “Phone number with country code and no spaces: 905321234567”). See Tools.
• When the agent moves to another step: the handoff's “When should the AI move to this step?” box.
• Details to get from the visitor before moving on: the handoff's “Collect details first” section. The agent doesn't move to that step until they are complete.
• Values that never change in an integration action (board, list, channel): the action's “Configure” window.
• The agent's first line: “On-screen text”.

What's left for the system prompt is the agent's role, its tone, the order in which it does its job and the rules it must follow.

Split the prompt into sections

Sections with headings make the prompt easier for you to read and make it easier for the agent to tell what matters most. Start each heading on a new line with #. You don't need all of them; use the ones that help:

• # Personality: the agent's role and its character in two or three words (for example warm, patient).
• # Environment: where it talks with the visitor and what state visitors usually arrive in.
• # Tone: how long replies are and how to address the visitor (formal or casual). Define the tone only here, once.
• # Goal: the job the agent must get done on this step. If it takes several steps, write them in numbered order.
• # Rules: what the agent must never do, all in one place.

If you're just starting, Personality, Goal and two or three rules are enough; add sections as you need them. The prompt of the store agent created when you connect your store is written in this layout too.

Keep it short and clear

• Instead of long explanations, write short sentences that say what to do, such as “If you don't understand what the visitor wants, ask one question.”
• Don't repeat the same thing in different sections. Two sentences that contradict each other leave the agent unsure.
• Add “This is important.” to the end of your one or two most important rules, and write them once more in the Rules section. If you mark everything as important, nothing stands out.
• Because replies are also read aloud, set a length limit (for example “Use at most three short sentences.”) and ask it not to write link addresses.
• The longer the prompt, the more likely the agent is to lose sight of its main job. Move long information to the knowledge base and split different jobs into separate steps (below).

Don't write tools into the prompt

The tools and integration actions you turn on in the step reach the agent with their own descriptions. You don't need to list them in the prompt or explain when to use them; instructions written in two places drift apart over time.

• Write when your own tool should be called, and what to do if it returns nothing, in the tool's “When should it be used?” field (for example “Gets the free times for the day the visitor names. If there are none, suggest the nearest day with free times.”). Integration actions come with their descriptions ready.
• Describe the order of the job in the prompt's Goal section, without naming tools: “First tell the visitor the available times; when they pick one, create the appointment.”
• Put getting the visitor's confirmation before anything that can't be undone (cancelling, deleting, sending) in the Rules section.

You don't need to tell it to ask for a tool's required fields either: if a required field's value isn't in the conversation, the agent asks the visitor for it on its own. It doesn't ask for optional fields.

One step, one job

Rather than loading everything onto one agent, split the work. An agent focused on a narrow job answers more consistently and is easier to test and fix.

For example, a first agent can work out what the visitor wants and move them with a handoff to a “Sales” or “Support” agent. Each has its own prompt, knowledge base selection and tools. If you'd rather show visitors the options up front, you can make the same split with a Selection step.

Example

An example written for a dental clinic's appointment agent; adapt it to your business. Two tools, one that checks free times and one that creates appointments, are turned on in the step's Tools tab.

# Personality
You are the appointment agent of Nova Dental Clinic. You are warm, calm and patient.

# Environment
You are talking with a visitor on the clinic's website. Visitors usually come with pain or a complaint and want an appointment quickly.

# Tone
Speak briefly; use at most three short sentences. Be polite and friendly. Ask one question at a time.

# Goal
1. Find out which treatment the visitor needs.
2. Tell them the available times and help them pick one.
3. Repeat the day and time they picked, get their confirmation, then create the appointment.

# Rules
- Never create an appointment before the visitor confirms. This is important.
- Don't diagnose or recommend medication.
- If the visitor describes severe pain, bleeding or swelling, tell them to call the clinic right away.

The example has no tools: when to call them is written in the tools' own descriptions. It has no prices, address or opening hours either: those are in the knowledge base. And it has no rules about reply language, formatting or not making things up: we add those.

Test and improve

1. Open the draft with “Preview” and ask the agent the questions your visitors will ask. Add a few hard ones too: an off-topic request, a request with missing details, a request that pushes against your rules.
2. Find where an unexpected reply comes from: wrong or missing information comes from the knowledge base, the wrong tone from the Tone section, doing something forbidden from the Rules section, and calling a tool at the wrong time from the tool's description.
3. Change one thing at a time and try again with the same question; that's how you know what worked.
4. When you're happy, click “Publish”. Visitors only see the new prompt after you publish.

After publishing, keep checking the “Unanswered questions” tab on the Knowledge base screen and the agent's conversations. You can also see where the agent struggles by scoring conversations with AI.