> 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/org/query-builder.md). # Start Building with 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. The following example shows how to create query metadata for a contact: ### Step 1: Go to the Contact Area in the MaiAgent Admin Console

### Step 2: Configure the Contact 1. Find the contact you want to configure and click Edit

2\. The following screen appears after you click it

Click Query Builder to open the graphical interface. ### Step 3: Select the Permissions to Grant 1. Select the knowledge bases you want to make available. You can also select only specific documents within a knowledge base

2\. To make documents with specific tags available, click "Show Tag Filters" to open the tag configuration area

Here, you can add tags and select the matching logic: within the same tag group, choose "Include all tags (AND)" or "Include any tag (OR)"; between multiple condition groups, choose "Match every group (AND)" or "Match any group (OR)". Older screenshots show AND/OR buttons, but they have the same meaning. These conditions determine which documents in the available knowledge bases can be accessed. The "Affected Files" panel below the builder shows in real time which files can be retrieved. {% hint style="info" %} To apply the same set of tag conditions to an AI assistant by default across all conversation platforms, configure them on the assistant settings page instead. See [Knowledge Base Tag Filtering](/maiagent-user-guide/en/build/agent/label-filter.md). A contact's query metadata takes precedence over the assistant's default conditions. {% endhint %} ## Conversation Settings (Message) You can also use the right-side menu shown below to select the knowledge permissions you want to grant:

Internal conversation: select available knowledge permissions

You can also use "Show Tag Filters" to configure tag-filtering conditions {% hint style="info" %} You can still change the permissions on the right to manage knowledge before sending each message {% endhint %}

Three files—CV, SOP, and Survey—are currently available for reference. Clear the CV selection before sending the next message:

Example of clearing a document selection

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

You can adjust permissions before sending each message, which affects the content that the response can cite for that turn. ## Preconfigure Web Chat During Loading MaiAgent lets you preconfigure query metadata before Web Chat is initialized. To restrict conversation content before a contact is identified (for example, when providing Web Chat to customers without registered contact accounts), provide query metadata when embedding Web Chat. The system will enable message-level knowledge base document filtering by default. For Web Chat settings, 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 construct query metadata in JSON format. 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 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/org/query-builder.md?ask=&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.