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

# Test and measure AI instructions

> Chat with your AI from the instruction editor, read how often each instruction was available, used or led to a handoff, and export instructions to CSV.

Check an instruction before and after it goes live: chat with your AI from the editor, see how often the AI had the instruction and used it, and download your instructions as a spreadsheet for review.

> [!NOTE]
>
> **AI Training → Knowledge** in your [OpenCX dashboard](https://platform.open.cx/ai-instructions). Testing, insights and export need the **AI knowledge base** permission; view access is enough.

## Try an instruction in the Test panel

Click the play button in the editor header (its tooltip reads **Test your instruction**, **Test your AI profile** on **Agent Identity**, or **Test with this article** on a knowledge base article). The **Test panel** opens beside the editor with your web chat widget, connected to your live AI agent. Close it with the same button or the **×** in the panel.

What the test chat does and doesn't do:

* **It answers with what is published.** Drafts and unpublished edits, including a pending schedule change, are not used. Publish an instruction before you test it, and test again after each publish.
* **It is a real web chat session.** It runs on the Web channel, so an instruction restricted to other channels won't apply here. The chat doesn't carry your teammate identity, so it doesn't show how a segment-restricted instruction behaves for a given customer.
* **It reaches your inbox.** Hover an AI reply and click the info button (**View my reasoning process**) to open that session in the inbox, in a new tab, with the AI's reasoning for the reply.

> [!WARNING]
>
> The test chat goes through the same agent your customers reach. Actions the AI calls and workflows that run on incoming messages can run during a test, so test with data that is safe to act on.

## Read an instruction's insights

Open a published instruction and click **Insights** in the editor header (**⌘2**; **⌘1** returns to **Editor**). A draft shows **Publish this instruction to start collecting insights** instead. Knowledge base articles have the same tab.

| Number | What it counts |
| - | - |
| **Available** | Sessions where the instruction was in the AI's context for at least one reply |
| **Used** | Sessions where the AI referenced the instruction in a reply, with the share of **Available** sessions underneath |
| **Handoffs** | Handoffs to a human in which the AI referenced the instruction, counted only in sessions where it was available |

Below the numbers, **Sessions** lists the sessions that used the instruction, newest first. Sessions that ended in a handoff carry a **Handed off** badge, and **View all … in inbox** opens the full list in the inbox.

The date picker above the numbers defaults to the last month. Clear it to see all time. It shares its range with the sidebar sort below, so the badges there and the numbers here always describe the same window.

### Find the instructions that matter most

The sort button next to the sidebar search ranks instructions and knowledge base articles together:

* **Handoffs** ranks by handoffs that referenced the item.
* **Citations** ranks by how many sessions the AI used the item in.

Pick the **Order** and a date range in the same menu, and click **Clear** to return to the folder view. A high handoff count on an instruction is a prompt to read those sessions and rewrite or narrow it.

## Export instructions to CSV

Choose **Export as CSV** from the **…** menu next to **AI instructions** to download every instruction, or from a folder's **…** menu to download that folder and its sub-folders. The dialog shows the file name, how many instructions it holds and the columns; click **Download CSV**.

| Column | Contents |
| - | - |
| `instruction_id` | The instruction's ID |
| `directory` | Its folder name, or `Uncategorized` at the top level |
| `title` | The instruction's title |
| `content` | The instruction's text |
| `is_draft` | `true` for an instruction that was never published or was unpublished |
| `restricted_to_channels` | Allowed channels, separated by `;` (empty means all) |
| `restricted_to_segments` | Allowed segment IDs, separated by `;` (empty means all) |
| `created_at`, `updated_at` | Timestamps |

For an instruction with pending edits, the file holds its published title and text. The file is UTF-8 encoded and opens in Excel, Google Sheets or any text editor.

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| The test chat ignores an instruction you just wrote | The instruction or your latest edit isn't published | Click **Publish**, then ask again in the Test panel |
| The test chat ignores a published instruction | It's restricted to another channel or to segments, or it's outside its active period | Check **Settings** on the instruction; see [Organize and schedule](https://docs.open.cx/ai-instructions/organize-and-schedule.md) |
| Insights shows **No sessions in this range** | No session used the instruction in the selected window | Widen the date range or clear it |
| **Export as CSV** is greyed out | The section or folder has no instructions | Add an instruction or export another folder |

***

## Related Documentation

> [card] [Organize and schedule](https://docs.open.cx/ai-instructions/organize-and-schedule.md)
>
> Folders, limits, schedules and versions.

> [card] [Training scenarios](https://docs.open.cx/ai-instructions/training-scenarios.md)
>
> Write and format an instruction.

> [card] [AI Instructions overview](https://docs.open.cx/ai-instructions/overview.md)
>
> AI profile, instructions and folders.

> [card] [Inbox](https://docs.open.cx/inbox/intro.md)
>
> Review the sessions behind the numbers.


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