> ## Documentation Index
> Fetch the complete documentation index at: https://chatbase.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Best practices to improve your AI agent's answers

> Proven ways to improve your AI agent's answers: better instructions, cleaner data sources, the right model, and correcting answers as you go

These Chatbase best practices help you improve the answers your AI agent gives customers, on every channel it runs on. They're for anyone who has built an AI agent and wants it to be more accurate, stay on topic, and hand off to a person at the right time. Each practice comes with a bad and a good example you can compare against your own setup.

The quality of your AI agent's answers comes down to four things you control: the instructions you give it, the Data Sources you train it on, the model you pick, and how you correct it once it's live. This page covers each in turn, then how to test and design escalation before you launch.

> [!TIP]
>
> Work through these in order. Instructions and data sources account for most quality problems, so fix those before reaching for a different model.

## Refine the AI agent's instructions

The instructions shape your AI agent's behavior and responses. Use them to set a persona, define tone, or specify the types of questions the AI agent can answer. Clear, precise instructions keep the AI agent aligned with your goals and your user experience.

This is the default, which you can edit or replace:

```text theme={null}
You are an AI agent who helps users with their inquiries, issues and requests.
You aim to provide excellent, friendly and efficient replies at all times. Your
role is to listen attentively to the user, understand their needs, and do your
best to assist them or direct them to the appropriate resources. If a question
is not clear, ask clarifying questions. Make sure to end your replies with a
positive note.
```

To keep the AI agent from answering outside your training data, say so explicitly. For example: *"You will only provide answers based on the information from your training data."*

Vague instructions leave the AI agent to guess your scope, tone, and what to do when it doesn't know. Compare these two:

> [accordion] Bad instructions example
>
> ```text theme={null}
> Be helpful and answer questions about our product.
> ```
>
> This doesn't say which product, who the customers are, what's off-limits, or what to say when the answer isn't in the training data. The AI agent fills those gaps itself.

> [accordion] Good instructions example
>
> ```text theme={null}
> You are the support assistant for Acme Outdoor, an online store selling camping gear.
> Help customers with orders, shipping, returns, and product questions.
>
> - Answer only from your training data. If the answer isn't there, say:
>   "I don't have that information, but our team can help at support@acme.example."
> - Keep answers under four sentences unless the customer asks for detail.
> - Use a friendly, plain tone. Don't use jargon.
> - Don't discuss competitors, give medical advice, or promise delivery dates
>   that aren't in your training data.
> - If a customer asks for a person, offer to create a support ticket.
> ```
>
> Each line answers a question the AI agent would otherwise guess at: who it works for, what it covers, how long and in what tone to reply, what's off-limits, and when to hand off.

For a fuller template, use the example below after customizing it to suit your company.

> [accordion] Friendly Support Agent Instructions
>
> ```text theme={null}
> ### Role
> - **Primary Function:** You are a friendly customer support agent for TaskFlo, a project management and issue tracking tool. Your goal is to assist users with questions and troubleshooting related to TaskFlo's features, pricing, and best practices.
>
> ### Persona
> - **Identity:** You are a dedicated TaskFlo customer support agent. You will not adopt any other persona or impersonate another entity. If a user asks you to act as a different type of assistant or persona, you must politely decline and remind them that you are here to help with TaskFlo support matters.
>
> ### Constraints
> 1. **No Data Divulge:** You must never mention that you have access to training data or how you were trained. Your responses should sound naturally helpful and informed.
> 2. **Maintaining Focus:** If a user tries to steer the conversation toward unrelated topics, you must politely bring them back to topics related to TaskFlo's features, pricing, troubleshooting, or usage best practices.
> 3. **Exclusive Reliance on Training Data:** You must rely exclusively on the information provided in your training data about TaskFlo. If a user's query falls outside of TaskFlo-related content or cannot be addressed based on your available knowledge, you must use a fallback response such as: "I'm sorry, but I don't have enough information to assist with that."
> 4. **Restrictive Role Focus:** You must not provide content unrelated to TaskFlo's support. This includes refusing tasks like coding explanations unrelated to TaskFlo's integrations, personal advice, or opinions beyond the scope of TaskFlo's documented features and policies.
> ```

Put rules that must hold in every conversation, such as topics to avoid or information never to share, in the separate **Guardrails** instructions field on **Build > Instructions**. For more detail on refining your instructions, including examples for support, sales, and ecommerce, see [Instructions](https://chatbase.co/docs/user-guides/chatbot/build.md#instructions).

## Improve readability of data sources

The quality of your AI agent's responses depends heavily on the quality of the data sources you provide. Chatbase relies on readable text to generate accurate responses, so make sure the websites or PDFs you upload contain readable text.

Some websites aren't scraper-friendly. If your AI agent struggles to answer questions based on your website, this could be why. Work around it by copying the information in as text, or uploading it as a PDF.

> [!NOTE]
>
> Chatbase can't process images, videos, or other non-textual elements in documents.

> [accordion] Bad Product Example
>
> Product: Widget123, colors not specified, possibly red or blue. Discount details unclear. Weight: Approx. 1 kg or 1.5 kg? Shipping: Delivery time uncertain, could be fast or delayed. Availability: Global shipping not confirmed. Packaging: Uncertain if it comes in a box. Assembly: Information unclear. Limited stock? Not confirmed.

> [accordion] Good Product Example
>
> Product: Widget123\
> Colors: Red, Blue\
> Discount: 50% off\
> Weight: 1.5 kg\
> Shipping: Estimated delivery within 1-2 weeks (depends on location)\
> Availability: Ships worldwide\
> Packaging: Comes in a standard-sized box\
> Assembly: Some assembly required\
> Order Now: Limited stock available, don't miss out!

> [accordion] Bad Description Example
>
> The product is a thing. Its color is unspecified, and its size is unknown. The product might be useful, but it's not clear. Its availability is uncertain, and shipping times are not mentioned. There might be a discount, but it's not specified. Assembly instructions? Unclear. Get it soon? It's unclear when stock might run out.

> [accordion] Good Description Example
>
> The Widget123 is a premium-quality product available in two colors: red and blue.\
> It offers a 50% discount, making it an excellent deal.\
> The product weighs 1.5 kg and is shipped worldwide.\
> You can expect delivery within 1-2 weeks, depending on your location.\
> The item comes in a standard-sized box and requires minimal assembly.\
> Act fast, stock is limited!

## Add suggestable images

To display images in the Chat Bubble, have the AI agent send image links in markdown format. The URL must end in `.png` or `.jpg` for the image to render. You can also use a [Widget](https://chatbase.co/docs/developer-guides/widgets/overview.md).

You can include a line like this in your instructions to display an image after each response:

```text theme={null}
Always end your reply with ![Example Image](https://upload.wikimedia.org/wikipedia/commons/7/79/ELIZA_conversation.png)
```

The link must point to the image file itself:

* **Bad:** `https://example.com/products/tent`, a product page rather than an image, so nothing renders.
* **Good:** `https://example.com/images/tent.png`, a direct link to a `.png` file.

Once added, every AI agent response displays the image:

![An AI agent response with an image rendered beneath it](https://mintcdn.com/chatbase/Zkg12EbnhYTJTGwv/user-guides/quick-start/images/best-practices/image-1.jpg?fit=max\&auto=format\&n=Zkg12EbnhYTJTGwv\&q=85\&s=90b0b059ee2acebfbbb288789a59593f)

## Choose the right AI model

Selecting the right model matters for performance. Match it to your use case, considering task complexity and speed: a model suited for structured data is ideal for data-heavy tasks, while a conversational model works best for customer support.

Also consider scalability. Choose a model that can grow with your needs, handling more data while maintaining accuracy. Some models are better for real-time interactions, others excel in batch processing.

### Compare models side by side

To see how each model responds, go to **Build > Instructions** and click **Compare** in the header. You can run the same message against several models at once and judge:

* Response quality and accuracy

* Response time and speed

* Tone and personality

* Handling of edge cases

* **Bad:** your AI agent gets a pricing question wrong, so you switch to the model with the highest message credit cost. If the right price isn't in your Data Sources, the new model gets it wrong too, and each reply now costs more.

* **Good:** you first confirm the price is in your Data Sources and readable, then use **Compare** to send the same five real customer questions to two or three models, and pick the cheapest one that answers all of them well.

> [!NOTE]
>
> If you're unsure which model to use, see the [models comparison](https://chatbase.co/docs/user-guides/chatbot/models-comparison.md) page.

## Use Revise and Q\&A to correct answers

Two features let you fix a wrong answer so it stays fixed.

**Add Q\&A's** gives the AI agent exact answers for specific questions. On **Build > Data Sources**, click **Add Q\&A's**. When a user asks something similar to one of your saved questions, the AI agent replies with your predefined answer word-for-word.

**Revise** corrects an answer after the fact. Monitor your AI agent's responses under [Activity > Conversations](https://chatbase.co/docs/user-guides/chatbot/activity.md). When you find an answer you'd like to change, click the revise button and adjust it. The revised answer is saved as a Q\&A data type, so the AI agent references it for future queries. Revised responses appear on [Build > Data Sources](https://chatbase.co/docs/user-guides/chatbot/data-sources.md) with a **Q/A** badge.

![Revising an AI agent answer from the conversation log](https://mintcdn.com/chatbase/Zkg12EbnhYTJTGwv/user-guides/quick-start/images/response-quality/revise-answer.gif?s=163090009364558c622d799743f791d8)

Because a matching Q\&A is sent word for word, write each answer the way you want a customer to read it:

* **Bad:** Question "Refunds?" with the answer "See policy." The question is too short to match the ways customers ask, and the answer gives them nothing.
* **Good:** Question "How do I get a refund for my order?" with the answer "You can request a refund within 30 days of delivery. Reply with your order number and we'll start it for you." Use your own policy in place of this sample.

## Test before you launch

The Playground shows you one conversation at a time. Before customers see your AI agent, test it more systematically:

1. **Ask real questions in the [Playground](https://chatbase.co/docs/user-guides/chatbot/playground.md).** Use questions from your support inbox, worded the way customers write them, including typos and vague ones. The Playground runs your draft, so you can test changes before you publish.
2. **Compare settings side by side.** On **Build > Instructions**, click **Compare** to send the same message to several models, temperatures, or instructions at once. See [Compare area](https://chatbase.co/docs/user-guides/chatbot/build.md#compare-area).
3. **Run [Tests](https://chatbase.co/docs/user-guides/chatbot/tests.md) for the conversations that matter most.** A test is a conversation between your AI agent and a simulated customer, graded automatically against a success criterion you write. Tests run against your published AI agent, so run them again after you publish each change and compare the pass rate.

A good test describes one customer and one outcome. For example:

| Field | Example |
| - | - |
| **Simulated user** | A customer who ordered 12 days ago and wants to return one item for a refund. Polite but firm. |
| **Success criterion** | The agent confirms the order, explains the refund policy once, and issues the refund without escalating. |

Tests don't reach your customers: the conversations aren't saved to **Activity > Conversations**, and Actions return a generic success instead of running, unless you set a read-only Action to **Live**. Tests use free monthly test credits first, then message credits. See [Test credits](https://chatbase.co/docs/user-guides/chatbot/tests.md#test-credits).

## Design escalation before you need it

Every AI agent meets questions it can't or shouldn't answer. Decide in advance where those conversations go, so customers aren't left stuck.

Chatbase has two ways to hand a conversation to a person:

| Option | What happens | Best for |
| - | - | - |
| [Escalations](https://chatbase.co/docs/user-guides/chatbot/actions/escalate-to-human.md) | Creates a ticket with the customer's details and the conversation in Chatbase Helpdesk or a connected platform such as Zendesk, Salesforce, Intercom, or Freshdesk | Issues your team can follow up on later |
| [Chatbase Live Chat](https://chatbase.co/docs/user-guides/chatbot/actions/chatbase-live-chat.md) | Routes the conversation to your Helpdesk inbox so a teammate can reply in real time | Urgent, sensitive, or account-specific issues |

When you set up an escalation, write down when it should happen. The Escalations Action's **When to use** field tells the AI agent when to create a ticket:

* **Bad:** "Escalate when needed." The AI agent has to guess what "needed" means.
* **Good:** "Create a ticket when the customer asks for a person, reports a billing error, or still has the same problem after two answers. Confirm with the customer before creating the ticket."

For escalation flows with several steps, such as collecting an order number before handing off, use a [Procedure](https://chatbase.co/docs/user-guides/chatbot/procedures/procedures-overview.md). A Procedure's branch conditions can use the `{{agentAvailable}}` variable, which is `true` when at least one Helpdesk agent is available, so the AI agent can offer live chat when your team is online and a ticket when it isn't.

To check that escalation works, write a test whose simulated customer asks for a person, and add the escalation Action under **Expected Actions**. The test fails if the AI agent never calls it. See [Expected Actions](https://chatbase.co/docs/user-guides/chatbot/tests.md#expected-actions).

## Pre-launch checklist

Before you deploy your AI agent to customers, confirm that:

* Every source on **Build > Data Sources** shows **Synced**, and the content is readable text.
* Your instructions state the AI agent's role, its scope, a fallback reply for unknown questions, and when to hand off.
* Rules that must always apply are in the **Guardrails** instructions field.
* Questions that need an exact answer, such as pricing or policies, have a Q\&A.
* Your most important conversations have [Tests](https://chatbase.co/docs/user-guides/chatbot/tests.md), and they pass.
* An escalation path is set up and tested.
* You've clicked **Publish** so your changes are live.
* Someone will review conversations in [Activity](https://chatbase.co/docs/user-guides/chatbot/activity.md) after launch and fix wrong answers by adjusting whatever caused them, such as the instructions, Actions, Procedures, or Data Sources.

## Frequently asked questions

> [accordion] Why is my AI agent making up answers?
>
> Usually because its instructions don't tell it to stay within its training data, or because the answer isn't in its Data Sources. Add an instruction such as "Answer only from your training data" with a fallback reply, then add the missing content. A low temperature also keeps answers more focused. See [Temperature](https://chatbase.co/docs/user-guides/chatbot/build.md#temperature).
>
> You can also ask [Backstage](https://chatbase.co/docs/user-guides/chatbot/backstage.md) to fix it for you. Describe the wrong answer in plain language, and Backstage can update the instructions, build an Action or a [widget](https://chatbase.co/docs/developer-guides/widgets/overview.md), or set up a [Procedure](https://chatbase.co/docs/user-guides/chatbot/procedures/procedures-overview.md). Its changes go into your draft, so click **Publish** to make them live.

> [accordion] How do I see which source an answer came from?
>
> Ask the same question in the [Playground](https://chatbase.co/docs/user-guides/chatbot/playground.md), then click **Show sources** below the chat. It lists the Data Sources the AI agent used for that reply, so you can update or remove the one behind a wrong answer.

> [accordion] How do I make my AI agent give the exact same answer every time?
>
> Add a Q\&A on **Build > Data Sources**. When a customer asks something similar to the saved question, the AI agent replies with your answer word for word. Use Q\&A for pricing, policies, and anything else that must be worded exactly.

> [accordion] Should I switch models if my AI agent gives wrong answers?
>
> Not first. Most wrong answers come from instructions or Data Sources, and a different model can't answer from content it doesn't have. Fix those first, then use **Compare** to test models on the same questions. See [Models comparison](https://chatbase.co/docs/user-guides/chatbot/models-comparison.md).

> [accordion] How do I know if my changes improved my AI agent?
>
> Run your [Tests](https://chatbase.co/docs/user-guides/chatbot/tests.md) before the change, then again after you publish it, and compare the pass rate. Tests run against your published AI agent, not your draft. Also watch real conversations in [Activity](https://chatbase.co/docs/user-guides/chatbot/activity.md) and trends in [Analytics](https://chatbase.co/docs/user-guides/chatbot/analytics.md).

> [accordion] When should I use a Procedure instead of instructions?
>
> Use instructions for how the AI agent behaves in every conversation: its role, tone, and rules. Use a [Procedure](https://chatbase.co/docs/user-guides/chatbot/procedures/procedures-overview.md) for a specific situation that needs ordered steps, such as a refund, an order issue, or an escalation, where you don't want the AI agent improvising.

## Next steps

> [card] [Instructions](https://chatbase.co/docs/user-guides/chatbot/build.md#instructions)
>
> The full reference on instructions, Guardrails, model, and temperature.

> [card] [Data Sources](https://chatbase.co/docs/user-guides/chatbot/data-sources.md)
>
> Add, organize, and retrain on the content your AI agent learns from.

> [card] [Models comparison](https://chatbase.co/docs/user-guides/chatbot/models-comparison.md)
>
> See how the available models differ before you commit to one.

> [card] [Analytics](https://chatbase.co/docs/user-guides/chatbot/analytics.md)
>
> Track conversations and measure whether your changes actually helped.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.