> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/build/agent/label-filter.md).

# Knowledge Base Label Filtering

Set label filtering conditions once for an AI Assistant so it references only files with matching labels across all conversation platforms

Knowledge Base label filtering lets you configure a default set of label conditions for each AI Assistant. Once configured, the assistant references only files and FAQs that match the conditions when answering questions and ignores all other content. The same rules apply whether users ask questions through Web Chat, LINE, the API, or back-office conversations.

{% hint style="info" %}
When label filtering is not configured, the assistant references all files in every mounted Knowledge Base, exactly as it did before.
{% endhint %}

Previously, limiting an assistant to files with specific labels required passing query metadata with every API call or configuring contacts individually. Now you only need to configure it once on the assistant settings page.

## Use Case <a href="#use-case" id="use-case"></a>

A retail chain's Knowledge Base contains public return and exchange policies, a membership points program, and store-opening and cashier SOPs intended only for employees. The Knowledge Base administrator adds the "Public for Customer Service" label to public documents and the "Internal Operations" label to internal documents. On the customer service assistant's settings page, the administrator then enables "Label Filtering," selects "Public for Customer Service," and saves the settings. From then on, the assistant cites only public documents when customers ask questions through the website's Web Chat or LINE. Even if a customer asks about store-opening procedures, the assistant cannot find the internal SOP and will not disclose internal information. No integration code changes are required.

## Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* The assistant has at least one mounted Knowledge Base (configured under "<mark style="color:blue;">Knowledge Base Settings</mark>" on the assistant settings page).
* Labels have been created in the Knowledge Base and applied to files or FAQs. For instructions on creating and applying labels, see [Document Management: Tags and Metadata](/maiagent-user-guide/en/build/knowledge-base/tags-and-metadata.md).

Available labels come from the Knowledge Bases mounted by this assistant. If the assistant has multiple mounted Knowledge Bases, the same set of conditions applies to all of them.

## Configure Label Filtering <a href="#setup" id="setup"></a>

{% stepper %}
{% step %}
In the left menu, click "<mark style="color:blue;">AI Assistants</mark>," select the assistant you want to configure, and open "<mark style="color:blue;">Settings</mark>."
{% endstep %}

{% step %}
Under "Knowledge and Data," click "<mark style="color:blue;">Label Filtering</mark>." The scope appears in the upper-right corner, showing the Knowledge Bases currently mounted by this assistant.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-aec3fd4687b3caaa423417cf9d2dde10320fda55%2Flabel-filter-initial.png?alt=media" alt="The label filtering section on the AI Assistant settings page before any conditions have been added"><figcaption><p>When no conditions are configured, the assistant references all files</p></figcaption></figure>
{% endstep %}

{% step %}
Under "Condition Group 1," click labels to add them to the condition. You can add multiple labels and choose "<mark style="color:blue;">Include All Labels</mark>" or "<mark style="color:blue;">Include Any Label</mark>" to determine how the group is evaluated.
{% endstep %}

{% step %}
Scroll down to the "<mark style="color:blue;">Affected Files</mark>" panel to confirm which files will be retrieved and which will be excluded. The panel calculates the result in real time based on the conditions currently shown, including unsaved changes.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-5675433977f7d3074d970799450b832974aec8ec%2Flabel-filter-configured.png?alt=media" alt="After adding the Public for Customer Service label, the Affected Files panel shows that 3 of 4 files can be retrieved"><figcaption><p>After a label is added, the plain-language description and Affected Files panel update in real time</p></figcaption></figure>
{% endstep %}

{% step %}
Click "<mark style="color:blue;">Save</mark>" in the lower-right corner. After saving, "Configured" appears next to "Label Filtering" in the left menu.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Label filtering shares the same "Save" button as the assistant's other settings. Remember to save before leaving the page, or the conditions will not take effect.
{% endhint %}

## How to Read Conditions <a href="#how-conditions-work" id="how-conditions-work"></a>

The builder describes conditions in plain language instead of displaying AND/OR. This guide includes the corresponding logic in parentheses for comparison with the previous interface or API documentation. Conditions have two levels: "within a group" and "between groups."

| Level                                                       | Option                   | Meaning                                          |
| ----------------------------------------------------------- | ------------------------ | ------------------------------------------------ |
| Within a group (between labels in the same condition group) | Include All Labels (AND) | A file must have every label listed in the group |
| Within a group                                              | Include Any Label (OR)   | A file only needs one of the labels in the group |
| Between groups (between multiple condition groups)          | Match Every Group (AND)  | A file must satisfy every condition group        |
| Between groups                                              | Match Any Group (OR)     | A file only needs to satisfy one condition group |

For combinations such as "A or B," click "<mark style="color:blue;">Add Condition Group</mark>" to add another group. The "For Multiple Groups" selector appears only when there are two or more groups.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-c9ac268cbac87e553237e80781808e2b70aeac98%2Flabel-filter-groups.png?alt=media" alt="Two condition groups joined with Match Any Group"><figcaption><p>Two condition groups: files labeled "Public for Customer Service" or files labeled "Internal Operations"</p></figcaption></figure>

At the bottom of the builder, a sentence describes the current conditions, such as: "The assistant will only reference files labeled 'Public for Customer Service' or 'Internal Operations.'" If you are unsure whether the conditions are correct, refer to this sentence and the "Affected Files" panel.

{% hint style="info" %}
The "Affected Files" panel counts files that have been loaded on the page. If the Knowledge Base contains many files, the panel displays "Only the first N loaded files are counted." Actual retrieval still applies the conditions to all files.
{% endhint %}

## Scope and Priority <a href="#scope-and-priority" id="scope-and-priority"></a>

The assistant's label filtering acts as a "default" for all conversations handled through that assistant, including Web Chat, conversation platforms such as LINE, API integrations, and back-office conversations.

If query metadata has already been specified at another level for a conversation, that level takes precedence and the assistant default is not used. The priority from highest to lowest is:

1. Query metadata passed with an individual message (for example, in an API call or Web Chat embed)
2. Conversation-level query metadata
3. Contact query metadata
4. Assistant label filtering (configured on this page)

In other words, existing contact or API settings are unaffected. The assistant's default conditions apply only when none of the first three levels specifies query metadata. For configuration instructions at each level, see [Knowledge Management Permissions: Query Metadata](/maiagent-user-guide/en/org/querymetadata.md) and [Getting Started with the Query Builder](/maiagent-user-guide/en/org/query-builder.md).

{% hint style="info" %}
The Knowledge Base "Search Test" is a tool for checking retrieval quality and does not apply the assistant's label filtering.
{% endhint %}

## Invalid Labels <a href="#invalid-labels" id="invalid-labels"></a>

If a label referenced by a condition has been renamed or deleted, or if its Knowledge Base has been unmounted from the assistant, reopening the settings page displays an invalid-label warning listing the affected labels. Click "<mark style="color:blue;">Remove Invalid Labels</mark>" to remove them all at once, or select other labels and save.

{% hint style="warning" %}
Invalid labels never match any files during retrieval, and they do not broaden retrieval to include everything. If the assistant suddenly cannot answer using Knowledge Base content, first check whether label filtering contains invalid labels.
{% endhint %}

## Clear Settings <a href="#clear" id="clear"></a>

Click "<mark style="color:blue;">Clear All Conditions</mark>" in the upper-right corner of the builder and save. The assistant will return to referencing all files.

If the Knowledge Bases mounted by the assistant do not contain any labels, this page displays "The mounted Knowledge Bases do not have any labels." Add labels to files in the Knowledge Base first.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-643602b6c5278d200b0704ca967d0ed7f678661f%2Flabel-filter-empty.png?alt=media" alt="Message displayed when the mounted Knowledge Bases do not contain any labels"><figcaption><p>Message displayed when the Knowledge Base does not contain any labels</p></figcaption></figure>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/build/agent/label-filter.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.