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

# Instruct AI Agent

> Improve your agent by choosing the right lever: knowledge, behavior, or system access

Once you've found something to improve with the [Agent Optimization Guide](/guides/optimization), every fix falls into one of three levers. Identify the lever, implement the change, then validate it with [Testing](/guides/testing).

## The three levers

| Lever                                       | When to pull                                                                                         | What to change                                                                                                                                    |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[Give knowledge](#give-knowledge)**       | The agent doesn't know the answer, or gives outdated or wrong information                            | Add or fix [Snippets](/concepts/snippets), [Data Providers](https://platform.botbrains.io/~/data-providers), or [Search Tables](/concepts/tables) |
| **[Instruct behavior](#instruct-behavior)** | The agent has the right information but applies it wrong (wrong tone, skips steps, doesn't escalate) | Add or refine [Guidance](/concepts/guidance) or [Procedures](/concepts/procedures)                                                                |
| **[Add system access](#add-integrations)**  | The agent needs to read or write data in an external system                                          | Connect a [Toolbox, MCP Server, or Unitool](/concepts/actions#connecting-to-third-party-systems)                                                  |

Every conversation problem maps to one of these. A wrong answer is a knowledge problem. A correct answer in the wrong tone is a behavior problem. "I can't look up your order" is a system access problem.

## Give knowledge

When the agent says "I don't have information about that" or gives an outdated answer, it needs better knowledge.

**Wrong answers.** Find them by filtering for low ratings with feedback like "wrong" or "incorrect." Click the AI message and open the [Improve Answer](/guides/improve-answers) sidebar to see which sources the agent used. Fix the root cause: update the outdated document, remove conflicting sources, or clarify the passage in [Data Providers](https://platform.botbrains.io/~/data-providers) or [Snippets](https://platform.botbrains.io/~/snippets).

**Missing answers.** The fastest fix is a [Snippet](/concepts/snippets): click the AI message, select **Add Snippet**, and write the ideal answer. For recurring topic clusters, add a full documentation source (webpage crawl, PDF, or [Search Table](/concepts/tables)). [Suggestions](/concepts/suggestions) with issue type "Missing content" point you directly to the biggest knowledge gaps. Before product launches or seasonal events, add documentation proactively.

## Instruct behavior

When the agent has the right information but responds with the wrong tone, skips steps, or answers when it should escalate, it needs better instructions. You have two tools, and most agents use both.

**[Guidance](/concepts/guidance)** shapes how the agent behaves in specific situations. Scope each rule to the right conversations with audience conditions, and keep instructions concrete: "Always include a tracking link when answering shipping questions" works better than "Be helpful." See [Guidance](/concepts/guidance) for how to write effective rules.

**[Procedures](/concepts/procedures)** guide the agent through multi-step workflows where the conversation must follow a specific sequence, such as collecting order details before processing a return.

### Choosing guidance or procedures

|                 | Guidance                      | Procedures                                    |
| --------------- | ----------------------------- | --------------------------------------------- |
| **Purpose**     | Shape behavior and tone       | Execute multi-step processes                  |
| **Structure**   | Free-form instructions        | Ordered steps with control flow               |
| **Logic**       | No branching                  | If/else conditions, code checks               |
| **Enforcement** | Agent interprets on its own   | Deterministic, agent follows the defined path |
| **Use cases**   | Tone, policies, general rules | Refunds, returns, verifications, escalations  |

Start with guidance. Add a procedure when steps must happen in a fixed order and eligibility checks must be deterministic, for example a refund that verifies the order and the return window before it runs.

## Add integrations

When the agent needs to look up customer-specific data or act in external systems, it needs system access. [Suggestions](/concepts/suggestions) with issue types "Can't read customer data" or "Can't write customer data" highlight these gaps automatically. See [Actions](/concepts/actions) for the full overview.

**Reading data.** The agent might need order status from your database, account details from your CRM, or inventory levels from your e-commerce platform. Choose your integration based on availability:

1. **[Pre-built Toolboxes or MCP Servers](https://platform.botbrains.io/~/profiles?tab=actions)** if botBrains offers one for your system.
2. **[Unitools](/concepts/unitools)** to write custom code that queries your API or database.
3. **[Search Tables](/concepts/tables)** if the data seldom changes and you can upload it.

**Taking actions.** The agent might need to create tickets, update records, trigger workflows, or process refunds. The same priority applies: pre-built integrations first, Unitools as fallback.

After adding system access, enable the tools on the relevant [guidance rules](/concepts/guidance) so the agent knows when to use them.

## Implement and validate

Once you've applied a lever, [build and deploy a version](/concepts/versioning) to make the change live. Confirm it first with [Testing](/guides/testing): re-run a failing case with View Alternative, or lock the behavior in with a [simulation](/guides/simulations) so it stays fixed.