> For the complete documentation index, see [llms.txt](https://aibotkit-docs.gitbook.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://aibotkit-docs.gitbook.io/documentation/chatbot-editor/instructions.md).
# BEHAVIOR: Instructions
**Instructions** is where you tell your agent who it is and how to behave. It's the first screen you land on when you open an agent.
Open your agent, then go to **Behavior → Instructions** in the left sidebar.
The screen has two parts: **Agent persona** and **Agent rules**.
***
## Agent persona
The persona sets the character your agent plays in every single conversation. It's three rows — click any row to open it and edit.
### Identity
Who your agent is, and what it's trying to achieve. This is the most important field on the page — your agent reads it before every reply it writes.
You can write your own, or start from a preset and edit it:
| Preset | Who it is |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sales** | A Sales Development Representative who qualifies inbound interest by asking about need, fit, and timeline — and listens more than it pitches. |
| **Support** | A frontline Customer Support Agent that gets to the real problem fast and speaks like a person, not a script. |
| **Booking** | A Booking Coordinator that helps visitors check availability and reserve the right service. |
| **Shopping Assistant** | A Personal Shopper that knows your catalog, compares options honestly, and matches each shopper to the right product. |
{% hint style="info" %}
Presets are a **starting point**, not a lock-in. Pick the closest one, then edit the text to match your business — your company name, who your visitors are, what a won conversation achieves. Keep product lists and prices out, though: those belong in [KNOWLEDGE](/documentation/chatbot-editor/step-2-training.md), where your agent looks them up fresh.
{% endhint %}
***
### Writing a good Identity
The Identity answers two questions: **who is your agent**, and **what does a successful conversation achieve**?
That's it. Two things it should never carry:
* **Step-by-step procedures.** "First ask this, then collect that" belongs in a [Playbook](/documentation/chatbot-editor/playbooks.md).
* **Facts that change.** Prices, offers, and product lists belong in your Knowledge sources — your agent looks them up fresh at answer time. The Identity should still be correct if you replaced your whole catalog tomorrow.
A well-structured Identity has three parts, each under its own header. (Agents created through onboarding come pre-structured this way — keep the headers.)
#### #Role — who your agent is
The Role defines who your agent is. It shapes every response the agent gives — its vocabulary, its attitude, its level of formality.
Write two or three short sentences starting with "You are…". The secret to a good role: describe what your agent *does* in conversation, not a list of adjectives.
> You are Maya, the design consultant for Fernwood Interiors. You ask about the visitor's space, style, and budget before suggesting anything, and you listen more than you pitch.
Notice what this doesn't do. It doesn't list services (your Knowledge sources cover that), and it doesn't say "warm, friendly, professional" (that's the Tone field's job). It shows character through behavior.
#### #Goal — what a won conversation achieves
The Goal is your agent's primary objective. It anchors every conversation — whenever your agent is unsure what to do next, it falls back to the goal.
Describe success in two or three sentences. Only success — your agent already knows how to handle the cases where it can't help, so there's no need to write about escalation or failure.
> Turn interested visitors into booked consultations. A won conversation means the visitor knows whether we're a fit for their project and, if we are, has shared their details so our team can call them.
**Using playbooks?** Add this one line to the Goal — it's the most important sentence for playbook-driven agents:
> The active playbook defines your steps and limits — follow it exactly.
And don't mention which details to collect (like "capture name and email") anywhere in the Identity. The playbook handles that, and two sets of instructions about the same thing will compete with each other.
#### #Business\_Context — a few lines about your business
Two or three lines: what your business is, who it serves, what makes it different.
> Fernwood Interiors is a boutique interior design studio in Austin serving homeowners and small offices. Projects range from single-room refreshes to full remodels, handled end-to-end by an in-house team.
One caution: **your agent treats these lines as absolute truth**, so double-check any number or capability you write here. If your context says "we host up to 1,000 guests" but your largest hall fits 800, your agent will confidently accept a 950-guest booking. Keep it accurate, and keep changing details (prices, current offers) out — those belong in Knowledge.
#### What you don't need to write
AI BotKit already teaches every agent to answer only from your content, offer a human handover, ask clarifying questions, respect your reply-length setting, reply in the visitor's language, and follow safety rules.
So skip sentences like "always be accurate", "answer from the knowledge base", or "be helpful and professional". They don't add anything — your agent already does all of that.
A handy test: if a sentence could apply to any chatbot on any website, delete it.
***
### Tone
Tone is how your agent should *sound*. It's kept separate from the Identity because the same character may need to sound different in different businesses — two support agents can behave identically while one sounds playful and the other formal.
Tone is **free text**, so you can describe your brand voice in your own words. Four presets are offered to start from:
* **Friendly** — Warm, encouraging, and easy to talk to. Simple language, a positive human voice.
* **Professional** — Clear, efficient, businesslike. Get to the point without filler.
* **Empathetic** — Patient and understanding. Acknowledge feelings before solving.
* **Direct** — Brief and to the point. Prioritise the answer, minimise pleasantries.
Keep Tone to one or two sentences about voice only — register, energy, and at most one behavioral cue ("acknowledge frustration once — then move to the fix"). If you find yourself writing steps or rules here, move them: Tone is only about how things sound.
{% hint style="info" %}
Across Identity and Tone together, aim for roughly **50–120 words**. Short and specific always beats long and thorough — every extra sentence dilutes the ones that matter.
{% endhint %}
**Reply length** sits in the same row. It controls how much your agent says:
| Setting | Length |
| ------------ | ----------------------- |
| **Short** | About 1 sentence |
| **Standard** | 2–3 sentences |
| **Long** | Up to about 5 sentences |
Short works well for widgets on busy pages; Long suits agents that explain products or policies.
### Language & time zone
* **Language** — the language your agent replies in. Over 100 languages are available.
* **Time zone** — the time zone your agent assumes when a visitor mentions dates or times ("tomorrow morning", "next Tuesday"). Choose the one your business operates in.
{% hint style="info" %}
Language and time zone used to live on a separate **General** screen. That screen has been removed — these two settings moved here, because they're things you *tell* the agent, and your agent's name moved to **Appearance → Interface**.
{% endhint %}
***
## Agent rules
Agent rules are the non-negotiable rules your agent must always follow — the lines it will not cross, in every conversation. Where the persona describes *character*, rules describe *conduct* in specific situations.
The AI pays extra attention to rules marked as **Hard rule** — use that to your advantage for the limits that matter most.
{% hint style="info" %}
Your agent starts with a **set of safety rules already written for you** — things like never performing live account actions and never asking for passwords or API keys. You can edit or switch these off, but we recommend leaving them on.
{% endhint %}
Click **Add rule** to create one. Good rules are concrete and situational, for example:
* "Never quote a price — always direct the visitor to the contact form instead."
* "Always ask for an order number before troubleshooting a delivery problem."
* "If someone asks about refunds, point them to our refund policy page and offer to connect them to a person."
### Guidance vs. Hard rule
Every rule has a **Kind**, shown in its own column in the rules table:
| Kind | What it means |
| ------------- | --------------------------------------------------------------------------------------------------- |
| **Guidance** | Followed when it applies. A [playbook](/documentation/chatbot-editor/playbooks.md) can override it. |
| **Hard rule** | Never broken, even if a playbook says otherwise. |
Use **Guidance** for preferences — how you'd like things done. Use **Hard rule** for the things that must never happen, whatever else is going on in the conversation — a minimum budget, a capacity limit, a refund policy. If your agent uses playbooks, this is also where the playbook's limits belong: see [why limits live outside the playbook](/documentation/chatbot-editor/playbooks.md#why-limits-live-outside-the-playbook).
Rules appear in a table with an **On** switch, so you can turn one off without deleting it. Your agent applies every enabled rule in every conversation.
{% hint style="warning" %}
Every enabled rule is sent to the AI on every message, so a long list makes replies slower and uses more of your allowance. Past about **10 enabled rules** the editor warns you. If you have more than that, some of them are probably [playbooks](/documentation/chatbot-editor/playbooks.md) in disguise.
{% endhint %}
{% hint style="info" %}
Rules apply **always**. If you want step-by-step handling for one *kind* of conversation — taking a booking, chasing an order, producing a quote — use [Playbooks](/documentation/chatbot-editor/playbooks.md) instead. Your agent loads a playbook only when the situation matches.
{% endhint %}
***
## Examples
Three complete personas, one for each common agent type. Adapt freely — swap in your business, keep the shape.
### 1. Customer Support — BrightBooks (accounting software)
**Identity:**
> **#Role**\
> You are the BrightBooks Assistant, the frontline support agent for our accounting software. You get to the specific problem fast and solve it in as few steps as possible.
>
> **#Goal**\
> Resolve the customer's issue in the conversation itself whenever possible, so they leave with a working answer — not a ticket number. The active playbook defines your steps and limits — follow it exactly.
>
> **#Business\_Context**\
> BrightBooks is online accounting software for freelancers and small businesses. Customers use it for invoicing, expense tracking, and tax reports, on monthly or yearly plans.
**Tone:**
> Calm, clear, and reassuring. Acknowledge frustration once — then move straight to the fix.
### 2. Lead Qualification — Harbor & Stone (kitchen renovation studio)
**Identity:**
> **#Role**\
> You are Ella, the project consultant for Harbor & Stone. You ask about the visitor's kitchen, their plans, and their timeline before talking about us, and you listen more than you pitch.
>
> **#Goal**\
> Qualify serious renovation inquiries and turn them into booked design consultations. A won conversation means we know the scope and timeline of their project and they've shared their contact details for our team to call. The active playbook defines your steps and limits — follow it exactly.
>
> **#Business\_Context**\
> Harbor & Stone is a kitchen renovation studio in Manchester serving homeowners within Greater Manchester. Every project is design-led and handled by our own fitters, from first sketch to final install.
**Tone:**
> Warm and unhurried, like a designer sketching ideas with you over coffee. Plain language — no trade jargon.
### 3. Shopping Assistant — Spoke & Saddle (bike shop, products and services)
**Identity:**
> **#Role**\
> You are the Spoke & Saddle Guide, a personal shopper who knows our bikes, gear, and workshop services inside out. You ask how and where someone rides before recommending anything.
>
> **#Goal**\
> Help every visitor find the right bike, gear, or service for the way they ride, and leave them confident enough to buy or book. Success is a visitor who knows exactly which option fits them and why.
>
> **#Business\_Context**\
> Spoke & Saddle is an independent bike shop in Portland selling road, gravel, and city bikes plus accessories, with an in-house workshop for servicing and repairs. It serves everyday commuters and weekend riders more than racers.
**Tone:**
> Friendly and enthusiastic, like a rider talking to another rider. Keep recommendations concrete and honest.
***
## Best practices
* **Show character through behavior, not adjectives.** "You ask about budget before recommending" teaches your agent something; "you are friendly and professional" doesn't — that's Tone's job.
* **Describe success only in the Goal.** Skip escalation and failure handling — your agent already knows what to do when it can't help.
* **Keep changing facts out of the Identity.** Prices, offers, and product lists belong in [KNOWLEDGE](/documentation/chatbot-editor/step-2-training.md), where your agent looks them up fresh.
* **Double-check every fact in Business Context.** Your agent treats it as absolute truth and will act on a wrong number with full confidence.
* **If you use playbooks, make the Goal defer to them** — "The active playbook defines your steps and limits — follow it exactly" — and never name details to collect in the Identity.
* **Don't restate what the platform already does** (accuracy, escalation, clarifying questions, language, safety). If a sentence could apply to any chatbot on any website, delete it.
* **Stay under \~120 words** across Identity and Tone. Every extra sentence dilutes the ones that matter.
* **Put your real limits in Agent rules as Hard rules** — a persona describes character; rules are what actually hold under pressure.
* **Test after every change.** Use **Test agent** (top right) and try the conversations your visitors actually have.
***
## Saving your changes
There's no permanent Save button on this screen. **Save appears in the title bar as soon as you change something** — its arrival is the signal that you have unsaved work. Click it to save; it disappears again once your changes are stored.
Use **Test agent** (top right) to open a live preview and try your changes before you put them in front of visitors.
***
## Related Topics
* [Playbooks](/documentation/chatbot-editor/playbooks.md) — Step-by-step procedures for common situations
* [APPEARANCE: Interface](/documentation/chatbot-editor/step-3-interface.md) — Your agent's name, greeting, and fallback message
* [KNOWLEDGE](/documentation/chatbot-editor/step-2-training.md) — What your agent actually knows
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://aibotkit-docs.gitbook.io/documentation/chatbot-editor/instructions.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.