> 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 Tag Filtering

Configure a label filter once in the Agent settings so the Agent only references files with matching labels across all conversation platforms

Knowledge base label filtering lets you configure a default set of label conditions for each Agent. Once configured, the Agent only references files and FAQs that meet these conditions when answering questions, excluding all other content. The same rules apply whether users ask questions through Web Chat, LINE, the API, or conversations in the admin interface.

{% hint style="info" %}
When no label filter is configured, the Agent references all files in all attached knowledge bases, exactly as before.
{% endhint %}

Previously, restricting an Agent to files with certain labels required passing query metadata in every API call or configuring each contact individually. Now, you only need to configure the filter once on the Agent 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 an opening and checkout SOP intended only for store staff. The knowledge base administrator labels public documents “Public for Customer Service” and internal documents “Internal Operations.” Then, on the customer service assistant's settings page, they enable “Label Filtering,” select “Public for Customer Service,” and save. From then on, whether customers ask questions through the website's Web Chat or LINE, the Agent only cites public documents. Even if a customer asks about store opening procedures, the Agent cannot find the internal SOP and will not disclose internal information. No engineer needs to change any integration code.

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

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

Available labels come from the knowledge bases attached to this Agent. If the Agent has multiple knowledge bases attached, the same set of conditions applies to all of them.

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

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

{% step %}
In the “Knowledge and Data” group, click “<mark style="color:blue;">Label Filtering</mark>.” The top-right corner shows the scope: the knowledge bases currently attached to this Agent.

<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="Label filtering section on the Agent settings page, with no conditions added yet"><figcaption><p>When no conditions are configured, the Agent references all files</p></figcaption></figure>
{% endstep %}

{% step %}
Under “Condition Group 1,” click a label below to add it to the conditions. 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 this group is evaluated.
{% endstep %}

{% step %}
Scroll down to the “<mark style="color:blue;">Affected Files</mark>” panel to check which files will be retrieved and which will be excluded. The panel updates 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 / 4 files can be retrieved"><figcaption><p>After adding a label, the plain-language explanation and Affected Files panel update in real time</p></figcaption></figure>
{% endstep %}

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

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

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

The builder describes conditions in plain language without displaying AND/OR. This guide includes the corresponding logic in parentheses to help you compare it with older screens 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 this group |
| Within a group                                              | Include Any Label (OR)   | A file only needs one of the labels in this 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  |

When you need combinations such as “A or B,” click “<mark style="color:blue;">Add a Condition Group</mark>” to add another group. The between-group selector under “When There Are Multiple Groups” only appears when there are at least two 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 combined with “Match Any Group”"><figcaption><p>Two condition groups: files with “Public for Customer Service,” or files with “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 with ‘Public for Customer Service,’ or files with ‘Internal Operations.’” If you are unsure whether the conditions are correct, use this sentence and the “Affected Files” panel to check.

{% hint style="info" %}
The “Affected Files” panel counts files that have been loaded on the screen. When a knowledge base has many files, the panel indicates “Only the first N loaded files are counted.” The filter still applies to all files during actual retrieval.
{% endhint %}

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

The Agent's label filter is a default that applies to all conversations through this Agent: conversation platforms such as Web Chat and LINE, API integrations, and conversations in the admin interface.

If query metadata has already been specified at another level for a conversation, that level takes precedence and the Agent 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 when embedding Web Chat)
2. Conversation-level query metadata
3. The contact's query metadata
4. The Agent's label filter (configured on this page)

Existing contact or API settings are therefore unaffected. The Agent's default conditions apply only when none of the first three levels specifies query metadata. For details on configuring each level, see [Knowledge Management Permissions: Query Metadata](/maiagent-user-guide/en/org/querymetadata.md) and [Start Building—Using the Query Builder](/maiagent-user-guide/en/org/querymetadata/query-builder.md).

{% hint style="info" %}
The knowledge base's “Search Test” is a tool for checking retrieval quality and does not apply the Agent's label filter.
{% endhint %}

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

If a label referenced in the conditions has been renamed or deleted, or its knowledge base has been detached from the Agent, reopening the settings page displays an invalid-label warning listing the affected labels. Click “<mark style="color:blue;">Remove Invalid Labels</mark>” to clear them all at once, or select other labels and save.

{% hint style="warning" %}
Invalid labels do not match any files during retrieval and do not expand retrieval to all files. If the Agent suddenly cannot answer questions using knowledge base content, first check the label filter for invalid labels.
{% endhint %}

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

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

If the knowledge bases attached to the Agent do not have any labels yet, this page displays “The attached knowledge bases do not have any labels yet.” Go to the knowledge base and add labels to files 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 shown when the attached knowledge bases do not have any labels yet"><figcaption><p>Message shown when the knowledge bases have no 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.