Write the system prompt

TL;DR. The system prompt — labelled "How the agent should behave" in the agent edit form — is the plain-English instructions the AI reads at the start of every conversation. It defines tone, what topics it should focus on, what it must not say, and when to hand off to a human. Visitors never see it. Pick a starting template, tweak it for your business, and iterate as you learn from real conversations.

#Where to find it

1. Go to AI Agents → Agents and click Edit on the agent you want to configure.
2. Open the Personality section (it's open by default on a new agent).
3. The big text box labelled "How the agent should behave" is the system prompt.

Right above the box you'll see "Start from a template" — a dropdown with five presets. Pick one and the box auto-fills. You can then tweak any line; nothing is locked.

#What the system prompt does

The system prompt is the single most important field on the whole agent — more important than the greeting or the lead-capture form. It's the instructions the AI reads before it sees the visitor's first message. Every reply is shaped by it.

You're effectively writing a job description for an employee who never sleeps and has access to your knowledge base.

Things the system prompt is good for:

• Tone of voice. "Be warm and patient." / "Speak like a Texas plumbing veteran who hates corporate jargon." / "Keep replies under 3 sentences."
• Boundaries. "Stick to topics in the knowledge base. Politely redirect off-topic chats." / "Never invent product features or prices."
• Hand-off rules. "If the visitor sounds frustrated or mentions billing, offer to connect them with our team right away."
• Identity. "You are the assistant for Acme Plumbing — a 24/7 service in Austin, Texas."

Things the system prompt is not for:

• Facts about your business. Those go in the knowledge base. The system prompt should tell the agent how to talk, not what's true.
• Lead-capture field labels. Use the Capture leads section instead.
• Hand-off keywords. Use the Words that trigger a hand-off field. The system prompt is for the attitude; the keywords are for the trigger.

#The five starting templates

Click the "Start from a template" dropdown to fill the box with one of these:

Each template is a real working prompt — not a placeholder. You can ship without changes if it fits your business, or use it as a starting point.

#A good system prompt has 4 parts

Whether you start from a template or write from scratch, aim for these four sections:

1. Identity — Who is the agent? What company? What's its role?
2. Topics — What is it allowed to talk about? What's off-limits?
3. Boundaries — What must it never invent? When does it hand off?
4. Style — Tone, length, formality.

Example for a roofing contractor:

You are the assistant for Sunrise Roofing, a residential roofing
company in San Antonio, Texas. We do replacements, repairs, and
inspections. Storm-damage estimates are free.

Topics:
- Answer questions about our services, service area, pricing
  ranges, and the inspection process — using the knowledge base.
- If asked about a competitor's product or general construction
  topics outside roofing, politely say it's outside your scope.

Boundaries:
- Never quote a firm price. Always say it depends on the job and
  offer to schedule a free inspection.
- If the visitor mentions a leak, water damage, or a recent storm,
  treat it as urgent and offer the hand-off immediately.
- If you don't know something, say so honestly. Never make up
  warranty terms, materials, or timelines.

Style:
- Warm and local. We're not a national chain — talk like a
  neighbour. Keep replies under 4 sentences when you can.

Notice what's NOT in this prompt:

• Specific service prices (those live in the knowledge base).
• The phone number (that's in your business info, surfaced automatically).
• A list of competitors (the agent shouldn't know or care).

#Tips that actually move the needle

1. Be specific about the company. "You are the assistant for Acme Co." is fine. "You are the assistant for Acme Co., a family-run HVAC company serving the Austin metro since 2003" is better — it gives the agent voice.

2. Use bullet rules, not paragraphs. The AI follows lists more reliably than prose. "Rules: 1. ... 2. ... 3. ..." outperforms a wall of text.

3. Tell it what NOT to do. "Never quote a firm price." / "Never recommend a competitor." / "Never agree to discounts you have not been told are available." These guardrails are cheap to write and prevent embarrassing mistakes.

4. Tell it when to hand off. "If the visitor mentions billing, refunds, legal, or sounds frustrated, offer the hand-off immediately." This is more reliable than relying on hand-off keywords alone.

5. Iterate from real conversations. Open AI Agents → Conversations, read transcripts, and find moments where the agent guessed, rambled, or missed a hand-off. Add a one-line rule to the system prompt that would have caught it. Save. Done.

6. Don't put facts in here. Pricing, service area, hours, product specs — those go in the knowledge base. The system prompt should reference how to use the knowledge base, not duplicate it.

7. Keep it under ~400 words. Long prompts dilute the rules. If you're writing 1000 words, the agent is being told too many things at once and the most important rules get drowned out.

#What visitors see (and don't see)

Visitors never see the system prompt. It's substituted into the LLM call on the server before the model is invoked. The browser has no copy of it, the embed widget JS has no copy of it, the conversation transcript shows only the visitor's messages and the agent's replies.

If you say something secret in the system prompt — internal pricing, an unannounced product, a phone number that shouldn't be public — it stays secret. (We still recommend treating the field like operational config: rotate it if a teammate leaves; don't put login credentials in it.)

#Test before going live

After you save:

1. Click Test on the agent edit page (top-right). A staff-only chat opens with the actual prompt + knowledge base — same code path the embed uses.
2. Try the obvious paths: "how much does X cost", "can you ship to Y", "I'm angry, I want a refund". See how the agent handles them.
3. Try the off-topic question. "What's the weather" / "recommend a competitor". The agent should redirect politely.
4. Try the hand-off trigger. Use one of your hand-off keywords; verify the agent escalates.

Iterate until you're happy. The agent doesn't see a difference between "Test" and "Live" — it's the same prompt either way.

#Related chapters

• 3. Teaching your agent (Knowledge) — facts go here.
• 4. Leads & hand-offs — capture + escalation are configured separately.
• 13a. Conversations inbox — read real transcripts to refine the prompt.
• Glossary