> For the complete documentation index, see [llms.txt](https://docs.cekat.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cekat.ai/en/ai-and-platform/ai-agent/writing-ai-behavior-and-knowledge-base.md).

# Writing AI Behavior & Knowledge Base

A practical guide to writing AI Behavior and Knowledge Base content that is clear, accurate, and easy for Cekat AI Agents to follow.

The quality of an AI Agent's answers depends mostly on two things: **what you instruct it to do** (AI Behavior) and **what it knows** (Knowledge Base). This guide explains how each works and the best format for writing them.

{% hint style="info" %}
This guide follows the **new AI Agent layout** (AI Behavior, AI Actions & Routing, AI Configuration, and Knowledge Base tabs). If you still use the old layout, see [If You Still Use the Old Layout](#if-you-still-use-the-old-layout).
{% endhint %}

## 1. Understand What Each Part Does

The most common mistake is putting everything in one place. Each part has a different job:

| Part                        | What it does                                                          | What belongs there                                             | What does not                        |
| --------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------ |
| **Welcome Message**         | First greeting, sent **exactly as written** (not rewritten by the AI) | Greeting, short intro, 2–4 topic options                       | Instructions for the AI              |
| **Communication Style**     | Personality and voice                                                 | Identity, tone, language, form of address, reply length        | Product info, prices, SOPs           |
| **Conversation Flow**       | What the AI does in specific situations                               | Steps per scenario: asking, recommending, ordering, complaints | Long FAQ lists                       |
| **Rules & Restriction**     | Boundaries the AI must respect in every reply                         | Prohibitions, topic scope, privacy and compliance rules        | Tone, conversation steps             |
| **Additional Instructions** | Extra instructions, optionally for specific pipelines                 | Different handling for new leads, existing customers, etc.     | General rules that apply to everyone |
| **AI Actions & Routing**    | System actions: transfer to an agent, labels, pipeline moves          | Trigger conditions (Prompt, Keywords, Number Of Message)       | —                                    |
| **Knowledge Base**          | Source of facts                                                       | Products, prices, schedules, policies, FAQs, SOPs              | Behavior instructions                |

{% hint style="warning" %}
**The Knowledge Base is treated as information, not as instructions.** When AI Behavior and the Knowledge Base disagree, the AI is told to follow AI Behavior first. A line such as "Never give discounts" written only in the Knowledge Base is weak and may be ignored. Put rules like that in **Rules & Restriction**.
{% endhint %}

### How the AI uses them

1. **Every reply** includes your AI Behavior. Communication Style, Conversation Flow, and Rules & Restriction are always sent, in that order, followed by the Additional Instructions that apply to the conversation. An Additional Instruction applies when it has no pipeline selected, or when the conversation is currently in one of its selected pipelines. An instruction with an empty title or empty body is skipped. The Welcome Message is not part of this: it is sent to the customer as a message.
2. To answer a question, the AI searches the Knowledge Base by **meaning** (not exact keywords) using the customer's latest message and the recent conversation, and pulls only the **most relevant pieces** (Text, QnA, File, and Website content all compete in the same search). The maximum number of pieces is set by **AI Context Limit** in AI Configuration (50 if empty, never more than 60). When more than 20 pieces are found, the system re-ranks them and keeps only the best 20 or so. In practice the AI sees about 20 pieces per question, however large the Knowledge Base is.
3. The AI also reads recent conversation history, up to the **AI History Limit** (20 messages by default, minimum 10).

What this means for you:

* **Keep Behavior concise.** The longer and wordier it is, the more likely an important instruction gets missed.
* **Split Knowledge cleanly by topic.** The AI doesn't read the whole Knowledge Base, only the relevant pieces. Each piece must make sense on its own.
* **Break long flows (such as ordering) into steps**, because older messages can fall outside the history window.

### When instructions conflict

* **AI Behavior vs. Knowledge Base:** the AI is told to follow AI Behavior first, then the example answers, then the Knowledge Base.
* **Between AI Behavior fields:** no field automatically wins. Rules & Restriction does **not** override Conversation Flow just because it is a "rule". The AI reads them as one block, in the order Communication Style, Conversation Flow, Rules & Restriction, Additional Instructions, and decides which applies.
* So **don't leave conflicts to chance.** When one instruction must beat another, say so in plain words, for example: "This rule overrides every step in Conversation Flow." (See the emergency rule in the [Healthcare example](https://docs.cekat.ai/en/ai-and-platform/ai-agent/writing-ai-behavior-and-knowledge-base/example-healthcare.md).)

## 2. How to Write AI Behavior

### General principles

1. **One instruction, one sentence.** Use bullets, not long paragraphs.
2. **Use clear imperative verbs:** "Ask…", "Answer…", "Don't…", "Always…".
3. **State conditions explicitly:** "If the customer asks about price, …". Avoid "sometimes" or "if possible".
4. **Give example wording** for replies that must stay consistent (order forms, the line before a handoff).
5. **Avoid conflicting instructions** across fields. For example, Communication Style says "keep replies short" while Conversation Flow says "explain every benefit in detail". If an exception is intended, write it down explicitly (see [When instructions conflict](#when-instructions-conflict)).
6. **Don't copy facts** (prices, stock, addresses) into Behavior if they're already in the Knowledge Base. Two sources drift apart when only one is updated, and the AI gets confused.
7. Use `[...]` placeholders only in templates, and **replace all of them** before saving.

### Communication Style (max 5,000 characters)

Recommended structure:

```plaintext
## Identity
- You are [AI name], the [role] of [Business name], [one-sentence business description].
- Refer to yourself as "[AI name]".

## Tone & Form of Address
- Tone: [friendly / professional / empathetic], [semi-formal].
- Address customers as "Kak" (or "Bapak/Ibu" if the customer writes formally).
- Use emoji sparingly, at most 1 per reply.

## Language
- Reply in the customer's language (Indonesian, English, Javanese, etc.).

## Reply Format
- At most 3–4 sentences per bubble. Break long information into bullet points.
- Don't use tables or markdown headings in chat.
- Ask at most 1 question per reply.
- End each reply with a relevant follow-up question, unless the conversation is finished.
```

### Conversation Flow (max 8,000 characters)

Write it as a **list of scenarios**. Each scenario has a trigger and numbered steps.

```plaintext
## [Scenario name]
Trigger: [when this scenario applies]
1. [First step]
2. [Next step]
3. [Outcome / closing line]
```

Scenarios you should usually include:

| Scenario                                | Example content                                             |
| --------------------------------------- | ----------------------------------------------------------- |
| Opening / qualification                 | Ask for name and needs, one at a time                       |
| Information questions                   | Answer from the Knowledge Base, then point to the next step |
| Recommendation / offer                  | Ask about needs, give 1–3 options, mention benefits         |
| Transaction (order / booking / sign-up) | Send a data form, check completeness, confirm a summary     |
| Objections / hesitation                 | Acknowledge, give 1 strong reason or an active promo        |
| Complaints                              | Apologize, collect details, say the team will help          |
| Information not available               | Don't guess; say the team will check                        |

{% hint style="info" %}
**Price calculations:** If the AI needs to calculate totals (shipping, COD fees, installments), write the formula as steps and ask the AI to show each line item before the total. Set **AI Creativity Level** to **Consistent**, and use the **Advanced** or **Auto** model for calculations.
{% endhint %}

### Rules & Restriction (max 3,000 characters)

These are hard limits. Keep them short and firm, ordered from most to least important.

```plaintext
## Must
- Answer ONLY from the Knowledge Base and these instructions.
- If information isn't available, say the team will check. Never guess or make things up.

## Must not
- Don't give prices, promos, or schedules that aren't in the Knowledge Base.
- Don't ask for passwords, PINs, OTPs, or full card numbers.
- Don't discuss or recommend competitors.
- Don't answer topics outside [business scope]. Politely steer back.
```

### Additional Instructions (max 30 instructions, 2,000 characters each)

Use these for behavior that **differs by customer stage**, by selecting a **Pipeline**. The instruction applies only while the conversation is in the selected pipeline. Without a pipeline, the instruction applies to all conversations.

Examples:

* **New Leads** pipeline: focus on qualification and education.
* **Awaiting Payment** pipeline: remind the customer of the deadline and how to pay.
* **Returning Customers** pipeline: greet them as loyal customers and offer a repeat-order program.

Each instruction is shown to the AI as "title: body", so **the title is read by the AI too**. Give each one a clear title (max 100 characters), such as "Awaiting Payment Pipeline – Reminder". Both the title and the body must be filled in, otherwise the instruction is skipped.

### Splitting a reply into bubbles (`###`)

To send an answer as several chat messages, put a separator on its own line between the parts. In the editor, click the bubble button, or type `###` alone on a line.

* It works in **every** AI Behavior field (Welcome Message, Communication Style, Conversation Flow, Rules & Restriction, Additional Instructions) and in **Knowledge Text** and example answers.
* In Behavior and Knowledge, it is an instruction to the AI: wherever it finds a separator, it keeps it in its reply, and the system then sends each part as a separate message.
* In the **Welcome Message**, the separator splits the greeting into separate messages on chat channels. On the website live chat widget, the greeting is shown as a single message.
* Only a line that contains **just** `###` is a separator. `### Title` with text after it is a normal heading.
* Avoid writing `###` in the middle of a sentence. Any `###` in the AI's final reply splits the message.

### How Behavior relates to AI Actions & Routing

Transfers to human agents, labels, and pipeline moves are configured in **AI Actions & Routing**, not in Behavior.

* In **Behavior**, define only **what the AI says** before or during a handoff. Example: "Tell the customer an admin will help shortly."
* In **AI Actions & Routing**, define **when** the action happens:
  * **Keywords** for clear requests, such as "admin", "refund", "complaint".
  * **Prompt** for conditions that need context, such as "the customer has sent complete order details and confirmed the order".
  * **Number Of Message** as a safety net so long conversations still reach a human.
* Agent Transfer allows at most one condition per trigger type (Prompt, Keywords, Number Of Message), so up to 3 in total.
* To hand off to a specific team or division, see [Handoff to a Specific Team or Division via Prompt](https://docs.cekat.ai/en/ai-and-platform/ai-agent/ai-agent-behavior/handoff-to-a-specific-team-via-prompt.md).

## 3. How to Write the Knowledge Base

### How the Knowledge Base is read

When you save, every source is cut into pieces and stored for search. At question time the AI retrieves only the pieces closest in meaning to the customer's message (see [How the AI uses them](#how-the-ai-uses-them)).

* **Text:** pieces are about 1,000 characters long, with some overlap between neighbors. The cut is made at a blank line first, then a line break, then a space. **Headings are not used as cut points**, so a heading can end up in a different piece from the content under it.
* **Tab title:** each Text tab is stored separately, and its title is added to the top of every piece from that tab. Give tabs clear, specific names.
* **Search by meaning:** pieces are matched to the customer's message by similarity of meaning. Use the same words your customers use.

### Choose the right source

| Type        | Best for                                            | Notes                                                                                                                                                                           |
| ----------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Text**    | SOPs, policies, business profile, general info      | Most flexible; use one tab per topic                                                                                                                                            |
| **QnA**     | Frequently repeated questions with standard answers | One question, one answer. Each pair is saved as one entry, and the AI finds it by similarity to the customer's message, not by exact match                                      |
| **Product** | Catalog, prices, weights, variants                  | Manage data in the Product feature so there's a single source of truth                                                                                                          |
| **Website** | Content already on your website                     | Retrain after your site changes                                                                                                                                                 |
| **File**    | Existing documents                                  | **PDF only**, and the text must be selectable (you can highlight it). Scanned images and photos are not read. Line breaks are flattened, so use Text for tables and price lists |

### Rules for Knowledge Text

1. **One tab = one topic.** Example tabs: `Profile & Contact`, `Products & Prices`, `Shipping & Payment`, `Return Policy`, `Active Promos`, `FAQ`.
2. **Separate items with a blank line and keep each item short** (well under about 1,000 characters). Headings and subheadings help you and your team read the text, but the AI may receive a piece without its heading, so don't rely on the heading alone to say what a line is about.
3. **Each piece must stand on its own.** Use the full product or service name on every line instead of pronouns.
   * ❌ `It costs Rp250,000 and comes in 3 colors.`
   * ✅ `AeroRun Running Shoe price: Rp250,000. AeroRun colors: black, white, navy.`
4. **Use key–value lists** for data, not paragraphs, and repeat the item name in each line.

   ```plaintext
   ### Intensive High School Package
   - Intensive High School Package price: Rp1,200,000/month
   - Intensive High School Package schedule: Monday, Wednesday, Friday, 16:00–18:00
   - Intensive High School Package capacity: max 8 students per class
   ```
5. **Avoid wide tables.** If a piece of a table is retrieved without its header row, the AI can misread the columns. Turn tables into per-item lists.
6. **Include synonyms and customer terms.** Example: `Shipping fee (ongkir)`, `Down payment (DP)`, `Installment / credit / cicilan`.
7. **State validity periods** for promos and temporary prices: `Promo valid 1–31 October 2026`. Remove promos that have ended.
8. **Don't let information conflict** across tabs or sources (Text vs Product vs Website).
9. **To send media**, add the URL and say when to send it:

   ```plaintext
   Send this size chart image when the customer asks about sizes or a size chart:
   https://example.com/size-chart.jpg
   ```
10. **Split a reply into several bubbles** by putting `###` **on its own line** between the parts when an answer should be sent in parts (see "Splitting a reply into bubbles" in section 2).

### Rules for QnA

* Write questions the way customers ask them, not in internal jargon. The question text is part of what the AI searches, so a question that sounds like the customer's message is found more easily.
* Keep answers to 1–3 sentences, complete without needing other context. A long entry (over about 1,000 characters) is cut into pieces, and the later pieces lose the question.
* Create separate entries for questions with different intent, even if they look similar.

## 4. Supporting Settings (AI Configuration)

| Setting                 | Recommendation                                                                                                                                                                                                                                                                                                  |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **AI Model**            | **Auto** if unsure. **Advanced** for calculations, image analysis, and tools                                                                                                                                                                                                                                    |
| **AI Creativity Level** | **Consistent** for pricing, policies, healthcare, and finance. **Balanced** for general sales                                                                                                                                                                                                                   |
| **Message Await**       | 10–15 seconds if customers often send several short messages in a row                                                                                                                                                                                                                                           |
| **AI History Limit**    | Raise it if your order or sign-up flow is long                                                                                                                                                                                                                                                                  |
| **AI Context Limit**    | Controls how many Knowledge Base pieces are searched per question (default 50, maximum 60 used). Only about the best 20 reach the AI, so if it still misses information, improve how the Knowledge Base is written instead of only raising this. Don't set it to 0: no Knowledge Base content will be retrieved |

## 5. Test Before You Save

1. Prepare **10–20 test questions** from real customer chats: prices, promos, complaints, off-topic questions, and questions the Knowledge Base can't answer.
2. Test them in the **Preview** panel. Preview uses your latest settings, including unsaved changes.
3. To test Additional Instructions, select a **pipeline** in Preview.
4. Check that the AI answers from the Knowledge Base, doesn't make things up, uses the right tone, and triggers handoffs and labels correctly.
5. Click **Save**. If results get worse, roll back with **Version History**.

{% hint style="success" %}
**Quick checklist before saving**

* [ ] No `[...]` placeholders left
* [ ] No fact written in two different places
* [ ] No behavior rules in the Knowledge Base
* [ ] No two instructions that contradict each other (or the exception is written explicitly)
* [ ] Every promo has a validity period
* [ ] Every field is under its character limit
* [ ] Handoff conditions are set in AI Actions & Routing
  {% endhint %}

## 6. Character Limits

| Field                                   | Limit                                                  |
| --------------------------------------- | ------------------------------------------------------ |
| Welcome Message                         | 5,000 characters                                       |
| Communication Style                     | 5,000 characters                                       |
| Conversation Flow                       | 8,000 characters                                       |
| Rules & Restriction                     | 3,000 characters                                       |
| Additional Instructions                 | Title 100, body 2,000 characters (max 30 instructions) |
| Prompt condition (AI Actions & Routing) | 1,000 characters                                       |

The dashboard enforces these limits as you type. Agents migrated from the old layout may already hold a longer Conversation Flow, because long old prompts are carried over as-is.

## If You Still Use the Old Layout

In the old layout, all instructions live in one **AI Agent Behavior** field. Use the same order so it's easy to migrate later:

```plaintext
### Identity & Communication Style
(same content as Communication Style)

### Rules
(same content as Rules & Restriction)

### Conversation Flow
(same content as Conversation Flow)
```

When you migrate to the new layout, copy each section into its matching field. See [Migrating to the New AI Agent](https://docs.cekat.ai/en/ai-and-platform/ai-agent/new-ai-agent-interface/migrating-to-the-new-ai-agent.md).

## Industry Examples

* [Retail & E-commerce](https://docs.cekat.ai/en/ai-and-platform/ai-agent/writing-ai-behavior-and-knowledge-base/example-retail-and-e-commerce.md)
* [Financial Services](https://docs.cekat.ai/en/ai-and-platform/ai-agent/writing-ai-behavior-and-knowledge-base/example-financial-services.md)
* [Education](https://docs.cekat.ai/en/ai-and-platform/ai-agent/writing-ai-behavior-and-knowledge-base/example-education.md)
* [Property](https://docs.cekat.ai/en/ai-and-platform/ai-agent/writing-ai-behavior-and-knowledge-base/example-property.md)
* [Healthcare](https://docs.cekat.ai/en/ai-and-platform/ai-agent/writing-ai-behavior-and-knowledge-base/example-healthcare.md)
