> 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/maiagent-user-guide-en/km/tags-and-metadata.md).

# Document Management: Tags & Metadata

Since a Knowledge Base may contain a large number of documents or FAQs to manage, MaiAgent provides tag management and metadata management features, allowing you to categorize and organize large volumes of documents and FAQs.

## Tag Management <a href="#tag-management" id="tag-management"></a>

When your Knowledge Base contains a large amount of data, the tagging system helps you quickly organize documents, FAQ attributes, or control reference material permissions. For example:

```
Product Data Knowledge Base (categorized by product information)
|-- #Tent 
|-- #4-Person Tent 
|-- #3-Season Tent 
|-- #SnowPeak
```

```
Tutorial Content Knowledge Base (categorized by permission level)
|-- #Non-Member
|-- #Regular Member 
|-- #VIP
```

### Add Tag <a href="#add-tag" id="add-tag"></a>

1. Click the Add button

<figure><img src="/files/96jHWzC1ziD4FmNNk0C2" alt=""><figcaption></figcaption></figure>

2. Enter the tag name

<figure><img src="/files/woHI1oxVj4toHs0HhBQD" alt=""><figcaption></figcaption></figure>

3. After clicking Add, the tag you just entered will be displayed as follows, including ID, name, etc.

{% hint style="info" %}
The ID can be used for granting document access permissions. For details, see [Technical Manual — Query Metadata Control Items](https://docs.maiagent.ai/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces#querymetadata-kong-zhi-xiang-mu-shuo-ming)
{% endhint %}

<figure><img src="/files/CyN7MzEnYlPwXFF3uH5q" alt=""><figcaption></figcaption></figure>

### Add Tags to Documents <a href="#tag-document" id="tag-document"></a>

After adding tags, go to the document page.

1. Click Edit File Information

<figure><img src="/files/NN5WwKS3wU7U6Y5i1olg" alt=""><figcaption></figcaption></figure>

2. Select tags

Add corresponding tags based on the document's requirements (you can select multiple tags).

<figure><img src="/files/2yJWfWn8k0Tu3bWyVDje" alt=""><figcaption></figcaption></figure>

The added tags will then be displayed next to the corresponding document:

<figure><img src="/files/HAGGRotYiWJq1fxqAY4A" alt=""><figcaption></figcaption></figure>

### Add Tags to FAQs <a href="#tag-faq" id="tag-faq"></a>

If you want to add hierarchical categorization or tag management for FAQs, you can:

1. Go to the FAQ management interface within the Knowledge Base, select the FAQ you want to edit, then click the Edit button

<figure><img src="/files/pXhaMO2cAv4wV0NIslrZ" alt=""><figcaption></figcaption></figure>

2. Select the tags to add, then click "<mark style="color:blue;">Confirm</mark>"

<div><figure><img src="/files/ro2GNPJ02056siHVCSau" alt=""><figcaption></figcaption></figure> <figure><img src="/files/UzgZsTfFfGRUJ0Amsx88" alt=""><figcaption></figcaption></figure></div>

The added tags will appear in the FAQ field.

<figure><img src="/files/Q9FUCJEkHRu0TJ0uaZn1" alt=""><figcaption></figcaption></figure>

***

### Tag Access Control <a href="#tag-access-control" id="tag-access-control"></a>

You can control what different users see based on different tags. For example, VIP customers can view more advanced product tutorials, while non-members can only see general tutorials.

{% hint style="info" %}
Filtering can be applied to both FAQs and documents.
{% endhint %}

#### AND Filter <a href="#and-filter" id="and-filter"></a>

The AND filter opens content that matches all tag conditions simultaneously.

For example: If a conversation is a tutorial-related conversation with a non-member, you can use tag filtering to only open documents that simultaneously match the "<mark style="color:blue;">Non-Member</mark>" and "<mark style="color:blue;">Tutorial</mark>" tags for the AI Assistant to use.

As shown: After filtering, the AI Assistant can only use the beginner camping document, avoiding disclosure of irrelevant information in non-member conversations.

<figure><img src="/files/du7X1gf9Z3h3h728nyhn" alt=""><figcaption></figcaption></figure>

#### OR Filter <a href="#or-filter" id="or-filter"></a>

For conversations with members, you can use the OR filter to allow documents matching either Regular Member or Non-Member to be available for the AI Assistant to reference:

<figure><img src="/files/mpXqAVbmoq0D6v9k8Syd" alt=""><figcaption></figcaption></figure>

Members can see more document content than non-members, achieving tiered access control.

{% hint style="info" %}
You can switch between filtering mechanisms by clicking "AND" or "OR" in the tag filter.
{% endhint %}

<figure><img src="/files/wL6TqrTA5ZCUstZAu3I4" alt=""><figcaption></figcaption></figure>

> For filtering results, refer to: [Internal Q\&A Features](https://github.com/Playma-Co-Ltd/maiagent-user-guide-gitbook/tree/main/en/release/explain.md)

## Document Metadata Management <a href="#document-metadata-management" id="document-metadata-management"></a>

### **What Is Metadata?** <a href="#what-is-metadata" id="what-is-metadata"></a>

Metadata is like a document's "ID card," recording detailed information about the document and helping the system better manage and use these documents.

**Example: Beginner Camping.pdf**

```
Metadata settings:
├── Document version: v2.1
├── Created date: 2024-03-15
├── Last updated: 2024-11-20
├── Next review: 2025-05-20
├── Updated by department: Marketing
└── Version status: Reviewed and approved for release
```

### Why Use Metadata? <a href="#why-use-metadata" id="why-use-metadata"></a>

When data is complex and voluminous, using metadata helps you maintain data quality more conveniently and quickly by:

**Improving Management Efficiency**

* Quickly identify document status and version information
* Stay more organized when managing large volumes of documents in bulk
* Reduce time spent on manual searching and verification

**Ensuring Content Quality**

* Use the latest document versions
* Track document update history and version status
* Ensure the AI Assistant uses the latest and reviewed content
* Set periodic review reminders to maintain data quality

### Add Metadata to Documents <a href="#add-metadata-to-document" id="add-metadata-to-document"></a>

1. Go to the document page and click Edit File Information:

<figure><img src="/files/NN5WwKS3wU7U6Y5i1olg" alt=""><figcaption></figcaption></figure>

2. Switch to the Metadata tab and enter the metadata mappings

> MaiAgent uses key-value pairs to store and retrieve metadata

<div><figure><img src="/files/xOcCzc8kOxkHsiAPw3Xw" alt=""><figcaption></figcaption></figure> <figure><img src="/files/ZOM2xoPGW53M8AgLg42j" alt=""><figcaption></figcaption></figure></div>

After entering, click the "<mark style="color:blue;">Add Metadata</mark>" button to add the key-value pair you just entered (you can add multiple metadata entries at once).

<figure><img src="/files/UGZll2NXjejvPxOWeIMr" alt=""><figcaption></figcaption></figure>

After adding, you can see the metadata you just added appearing in the field.

### Add Metadata to FAQs <a href="#add-metadata-to-faq" id="add-metadata-to-faq"></a>

1. Go to the FAQ management interface within the Knowledge Base, select the FAQ you want to edit, then click the Edit button
2. Switch to the Metadata page, enter the values, then click Add Metadata

After entering all values, click "Confirm"

<figure><img src="/files/KQYw6c9nv5fDVemNSGFb" alt=""><figcaption></figcaption></figure>

The added metadata will appear in the FAQ list.

<figure><img src="/files/5z5zjoq9WmmkZMTLYqVq" alt=""><figcaption></figcaption></figure>

### Custom URL Mapping <a href="#custom-url-mapping" id="custom-url-mapping"></a>

`url` is a reserved word in the metadata system. If you set `url: https://...your-specified-URL`, the URL you set will override the original file location when viewing citation snippets in conversations, opening your specified URL instead.

**Example Scenario: Brand Spring Promotional Campaign**

**Original Settings:**

```yaml
title: "2025 Spring Sale Event Details"
content: "This event includes 20% off storewide, bonus gifts for minimum purchase amounts, and many more offers..."
url: https://www.yourstore.com/spring-sale-2025
```

**Usage Effect:** When a user asks "What offers are available in the spring sale?" in a conversation:

* The AI will cite this knowledge snippet to answer the question
* When the user clicks the citation source, it will not open the internal file location
* Instead, it will navigate directly to `https://www.yourstore.com/spring-sale-2025`, the official campaign page
* The user can immediately see the latest event details, purchase buttons, countdown timers, and other dynamic content

**Practical Scenarios:**

* **Website Announcements**: `url: https://www.company.com/announcements/system-maintenance`
* **Product Spec Pages**: `url: https://www.product.com/specs/model-x1`
* **Customer Service Policies**: `url: https://support.company.com/return-policy`
* **Event Registration**: `url: https://events.company.com/register/webinar-2025`

The benefit of this setup is making AI responses more actionable -- not only providing information but also guiding users directly to relevant pages to take action, improving user experience and conversion rates.

***

#### Before Setting url <a href="#before-url-setting" id="before-url-setting"></a>

As shown below, before setting the url value, clicking a citation node and clicking any node (e.g., Beginner Camping.pdf) allows you to view the original document (you can configure whether to allow users to download original document files in the conversation platform):

{% hint style="info" %}
[Conversation Platform - Allow Citation Document Download Settings](https://github.com/Playma-Co-Ltd/maiagent-user-guide-gitbook/tree/main/en/release/web-chat-introduction/website.md#id-3.-gong-neng-she-ding)
{% endhint %}

<div><figure><img src="/files/A5I05ju4f9qdzGNASkob" alt=""><figcaption><p>View citation nodes</p></figcaption></figure> <figure><img src="/files/zO1cVtwlew7y9bLO0GS0" alt=""><figcaption><p>View original file location</p></figcaption></figure></div>

#### After Setting url (Using Google as an Example) <a href="#after-url-setting" id="after-url-setting"></a>

<figure><img src="/files/HhSWUgrIXHM3sVKtVrfc" alt=""><figcaption></figcaption></figure>

Click the cited node file (Camping Precautions.txt) again. Instead of showing a document preview, it will open the Google homepage:

<div><figure><img src="/files/UWzwpQtetJoDDE1boVvm" alt=""><figcaption></figcaption></figure> <figure><img src="/files/1kDRrOM36hpv9B3oD9aG" alt=""><figcaption></figcaption></figure></div>

After setting the `url` field in metadata, when users see the AI Assistant citing that document in a conversation, they can click directly to navigate to the link you set for more complete information.


---

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/km/tags-and-metadata.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.