> 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/org/query-builder.md).

# Getting Started - Using the Query Builder

## Contact Query Metadata Configuration

You can use the "Query Builder" in the MaiAgent service to create query metadata through a graphical interface. Here is an example using contact query metadata:

### Step 1: Navigate to the Contact Section in the MaiAgent Backend

<figure><img src="/files/NYtCWwPWx4bvVPJCjAe6" alt=""><figcaption><p>Contact section entry point</p></figcaption></figure>

### Step 2: Configure the Desired Contact

1. Find the contact you want to configure and click Edit

<figure><img src="/files/8pD9k9m2Ew5RgboNc3lE" alt=""><figcaption><p>Contact edit entry point</p></figcaption></figure>

2\. After clicking, the following screen appears

<figure><img src="/files/v5iHEULGJW8cpEkF6vnb" alt=""><figcaption><p>Query Builder entry point</p></figcaption></figure>

Click the Query Builder to enter the graphical interface

### Step 3: Select the Permissions to Grant

1. Check the knowledge bases you want to open, or selectively check specific documents within a knowledge base

<figure><img src="/files/pvJQs1Lmpo6FM2C4anGo" alt=""><figcaption><p>Select knowledge bases and documents</p></figcaption></figure>

2\. To open documents based on specific tags, click "Show Tag Filters" to open the tag configuration area

<figure><img src="/files/gTVgEtgmgPlZSXJ3ZFc2" alt=""><figcaption><p>Tag filter settings</p></figcaption></figure>

You can select the condition logic here: choose `"OR"` (match any condition) or `"AND"` (match all conditions) as the document access criteria within the opened knowledge bases

## Conversation Settings (Message)

You can also use the right-side menu shown below to select the knowledge permissions to grant:

<figure><img src="/files/EVb125zjwF04sqTHSBxx" alt=""><figcaption><p>Internal conversation: Select available knowledge permissions</p></figcaption></figure>

You can also use "Show Tag Filters" to configure tag filter conditions

{% hint style="info" %}
You can still modify the right-side permissions for knowledge management before sending each different message
{% endhint %}

<figure><img src="/files/QWmNNKQSynH9jQV8cYMz" alt=""><figcaption><p>Available document list</p></figcaption></figure>

<figure><img src="/files/w0jk5fNJChOyzr9V5cEd" alt=""><figcaption><p>Selected document status</p></figcaption></figure>

Currently, three files are available for reference: CV, SOP, and Questionnaire

After unchecking the CV in the next message and sending:

<figure><img src="/files/nU5aKDwPT2AusnEjsjio" alt=""><figcaption><p>Unchecking a document example</p></figcaption></figure>

The Agent can no longer use the CV file, and the reference library no longer shows CV citations:

<figure><img src="/files/TpZoHDIP8suzosVvTlwq" alt=""><figcaption><p>Reference library change: After removing CV</p></figcaption></figure>

You can adjust permissions before sending each message, affecting the content that can be cited in that round of responses.

## Pre-Configuration During Web Chat Initialization

MaiAgent provides the ability to pre-configure query metadata before Web Chat is officially initialized. If you want to restrict conversation content before the contact is identified (e.g., when providing Web Chat service to customers who have not registered a contact account), you can provide query metadata during embedding, and the system will enable the message-level knowledge base document filtering mechanism by default.

For Web Chat configuration, see: [Technical Manual: Getting Started — Using JSON Format](https://docs.maiagent.ai/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces#webchat-chu-shi-hua-she-ding)

{% hint style="info" %}
You can also use JSON format to construct query metadata. See [Technical Manual: Getting Started](https://docs.maiagent.ai/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces)[—](https://docs.maiagent.ai/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces)[Using JSON Format](https://docs.maiagent.ai/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan/json-interfaces)
{% endhint %}


---

# 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/org/query-builder.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.