> 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/setup.md).

# Create an Agent

Steps to create an Agent and the purpose of each tab on the Agent settings page

This page walks you through creating an Agent from scratch. Before you begin, review the settings map below to learn what each tab controls and where to find details.

## Settings map <a href="#settings-map" id="settings-map"></a>

The settings window that opens when you create an Agent and the “<mark style="color:blue;">Settings</mark>” tab you open later from the Agent list use the same navigation on the left: 5 groups with 12 tabs in total.

| Group                                                   | Tab                                                      | What it controls                                                                                                                                                                                                                                                                                                | Details                                                                                                                                                                                                                                                                              |
| ------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <mark style="color:blue;">Basic</mark>                  | <mark style="color:blue;">Basic Settings</mark>          | Name, <mark style="color:blue;">LLM Model</mark>, and <mark style="color:blue;">Fallback Model Group</mark>; <mark style="color:blue;">Thinking Effort</mark> is also available when supported by the model                                                                                                     | [Choose a model](#language-model-settings), [Model access](/maiagent-user-guide/en/org/model-access.md)                                                                                                                                                                              |
| <mark style="color:blue;">Basic</mark>                  | <mark style="color:blue;">Answer Mode Settings</mark>    | Answer mode, <mark style="color:blue;">Role Instructions</mark>, <mark style="color:blue;">Enable Inline Citations</mark>, and reply templates for Template and Hybrid modes; <mark style="color:blue;">Voice Assistant Settings</mark> also appear here when voice assistants are enabled for the organization | [Answer modes](#select-answer-mode-to-build-prompt), [Voice assistants](/maiagent-user-guide/en/build/agent/voice-agent.md)                                                                                                                                                          |
| <mark style="color:blue;">Knowledge & Data</mark>       | <mark style="color:blue;">Knowledge Base Settings</mark> | Select the knowledge bases the Agent references when answering                                                                                                                                                                                                                                                  | [Configure knowledge bases](#rag-settings), [Knowledge bases](/maiagent-user-guide/en/build/knowledge-base.md)                                                                                                                                                                       |
| <mark style="color:blue;">Knowledge & Data</mark>       | <mark style="color:blue;">Tag Filtering</mark>           | Restrict the Agent to files that match the tag conditions                                                                                                                                                                                                                                                       | [Knowledge base tag filtering](/maiagent-user-guide/en/build/agent/label-filter.md)                                                                                                                                                                                                  |
| <mark style="color:blue;">Knowledge & Data</mark>       | <mark style="color:blue;">Database Settings</mark>       | Link databases to query using Text to SQL (Agent mode only)                                                                                                                                                                                                                                                     | [Create and configure databases](/maiagent-user-guide/en/build/database/create-database.md)                                                                                                                                                                                          |
| <mark style="color:blue;">Capabilities</mark>           | <mark style="color:blue;">Tools</mark>                   | Select the tools the Agent can call (Agent mode only)                                                                                                                                                                                                                                                           | [Configure tools for an Agent](/maiagent-user-guide/en/build/tools/configure_tools.md)                                                                                                                                                                                               |
| <mark style="color:blue;">Capabilities</mark>           | <mark style="color:blue;">MaiGPT Connectors</mark>       | Bind connectors so they are available in all conversations with this Agent (Agent mode only)                                                                                                                                                                                                                    | [Manage connectors (administrators)](/maiagent-user-guide/en/work/maigpt/connectors/connectors-admin.md)                                                                                                                                                                             |
| <mark style="color:blue;">Capabilities</mark>           | <mark style="color:blue;">Skill Settings</mark>          | Attach skills for the Agent to use                                                                                                                                                                                                                                                                              | [Skills](/maiagent-user-guide/en/build/skills.md)                                                                                                                                                                                                                                    |
| <mark style="color:blue;">Capabilities</mark>           | <mark style="color:blue;">Hook</mark>                    | Apply Hooks that run when a user message is received, after an AI response is generated, or after a conversation is completed (visible only with Hook access permissions)                                                                                                                                       | [Add and configure Hooks](/maiagent-user-guide/en/build/hook/setup.md)                                                                                                                                                                                                               |
| <mark style="color:blue;">Interface & Experience</mark> | <mark style="color:blue;">Agent UI</mark>                | Select interactive components the Agent can include in replies (Agent mode only)                                                                                                                                                                                                                                | [Agent UI](/maiagent-user-guide/en/build/tools/agent-ui.md)                                                                                                                                                                                                                          |
| <mark style="color:blue;">Management & Advanced</mark>  | <mark style="color:blue;">Permission Settings</mark>     | Specify which roles can use this Agent                                                                                                                                                                                                                                                                          | [Preassign Agent permissions](#pre-assign-agent-permissions)                                                                                                                                                                                                                         |
| <mark style="color:blue;">Management & Advanced</mark>  | <mark style="color:blue;">Advanced Settings</mark>       | Maximum retrieval chunks, output length controls, Agent workflow settings, conversation memory settings (including Embedding and Reranker models), persistent memory, automatic evaluation, and more; the defaults are usually sufficient                                                                       | [Reply length and Agent execution limits](/maiagent-user-guide/en/build/agent/custom-max-tokens.md), [Cross-conversation retrieval](/maiagent-user-guide/en/build/agent/cross-conversation-search.md), [Persistent memory](/maiagent-user-guide/en/build/agent/persistent-memory.md) |

{% hint style="info" %}
Tabs marked “Agent mode only” remain accessible in other answer modes, but only show a notice and a <mark style="color:blue;">Go to Answer Mode Settings</mark> button. Switch to Agent mode to configure them.
{% endhint %}

The creation window has an additional <mark style="color:blue;">Channel Activation</mark> item in the <mark style="color:blue;">Basic</mark> group. It determines whether the Web Widget and API Integration are enabled as soon as the new Agent is created. This item only appears during creation and is unavailable when editing an existing Agent. See [Configure channel activation](#channel-activation).

### Tabs at the top of the Agent page <a href="#page-tabs" id="page-tabs"></a>

After creating an Agent, open it from the Agent list to see these tabs at the top of the page:

| Tab                                              | What it controls                                                                                                                                                                                                   | Details                                                                      |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| <mark style="color:blue;">Settings</mark>        | The 12 tabs in the settings map above                                                                                                                                                                              | This page                                                                    |
| <mark style="color:blue;">Usage Analytics</mark> | <mark style="color:blue;">Usage Statistics</mark> for this Agent; <mark style="color:blue;">Monitoring Metrics</mark> are also available with <mark style="color:blue;">AI Assistant Monitoring Permissions</mark> | [Agent usage analytics](/maiagent-user-guide/en/build/agent/usage.md)        |
| <mark style="color:blue;">Channels</mark>        | Channels connected to this Agent (website, LINE, etc.)                                                                                                                                                             | [Connect channels](/maiagent-user-guide/en/build/choose-channel.md)          |
| <mark style="color:blue;">API Integration</mark> | Instructions for calling this Agent programmatically                                                                                                                                                               | [Developer tools](/maiagent-user-guide/en/org/developer.md#integration-docs) |
| <mark style="color:blue;">Webhook</mark>         | Push this Agent's replies to your own system                                                                                                                                                                       | [Webhook](/maiagent-user-guide/en/build/conversation-settings/webhook.md)    |

## 1. **Create an Agent** <a href="#create-ai-agent" id="create-ai-agent"></a>

Go to “<mark style="color:blue;">AI Assistants</mark>” under “<mark style="color:blue;">AI Features</mark>” in the left sidebar, then click “<mark style="color:blue;">Create AI Assistant</mark>” in the upper right.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-87b5a1243ec25ab81a5f9c010df5c95917736f43%2Fagent-builder-list.png?alt=media" alt="Agent list showing columns such as name, large language model, and answer mode, with a Create Agent button in the upper right and action buttons on the right of each row"><figcaption><p>The “Create AI Assistant” button in the upper right of the Agent list</p></figcaption></figure>

### List filters and columns <a href="#agent-list-filters-and-columns" id="agent-list-filters-and-columns"></a>

Above the list, search by Agent name or ID and narrow the results using the “<mark style="color:blue;">All Large Language Models</mark>”, “<mark style="color:blue;">All Answer Modes</mark>”, and “<mark style="color:blue;">All Creators</mark>” dropdowns. After selecting a creator, the list only shows Agents created by that member that you have permission to view. Multiple filters apply together.

For example, a manager looking for an Agent created by a colleague can select that member under “<mark style="color:blue;">All Creators</mark>”, then narrow the results by name or model. Afterward, click “<mark style="color:blue;">Reset Filters</mark>” to clear the conditions. If no Agents match, the list displays “<mark style="color:blue;">No matching AI assistants found</mark>”, where you can also reset the filters.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-025b99de1b70033b5eec6c0f38f334f584ad5fb7%2Fagent-builder-creator-filter.png?alt=media" alt="AI assistant list filters: filter by name or ID, large language model, answer mode, and creator, and click Reset Filters to clear the conditions"><figcaption><p>Combine “All Creators” with other filters, and click “Reset Filters” to clear them</p></figcaption></figure>

Each row displays:

| Column                                                | Description                                                                                                                                                                                    |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">ID</mark>                   | The Agent's identifier, used for API integration and issue reporting                                                                                                                           |
| <mark style="color:blue;">Name</mark>                 | The name entered in Basic Settings                                                                                                                                                             |
| <mark style="color:blue;">Large Language Model</mark> | The LLM model selected in Basic Settings                                                                                                                                                       |
| <mark style="color:blue;">Answer Mode</mark>          | RAG Q\&A, Agent mode, Template, or Hybrid                                                                                                                                                      |
| <mark style="color:blue;">Knowledge Bases</mark>      | Linked knowledge bases                                                                                                                                                                         |
| <mark style="color:blue;">Skills</mark>               | Attached skills                                                                                                                                                                                |
| <mark style="color:blue;">Last Updated</mark>         | The most recent time the settings were saved                                                                                                                                                   |
| <mark style="color:blue;">Actions</mark>              | <mark style="color:blue;">Edit</mark>, <mark style="color:blue;">Duplicate</mark>, and <mark style="color:blue;">Delete</mark>; see [Duplicate and delete Agents](#duplicate-and-delete-agent) |

The list does not support multiple selection or batch actions. To adjust multiple Agents, open their settings individually.

## **2. Name your Agent** <a href="#name-your-ai-agent" id="name-your-ai-agent"></a>

Click “<mark style="color:blue;">Basic Settings</mark>” in the left navigation of the creation window and enter the Agent's name in the “<mark style="color:blue;">Name</mark>” field. Name it after its main task, for example, XX AI Customer Support, XX Regulatory Lookup Assistant, or XX Project Assistant.

One account can create multiple Agents (quantity limits depend on your purchased plan). Agent names must be unique within an organization. See [Names must be unique within the organization](#unique-agent-name).

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-4cb47f5b44486da5aa446869abac0d95ab37ed68%2Fagent-builder-create-basic.png?alt=media" alt="Create Agent window: Basic Settings is selected in the left navigation, the Name field contains “Demo Website Support Assistant”, and LLM Model appears below"><figcaption><p>Enter the Agent name in Basic Settings</p></figcaption></figure>

### Names must be unique within the organization <a href="#unique-agent-name" id="unique-agent-name"></a>

Each Agent in an organization must have a different name so you can distinguish Agents in dropdowns that only display names, such as delegation scheduling. When creating an Agent, [duplicating an Agent](#duplicate-agent), or changing its name in “<mark style="color:blue;">Basic Settings</mark>”, submitting a name that matches another Agent in the Agent list is blocked. A red message appears below the Name field: “An AI assistant with this name already exists in this organization. Please use a different name.”

The window stays open and retains your other settings. Once you enter a unique name, the red message disappears automatically and you can submit again. If you are on another tab when submitting (such as “<mark style="color:blue;">Permission Settings</mark>”), the screen automatically returns to “<mark style="color:blue;">Basic Settings</mark>” so you can see the message.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-b619de20ab9c129019728c4184187ff2ff00863c%2Fagent-builder-name-duplicate-create.png?alt=media" alt="Basic Settings in the Create AI Assistant window: the Name field is highlighted in red, with a red message below stating that an AI assistant with this name already exists in the organization and a different name is required"><figcaption><p>If the name matches an existing Agent in the organization, a red message appears below the Name field</p></figcaption></figure>

The system compares names as follows:

| Situation                                                                       | Result                                                                                                             |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Extra spaces before or after the name                                           | Leading and trailing spaces are removed before comparison; a name matching an existing name is blocked             |
| Only English letter case differs (for example, `Support Bot` and `support bot`) | These count as different names and can be saved; changing only the case of your own Agent's name can also be saved |
| Same name as a deleted Agent                                                    | Creation is allowed; deleted Agents are excluded from comparison                                                   |
| The name is unchanged when saving                                               | No name check is performed; other settings can be saved as usual                                                   |

{% hint style="info" %}
Agents that already shared a name before this rule was introduced are not renamed automatically, and their settings other than the name can still be changed as usual. Only when you change one of their names must the new name differ from other Agents. We recommend gradually giving them names that are easy to distinguish.
{% endhint %}

### Configure channel activation <a href="#channel-activation" id="channel-activation"></a>

Every new Agent automatically includes three built-in channels: <mark style="color:blue;">Internal Chat</mark>, <mark style="color:blue;">Web Widget</mark>, and <mark style="color:blue;">API Integration</mark>. Click <mark style="color:blue;">Channel Activation</mark> in the <mark style="color:blue;">Basic</mark> group on the left of the creation window to decide whether to enable the latter two before creating the Agent, rather than enabling each platform afterward.

| Channel                                          | Description                                                                        | Can it be changed?                                                |
| ------------------------------------------------ | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| <mark style="color:blue;">Internal Chat</mark>   | Chat directly with the assistant in the admin console                              | Marked <mark style="color:blue;">Always Enabled</mark>; no toggle |
| <mark style="color:blue;">Web Widget</mark>      | Embed it in a website or open it via a URL so visitors can chat with the assistant | Toggle                                                            |
| <mark style="color:blue;">API Integration</mark> | Call the assistant from external systems using an API key                          | Toggle                                                            |

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-96e5b423b54a638ed99772a2041f24cf407bc8d5%2Fagent-builder-create-channel-activation.png?alt=media" alt="Create AI Assistant window: Channel Activation is selected on the left with an Internal Chat Only label; the right explains that the organization defaults to internal chat only, marks Internal Chat as Always Enabled, shows Web Widget and API Integration toggled off, and notes that these can be changed in each channel&#x27;s settings after creation"><figcaption><p>When the organization defaults to internal chat only, both toggles start off</p></figcaption></figure>

* **Initial toggle values**: Follow the organization's “[Enable channels and API integration by default for new assistants](/maiagent-user-guide/en/org/overview/organization-overview.md#new-agent-channel-default)” setting. The current organization default is explained above the section. When the setting is off, the message reads “Current organization default: new assistants only have Internal Chat enabled. Web Widget and API Integration are disabled by default.” Both toggles start off. When it is on, the message reads “Current organization default: all channels are enabled as soon as a new assistant is created.” Both toggles start on.
* **The two toggles are independent**: You can enable only Web Widget and leave API Integration off, or vice versa. The left navigation label updates immediately: <mark style="color:blue;">Internal Chat Only</mark> when both are off, or <mark style="color:blue;">1 External Channel</mark> or <mark style="color:blue;">2 External Channels</mark> when enabled.
* **Who can configure this**: Any member who can open the creation window can configure it; no additional permission is required.
* **Changing settings after creation**: After clicking <mark style="color:blue;">Confirm</mark> to create the Agent, go to its <mark style="color:blue;">Channels</mark> tab, open each channel's <mark style="color:blue;">Platform Settings</mark>, and toggle <mark style="color:blue;">Enabled</mark>. For permissions, see [Default activation state and toggle permissions](/maiagent-user-guide/en/build/conversation-settings/platform-settings/function-settings.md#activation-default-and-permission).

For example, an e-commerce support manager creates a “Website Support Assistant” and wants the website chat window to go live immediately, while keeping the API unavailable to external systems for now. In <mark style="color:blue;">Channel Activation</mark> in the creation window, she enables <mark style="color:blue;">Web Widget</mark> and leaves <mark style="color:blue;">API Integration</mark> off. The left label changes to <mark style="color:blue;">1 External Channel</mark>. She then clicks <mark style="color:blue;">Confirm</mark> to create it. On the new Agent's <mark style="color:blue;">Channels</mark> tab, Web Widget shows <mark style="color:blue;">In Service</mark>, API shows <mark style="color:blue;">Disabled</mark>, and Internal Chat remains available as usual.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-5fb1ebdcd4ec67c5c8a66b9df0e9b9d72d799399%2Fagent-builder-channel-activation-result.png?alt=media" alt="Agent Channels tab: the top shows external service active with 1 external channel serving customers; built-in channels list Web Widget as In Service, Internal Chat, and API as Disabled"><figcaption><p>After creating an Agent with only Web Widget enabled, the Channels tab shows Web Widget as In Service and API as Disabled</p></figcaption></figure>

{% hint style="info" %}
This section only appears in the <mark style="color:blue;">Create AI Assistant</mark> window. For new Agents created through other methods such as [duplicating an Agent](#duplicate-agent), Web Widget and API Integration always follow the organization defaults and do not inherit the source Agent's activation states. Internal Chat is always enabled.
{% endhint %}

## 3. Choose RAG to make your Agent smarter and its answers more accurate <a href="#select-rag-for-smarter-responses" id="select-rag-for-smarter-responses"></a>

### What is RAG? <a href="#what-is-rag" id="what-is-rag"></a>

Think of RAG as a combination of “an assistant who excels at conversation + a librarian who is great at finding information.”

A regular Agent is like someone with an excellent memory and a talent for storytelling, but it can only share knowledge it has previously learned. When an Agent uses RAG, it is as though it **visits the library to find the latest information** before answering, then organizes what it finds in its own words and explains it clearly to you.

On the MaiAgent platform, this “library” is our **knowledge base**. The Agent uses RAG to find relevant information in the knowledge base, making answers more accurate, up to date, and relevant to your needs.

The next section explains how to configure knowledge bases in detail.

{% hint style="info" %}
MaiAgent's knowledge base retrieval combines semantic search, keyword search, and reranking (Reranker). You can also use tag filtering to narrow the search so the Agent finds the most relevant passages before answering.
{% endhint %}

### Configure knowledge bases <a href="#rag-settings" id="rag-settings"></a>

Agents use RAG (Retrieval-Augmented Generation) through knowledge bases. Click “<mark style="color:blue;">Knowledge Base Settings</mark>” in the left navigation of the creation window, then “<mark style="color:blue;">Select Knowledge Bases</mark>” to specify which knowledge bases the Agent should reference.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-9e0983bd7da5ac4051446448c7dec0329c792a4a%2Fagent-builder-create-knowledge-base.png?alt=media" alt="Create Agent window: Knowledge Base Settings is selected on the left; Use Knowledge Base and the Select Knowledge Bases button appear on the right, with no knowledge base selected yet"><figcaption><p>Select the knowledge bases the Agent should reference in Knowledge Base Settings</p></figcaption></figure>

{% hint style="success" %}
Compared with OpenAI RAG, MaiAgent RAG provides additional features to support different deployment needs and more diverse data processing formats, offering a more powerful retrieval and generation experience.

For a detailed comparison, see [**What is RAG? MaiAgent RAG vs. OpenAI RAG comparison table**](https://docs.maiagent.ai/tech/quickstart/rag)
{% endhint %}

### Configure FAQ priority <a href="#configure-faq-priority" id="configure-faq-priority"></a>

To ensure accurate and consistent Agent answers, you can enable FAQ priority. When the knowledge base contains both FAQ content and other documents, the LLM prioritizes FAQ content to answer questions, keeping responses aligned with the standard answers you have created.

**Benefits:**

* **Improve answer accuracy**: When the knowledge base contains both FAQs and other documents, prioritize verified FAQ content to reduce potentially inaccurate answers generated by the AI
* **Ensure consistent answers**: All users receive FAQ answers to the same standard, maintaining service quality
* **Reduce hallucination risk**: Prioritize standard FAQ answers to avoid fabricated or incorrect information from the AI

**Setup:**

1. Click “<mark style="color:blue;">Answer Mode Settings</mark>” in the left navigation of the settings page
2. Enter the following instruction in the “<mark style="color:blue;">Role Instructions</mark>” field:

   ```
   Please prioritize FAQ content when answering user questions
   ```

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-92ee49f4ae858e5acf050b9794a4c06251267279%2F%E6%88%AA%E5%9C%96%202026-01-06%20%E4%B8%8B%E5%8D%882.08.02.png?alt=media" alt="Role Instructions field containing an instruction to prioritize FAQ content when answering user questions"><figcaption><p>Use Role Instructions to request that FAQ content be prioritized.</p></figcaption></figure>

{% hint style="info" %}
With this enabled, the Agent prioritizes FAQ content when both FAQs and other documents are present in the knowledge base. If no relevant FAQ content is found, it still answers using other knowledge base documents or general knowledge.
{% endhint %}

## **4.** Choose a model to give your Agent a smart brain! <a href="#select-model-for-ai-agent" id="select-model-for-ai-agent"></a>

### Why choose a language model? <a href="#language-model-selection-purpose" id="language-model-selection-purpose"></a>

An Agent's performance depends largely on its brain—the language model (LLM) it uses. In this step, you can choose from different models to suit your needs. Your choice affects response speed, comprehension, and the depth and naturalness of answers.

Choosing the right model helps your Agent work efficiently and provides the best experience for your use case!

{% hint style="info" %}
[**Key factors when choosing a large language model**](https://docs.maiagent.ai/tech/quickstart/llm)
{% endhint %}

### Configure the language model <a href="#language-model-settings" id="language-model-settings"></a>

Click “<mark style="color:blue;">Basic Settings</mark>” in the left navigation and select a large language model from the “<mark style="color:blue;">LLM Model</mark>” dropdown. Available models depend on the organization's [model access permissions](/maiagent-user-guide/en/org/model-access.md). The platform sets the model marked as the default in the menu. Compare each model's Credits price, speed, specifications, and retirement date on the [Model Access](/maiagent-user-guide/en/org/model-access.md#compare-price-speed-specs) page.

The dropdown has two groups: “<mark style="color:blue;">Models</mark>” at the top lists individual models, and “<mark style="color:blue;">Fallback Model Groups</mark>” below lists [AI Gateway fallback groups](/maiagent-user-guide/en/build/ai-gateway.md#fallback-groups). When you select a fallback group, its models take over responses in sequence, and the “<mark style="color:blue;">Thinking Effort</mark>” setting is hidden.

#### Understand the capability labels in the menu <a href="#model-capability-labels" id="model-capability-labels"></a>

The model catalog changes as models are added and removed, so this guide does not maintain a separate reference table. Check the labels on each model's row in the menu to see what it supports:

| What you see                                          | Meaning                                                                                                                 |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Parentheses after the model name                      | The inference provider (for example, AWS Bedrock or Azure OpenAI)                                                       |
| <mark style="color:blue;">Default</mark> label        | The default model configured by the platform                                                                            |
| <mark style="color:blue;">Multimodal</mark> label     | Understands images; choose this type if conversations will include uploaded images                                      |
| <mark style="color:blue;">Thinking</mark> label       | Supports thinking effort; after selection, the “<mark style="color:blue;">Thinking Effort</mark>” setting appears below |
| <mark style="color:blue;">Custom</mark> label         | A model the organization connected through AI Gateway                                                                   |
| <mark style="color:blue;">Fallback Group</mark> label | This row is a fallback model group rather than an individual model                                                      |
| Image icon on the second line                         | Blue indicates multimodal support; gray indicates no support. Hover to see “Multimodal: Supported/Not supported”        |
| Number on the second line                             | The model's context length (the number of tokens it can process at once)                                                |

The menu currently does not indicate whether a model supports tool calling (required for Agent mode and skills). If conversation records show an error such as “Model does not support tool calling” after switching to Agent mode, choose another model.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-f0d9543176253c8e3ea6621231ab4bae5cb1a6b9%2F%E6%88%AA%E5%9C%96%202026-07-02%20%E4%B8%8A%E5%8D%8811.30.18.png?alt=media" alt="LLM Model and Thinking Effort options in Basic Settings"><figcaption><p>LLM Model and Thinking Effort settings; the available levels depend on the selected model.</p></figcaption></figure>

### Set thinking effort <a href="#thinking-effort" id="thinking-effort"></a>

When you select a model that supports thinking (marked with a “<mark style="color:blue;">Thinking</mark>” label in the menu), “<mark style="color:blue;">Thinking Effort</mark>” appears below “<mark style="color:blue;">LLM Model</mark>”. It determines how deeply the Agent reasons before answering. This sets the Agent's default level, used when the user has not selected a different level in the conversation.

The options include “<mark style="color:blue;">Default</mark>” and **the levels supported by the current model**. From lowest to highest, the levels are <mark style="color:blue;">Off</mark>, <mark style="color:blue;">Minimal</mark>, <mark style="color:blue;">Low</mark>, <mark style="color:blue;">Medium</mark>, <mark style="color:blue;">High</mark>, <mark style="color:blue;">Extra High</mark>, and <mark style="color:blue;">Maximum</mark>. Higher levels mean deeper reasoning, slower replies, and greater Credits consumption. Click an option to see its description below.

“<mark style="color:blue;">Default</mark>” and “<mark style="color:blue;">Off</mark>” include annotations based on the model's actual behavior so you can understand how your selection affects response speed:

| Option                                                                            | Description                                                                                                                                                                                                                                                                                              |
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Default</mark>                                          | No level is specified. Depending on the model's behavior, this appears as <mark style="color:blue;">Default (no thinking · fastest)</mark> or <mark style="color:blue;">Default (model decides how to think)</mark>                                                                                      |
| <mark style="color:blue;">Off</mark>                                              | Disables thinking. This option appears only when the model allows thinking to be disabled. For models that do not think by default, it appears as <mark style="color:blue;">Off (same as default)</mark>; for models that think by default, it appears as <mark style="color:blue;">Off (fastest)</mark> |
| <mark style="color:blue;">Minimal</mark>–<mark style="color:blue;">Maximum</mark> | Enables thinking. Every level has the description “Enables thinking: adds approximately 1–3 seconds per model call, depending on the model”                                                                                                                                                              |

{% hint style="warning" %}
**“Low” is not always faster than “Default.”** For models that do not think by default (shown as <mark style="color:blue;">Default (no thinking · fastest)</mark>), any thinking level enables thinking and is slower than the default. The settings page then displays “The current setting enables thinking and is slower than the default.” If you simply want faster replies, keep <mark style="color:blue;">Default</mark>.
{% endhint %}

For example, a store lookup Agent uses Claude 4.5 Haiku. The administrator assumes that setting thinking effort to <mark style="color:blue;">Low</mark> will speed up replies, but after selecting it sees “The current setting enables thinking and is slower than the default.” Because this model's <mark style="color:blue;">Default</mark> is labeled “no thinking · fastest,” the administrator switches back to <mark style="color:blue;">Default</mark> and saves to keep replies as fast as possible.

Each model supports different levels. The interface lists only the options available for the current model, for example:

* **Claude 4.5 Haiku**: Supports <mark style="color:blue;">Off</mark> and <mark style="color:blue;">Minimal</mark>, up to <mark style="color:blue;">High</mark>
* **Claude 5.5 Opus**: Thinking cannot be disabled, so there is no <mark style="color:blue;">Off</mark> option. The lowest level is <mark style="color:blue;">Low</mark>, and <mark style="color:blue;">Extra high</mark> and <mark style="color:blue;">Maximum</mark> are available

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-7243cb31dea4817063a7532182f4d916085d4061%2Fagent-thinking-effort-haiku.png?alt=media" alt="Claude 4.5 Haiku is selected as the LLM model. Thinking effort lists Default (no thinking · fastest), Off (same as default), Minimal, Low, Medium, and High. Low is selected, with a notice below that the current setting enables thinking and is slower than the default"><figcaption><p>Claude 4.5 Haiku: Off and Minimal are available, up to High; selecting a thinking level displays a notice that it is slower than the default</p></figcaption></figure>

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-20fd2bd98243553337c6963a805c605362a64605%2Fagent-thinking-effort-no-off.png?alt=media" alt="Claude 5.5 Opus is selected as the LLM model. Thinking effort lists Default (model decides how to think), Low, Medium, High, Extra high, and Maximum. Default is selected, with an explanation below that the model decides whether to think and how much effort to use"><figcaption><p>Claude 5.5 Opus: No Off option; Extra high and Maximum are available. By default, the model decides how to think</p></figcaption></figure>

{% hint style="info" %}
**Thinking levels when switching models**

* When switching to another model that supports thinking, the selected level is retained. If the new model does not support that level, the interface shows the level actually applied, and replies use that level: the closest level supported by the new model that does not exceed the original level. If the new model's lowest level is higher than the original level, its lowest level is used. For example, switching from <mark style="color:blue;">Maximum</mark> on Claude 5.5 Opus to Claude 4.5 Haiku displays <mark style="color:blue;">High</mark>; switching from <mark style="color:blue;">Minimal</mark> on Claude 4.5 Haiku to Claude 5.5 Opus displays <mark style="color:blue;">Low</mark>.
* When switching to a model that does not support thinking, “<mark style="color:blue;">Thinking effort</mark>” is hidden, and the selected thinking level returns to <mark style="color:blue;">Default</mark>.
  {% endhint %}

To let users adjust this during conversations, enable <mark style="color:blue;">Allow users to adjust thinking effort</mark> in the chat platform's [Feature settings](/maiagent-user-guide/en/build/conversation-settings/platform-settings/function-settings.md#ai-interaction). For Web Chat, also enable <mark style="color:blue;">Show thinking process</mark> so that the thinking effort button appears below the input box. See [Thinking effort button in Web Chat](/maiagent-user-guide/en/build/conversation-settings/platform-settings/function-settings.md#web-chat-thinking-effort). MaiGPT does not require these two switches: selecting a model that supports thinking lets users adjust it in the input box. See [MaiGPT chat: Thinking effort](/maiagent-user-guide/en/work/maigpt/chat.md#deep-thinking).

For example, an ecommerce customer service manager's order lookup Agent uses Claude 4.5 Haiku. Most visitors ask simple questions such as “Has my package shipped?” She selects <mark style="color:blue;">Minimal</mark> under “<mark style="color:blue;">Thinking effort</mark>” in “<mark style="color:blue;">Basic settings</mark>” and saves, then enables both <mark style="color:blue;">Show thinking process</mark> and <mark style="color:blue;">Allow users to adjust thinking effort</mark> in the Web Chat platform's feature settings. When visitors start a new conversation, the thinking effort button below the input box shows <mark style="color:blue;">Minimal</mark>. For more complex questions, such as refund calculations, visitors can switch to <mark style="color:blue;">High</mark> before asking.

## 5. Create a System Prompt for Your Use Case <a href="#create-system-prompt-for-use-case" id="create-system-prompt-for-use-case"></a>

To tailor your Agent to different applications, set a “System prompt” so that the AI's response style and content better suit the context.

{% hint style="info" %}
[What is a system prompt? Where can I find example templates?](/maiagent-user-guide/en/build/agent/system-prompt.md)

[AI tool for generating a role assistant](https://chat.maiagent.ai/web-chats/eb2c95ef-f022-4716-92aa-ec0d3ffbc80b/conversations/bc7ed5e6-b3cb-4c91-a465-a4e439c06db4)
{% endhint %}

### Response Mechanism for Reducing Hallucinations <a href="#hallucination-free-generative-ai-response" id="hallucination-free-generative-ai-response"></a>

MaiAgent's response mechanism helps AI maintain high accuracy when answering questions. When a question involves uncertainty or falls outside its knowledge, it openly acknowledges its limitations instead of fabricating answers, providing users with a more reliable, trustworthy AI interaction experience. Its importance across industries and the public sector is outlined below:

{% tabs %}
{% tab title="Industry applications" %}
**Finance:**

When providing investment advice or risk assessments, AI must base its analysis on verified data to avoid false information that could lead to poor investment decisions. When information is insufficient or uncertain, the system explicitly says so to support reliable investment decisions.

**Healthcare:**

When assisting with medical diagnoses or medication inquiries, AI systems must strictly follow established medical knowledge and avoid inventing advice that could mislead patients. For new or unverified medical information, the system clearly indicates that further professional consultation is needed.

**Manufacturing:**

In applications such as production process optimization and quality control, AI must base its recommendations on actual production data and validated methods to avoid production losses caused by inaccurate predictions.

**Education**:

When assisting with teaching or answering students' questions, AI needs to provide accurate knowledge rather than misinformation that could mislead learning. For complex or ambiguous concepts, the system acknowledges the limits of its understanding.

**Legal services:**

When providing legal information and advice, AI must rely on existing laws and case precedents rather than speculative advice that could pose legal risks. The system clearly identifies matters that require further confirmation by a qualified lawyer.

**Customer service:**

When handling customer inquiries, AI must provide accurate product information and service descriptions. For questions it cannot answer with certainty, it immediately refers customers to the appropriate professionals to avoid misleading them.
{% endtab %}

{% tab title="Public sector applications" %}
**Government policy inquiries:**

When providing policy information and service guidance to the public, AI must answer based on current, accurate regulations and administrative procedures to avoid outdated or incorrect information. For complex questions or those requiring professional judgment, the system explicitly recommends seeking assistance from the relevant department.

**Public service decisions:**

When helping governments evaluate decisions on public infrastructure, social welfare, and similar matters, AI must base its analysis on real data and research. It must clearly explain uncertainty in predictions to support reliable policymaking.

**Emergency response management:**

When dealing with natural disasters, public health emergencies, and similar events, AI systems must provide accurate information and guidance, avoiding false information that could mislead the public and undermine disaster preparedness and response.
{% endtab %}
{% endtabs %}

### Choose a Response Mode and Write Your Prompt <a href="#select-answer-mode-to-build-prompt" id="select-answer-mode-to-build-prompt"></a>

Click <mark style="color:blue;">“Response mode settings”</mark> in the left navigation of the Agent settings page. Options range from open conversation to highly structured responses to meet different business needs. Each mode has its own strengths and applications, so choose one that suits your use case.

The available response modes are <mark style="color:blue;">RAG Q\&A</mark>, <mark style="color:blue;">Agent mode</mark>, and <mark style="color:blue;">Template</mark> and <mark style="color:blue;">Hybrid</mark> under <mark style="color:blue;">Other modes</mark>. Newly created Agents default to <mark style="color:blue;">Agent mode</mark>.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-d8c57203a17ef895fde313b581c86aec8895c567%2Fagent-builder-reply-mode-options.png?alt=media" alt="Response mode options: RAG Q&#x26;A and Agent mode, with Template and Hybrid shown after expanding Other modes"><figcaption><p>Expand Other modes to see all four response modes</p></figcaption></figure>

{% hint style="info" %}
The “Workflow” response mode is no longer available. Agents that previously used Workflow mode have been automatically converted to <mark style="color:blue;">RAG Q\&A</mark> mode.
{% endhint %}

{% tabs %}
{% tab title="Response mode: RAG Q\&A" %}
**When to use it**

The AI freely answers questions, generating the most appropriate response based on the context and knowledge base content. Suitable for most Q\&A scenarios

**Steps**

Click “<mark style="color:blue;">Response mode settings</mark>” in the left navigation, select <mark style="color:blue;">“RAG Q\&A”</mark> as the response mode, and enter the system prompt you have defined for the Agent in the “<mark style="color:blue;">System prompt</mark>” field. If the model supports it, use “<mark style="color:blue;">Output format</mark>” to choose plain text or JSON output. See [Output format: Plain text or JSON Schema](#output-format-json-schema) for details.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-95d9ce5caa9d8ad5a3b9f4abb0d9b8880cc14cfe%2Fagent-builder-reply-mode-rag.png?alt=media" alt="Response mode settings: RAG Q&#x26;A is selected, with System prompt and Output format fields below"><figcaption><p>Select RAG Q&#x26;A to enter a system prompt and choose an output format</p></figcaption></figure>

**Use case: Website customer service assistant**

To create a website customer service assistant for “MaiAgent - Agent Development Platform,” enter the AI's response instructions in the “System prompt” field to clearly define its response style and responsibilities

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-889916bc42d32b39304aa6a21519d3ed92630f30%2Fagent-builder-create-role-instruction.png?alt=media" alt="Response mode settings in the Create Agent window: the System prompt field contains instructions for a website customer service assistant"><figcaption><p>Enter the website customer service assistant's response instructions in the System prompt field</p></figcaption></figure>
{% endtab %}

{% tab title="Response mode: Template" %}
Selecting “<mark style="color:blue;">**Response mode: Template**</mark>” significantly reduces hallucinations. The Agent strictly answers questions using the knowledge base and FAQ content you provide, classifying questions rather than asking the LLM to generate content. Using the template system to answer minimizes the risk of hallucinations.

**When to use it**

Scenarios that require a consistent response format, such as standard inquiry procedures and reports.

**Example walkthrough**

Suppose you want to create a “Municipal Services Hotline” customer service Agent to answer residents' questions about municipal services in real time.

**1. Click “**<mark style="color:blue;">**Response mode settings**</mark>**” in the left navigation, expand&#x20;**<mark style="color:blue;">**“Other modes”**</mark>**&#x20;and select&#x20;**<mark style="color:blue;">**“Template”**</mark>

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-ee9beee4833a61e1ad64638fbdc439c07b867ca7%2Fagent-builder-reply-mode-template.png?alt=media" alt="Response mode settings: Other modes is expanded and Template is selected, displaying Response template and Fallback template fields below"><figcaption><p>Select Template to display the Response template and Fallback template fields</p></figcaption></figure>

**2. Fill in the response template (use the template system to generate answers)**

If you have not yet created a knowledge base and FAQ, the response template instructions default to the following.

We recommend adding a knowledge base or FAQ first to use the response template. The files **must be in a tabular format such as Excel, CSV, json, or jsonl.**

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-c2c3b6aac1f66b06a9f5864572950c5a9c074f50%2Fimage%20(56).png?alt=media" alt="The Response template field uses loop, question, and answer to list FAQ entries one by one"><figcaption><p>Example FAQ loop and question/answer variables in a response template.</p></figcaption></figure>

In this example, I have an Agent named “Municipal Services Hotline” and have added a “Municipal Services FAQ” to its knowledge base.

The FAQ fields include question, answer, agency, category, and publication time

We recommend uploading tabular files such as **Excel, CSV, json, or jsonl**. The fields must have **headers and corresponding content**.

![](https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-b461f55433989c2f04cbd8eb6a41851e710e822a%2Fimage%20\(62\).png?alt=media)

Return to the response template editor and click “<mark style="color:blue;">**Initialize response template**</mark>” in the upper right. The system generates a sample response based on the document you just uploaded to the knowledge base, for example:

```
Your question relates to the following information:

[loop: 市政服務 FAQ.xlsx]
{@loopIndex}. Question: {問題} Answer: {答案} Agency: {機關} Category: {分類} Publication time: {發布時間}
[endloop]

Thank you for your inquiry.
```

You can now edit and format the response text.

The \[] {} portions are system instructions, so edit only the text.

📍 **Loop: Enter the corresponding document filename (specify which document to use for response generation)**

I made the following changes:

* [x] Content of the “**opening message”**
* [x] **“Question” text**
* [x] **“Category” text**
* [x] **Removed “Agency”**
* [x] **Closing message content**
* [x] **Line breaks and formatting**

When we return to the Agent Q\&A interface and ask a relevant question, the Agent's response follows exactly the **template format** we just edited and the **FAQ document content**.

**3. Fill in the fallback template**

If the Agent determines that there is no relevant information, it responds using the “<mark style="color:blue;">**Fallback template**</mark>”.

Finally, click “<mark style="color:blue;">**Save**</mark>”.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-ac3c2e9f4d87adc11a473249038a9d7befea7b27%2Fagent-builder-reply-mode-template-fallback.png?alt=media" alt="Response template and Fallback template fields, with the Save button at the bottom right"><figcaption><p>Fill in the fallback template, then click Save</p></figcaption></figure>
{% endtab %}

{% tab title="Response mode: Hybrid" %}
**When to use it**

Combines RAG Q\&A with templates: some content follows the template format, while the rest is generated freely. Suitable for scenarios requiring partially structured responses.

**Usage recommendations**

The system prompt may conflict with “Response mode: Template,” so when choosing “Response mode: Hybrid,” write the system prompt as broad guidelines.

For example, describe the role's tasks, interaction principles, and communication style.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-cfb9167a4846ec52018f7ae6ca99395e141d0617%2Fagent-builder-reply-mode-hybrid.png?alt=media" alt="Response mode settings: Other modes is expanded and Hybrid is selected, with System prompt and Response template fields below"><figcaption><p>When Hybrid is selected, both System prompt and Response template are displayed</p></figcaption></figure>
{% endtab %}

{% tab title="Response mode: Agent mode" %}
**When to use it**

In daily business operations, employees often need to organize information, analyze data, and create reports and analytical summaries for routine work or tasks assigned by their managers. Common questions include:

* “Which product sold the most last month?”
* “List all customers with sales exceeding 100,000”
* “What is the revenue trend over the past three months?”

When nontechnical staff handle these questions, they often rely on the data team to write SQL queries, which is time consuming and inefficient.

With MaiAgent's Agent mode, the system can use the Text to SQL tool to automatically convert natural language questions into SQL queries and query the database in real time to quickly deliver analytical results.

{% hint style="info" %}
For an introduction to Text to SQL, see [Text to SQL](/maiagent-user-guide/en/build/database/text2sql.md)
{% endhint %}

This feature is particularly suitable for scenarios requiring <mark style="color:blue;">**real-time queries and data insights**</mark>, such as report analysis, operational metric tracking, and data queries. It gives nontechnical users easy access to data for a more intuitive, efficient decision-making process driven by data.

**Text to SQL steps**

1. Click “Response mode settings” in the left navigation and select <mark style="color:blue;">**“Agent mode”**</mark> as the response mode

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-4720e2275f9ff8972360e8724ed7521dff892a68%2Fagent-builder-reply-mode-agent.png?alt=media" alt="Response mode settings: Agent mode is selected, with Database settings, Tools, and other items in the left navigation"><figcaption><p>Select Agent mode</p></figcaption></figure>

2. Click “Database settings” in the left navigation, then click “Select database” to link an existing database. Create databases under “<mark style="color:blue;">AI features</mark>” → “<mark style="color:blue;">Databases</mark>” in the left menu. You can upload a spreadsheet to create a MaiAgent database or connect an external database such as PostgreSQL, MySQL, SQL Server, Oracle, or SynxDB. See [Create and Configure Databases](/maiagent-user-guide/en/build/database/create-database.md) for instructions

**Use case: Querying ecommerce product sales data**

Suppose you are a marketer at an ecommerce platform and want to quickly look up product sales and similar data

First, click “Response mode settings” in the left navigation and select <mark style="color:blue;">**“Agent mode”**</mark> as the response mode

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-4720e2275f9ff8972360e8724ed7521dff892a68%2Fagent-builder-reply-mode-agent.png?alt=media" alt="Response mode settings: Agent mode is selected, with Database settings, Tools, and other items in the left navigation"><figcaption><p>Select Agent mode</p></figcaption></figure>

Next, create a MaiAgent database under “<mark style="color:blue;">Databases</mark>” and upload an Excel file. The system automatically converts it into a queryable table

{% hint style="info" %}
For details about MaiAgent databases, see [Text to SQL with MaiAgent Databases](/maiagent-user-guide/en/build/database/text-to-sql-maiagent.md)
{% endhint %}

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-b9e56bbbf14ebaca0880a2190930e59267e0261d%2F%E6%88%AA%E5%9C%96%202025-04-23%20%E4%B8%8B%E5%8D%883.01.50.png?alt=media" alt="An ecommerce sales table with columns for sales channel, date, product name, quantity, and amount"><figcaption><p>Example sales table with column headers and data rows.</p></figcaption></figure>

You can also ask your company's technical staff for MySQL or PostgreSQL connection details and first create an external database under “<mark style="color:blue;">Databases</mark>” (see [Create and Configure Databases](/maiagent-user-guide/en/build/database/create-database.md)).

Then click “<mark style="color:blue;">Database settings</mark>” in the left navigation of the Agent settings, click “<mark style="color:blue;">Select database</mark>” to link it, and save.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-209e26ccc4634848c63dc94eb4d3c71c5d55686b%2Fagent-builder-create-database.png?alt=media" alt="Database settings is selected in the left navigation. The right pane shows usage tips, linked databases, and the Select database button, with no database selected yet"><figcaption><p>Link the database you want to query in Database settings</p></figcaption></figure>

Once configured, go to the Agent Q\&A interface and enter a question, such as

“What are the top three items by sales on the official website, excluding shipping fees?”

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-304f6095eb36c1686b12e9d0a28b305aeca1bd18%2F%E6%88%AA%E5%9C%96%202025-04-23%20%E4%B8%8B%E5%8D%883.00.14.png?alt=media" alt="The ecommerce revenue analysis assistant identifies the top three items by sales on the official website, excluding shipping fees"><figcaption><p>Example response to a natural language query about sales data.</p></figcaption></figure>
{% endtab %}
{% endtabs %}

### Output Format: Plain Text or JSON Schema <a href="#output-format-json-schema" id="output-format-json-schema"></a>

When the response mode is <mark style="color:blue;">RAG Q\&A</mark> and the selected LLM model supports structured output, “<mark style="color:blue;">Output format</mark>” appears below the system prompt:

* <mark style="color:blue;">Plain text output</mark> (default): Standard conversational replies.
* <mark style="color:blue;">JSON output</mark>: Selecting this displays the “<mark style="color:blue;">Output format JSON Schema</mark>” field. Paste a JSON Schema, and every Agent response will be JSON that conforms to this structure. This is useful when a program needs to parse the response, for example to extract form fields from a conversation or classify questions.

How to fill it in:

* The content must be valid JSON. Otherwise, saving displays “Invalid output format JSON.”
* Use `"type": "object"` at the top level, and define each field's `type` and `description` in `properties`. Clearer descriptions help the Agent fill in values more accurately. You can adapt the `Person` example shown when the field is empty:

```json
{
  "title": "Person",
  "type": "object",
  "properties": {
    "name": { "type": "string", "description": "The person's name." },
    "age": { "type": "integer", "description": "Age in years which must be equal to or greater than zero." }
  }
}
```

* Place every field inside `properties` and specify a `type` for each one. If you paste only sample response data (such as `{"answer": "string"}`), it does not define any fields and cannot be saved. See [Error when pasting sample data](#output-format-no-fields-error) below.
* If “Output format” is missing, the current model does not support JSON output or the response mode is not RAG Q\&A; you can switch to another model.

{% hint style="info" %}
System prompts and knowledge base retrieval still apply to JSON output. This mode is typically used with [API integration](/maiagent-user-guide/en/org/developer.md#integration-docs), where your program parses the returned JSON. Users on standard chat platforms see the raw JSON directly.
{% endhint %}

#### Error When Pasting Sample Data <a href="#output-format-no-fields-error" id="output-format-no-fields-error"></a>

The “<mark style="color:blue;">Output format JSON Schema</mark>” field requires a Schema describing the fields, rather than an example of what the response looks like. Pasted sample data may be valid JSON, but it does not define any fields, leaving the Agent unable to determine what to output. Clicking “<mark style="color:blue;">Save</mark>” opens an “<mark style="color:blue;">Error</mark>” dialog listing the keys that need to be moved into `properties`:

> This JSON Schema does not define any fields and appears to be sample data rather than a Schema. Wrap the fields in a top-level "properties" object and specify a "type" for each field. Keys to move into "properties": answer, suggested\_questions.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-420bb4beff810fc4039e061a3df2c0492f561bac%2Fagent-output-format-example-payload.png?alt=media" alt="JSON output is selected for Output format. The Output format JSON Schema field contains sample data with only the answer and suggested_questions keys"><figcaption><p>Sample data pasted instead of a Schema</p></figcaption></figure>

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-2647103190d431af19b355a59484f7f997664989%2Fagent-output-format-no-fields-error.png?alt=media" alt="Error dialog: This JSON Schema does not define any fields and appears to be sample data rather than a Schema. The keys to move into properties are answer and suggested_questions"><figcaption><p>The error on saving lists the keys to move into properties</p></figcaption></figure>

Move the listed keys into `properties`, add a `type` for each one (a `description` is also recommended), and click “<mark style="color:blue;">Save</mark>” again. The example above becomes:

```json
{
  "type": "object",
  "properties": {
    "answer": { "type": "string", "description": "The reply to the customer" },
    "suggested_questions": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Suggested follow-up questions for the customer"
    }
  },
  "required": ["answer", "suggested_questions"]
}
```

**Use case**: Alex, an engineer at the e-commerce company Acme, wants the customer service Agent to return two fields, “answer” and “suggested follow-up questions,” so the website can display the questions as buttons. Under “<mark style="color:blue;">Output format</mark>,” he selects “<mark style="color:blue;">Output JSON</mark>,” pastes his sample response `{"answer": "string", "suggested_questions": ["string"]}` directly into the field, and clicks Save. An error message appears, indicating that `answer` and `suggested_questions` must be moved into `properties`. He converts the sample to a Schema using the format above and saves again. The message “<mark style="color:blue;">Saved successfully</mark>” confirms that the output format is configured.

{% hint style="warning" %}
For Agents whose output format was previously saved using sample data, editing any setting (even one unrelated to the output format) and clicking “<mark style="color:blue;">Save</mark>” will trigger the same error. First replace the “<mark style="color:blue;">Output format JSON Schema</mark>” with a valid Schema. If you do not need JSON output, select “<mark style="color:blue;">Output plain text</mark>” to save instead.
{% endhint %}

### Agent mode options: Normal mode and Canvas mode <a href="#agent-mode-normal-vs-canvas" id="agent-mode-normal-vs-canvas"></a>

After you select <mark style="color:blue;">Agent mode</mark>, an “<mark style="color:blue;">Agent mode</mark>” section and several built-in tool switches (Code Interpreter, Browser Tool, and image search; see [Built-in tool switches in Agent mode](/maiagent-user-guide/en/build/tools/configure_tools.md#agent-mode-builtin-switches)) appear below the role instructions. “Agent mode” offers two options:

| Option                                                 | On-screen description                                               | When to choose it                                                                                                                                                                                                                       |
| ------------------------------------------------------ | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">Normal mode</mark> (default) | The AI completes tasks autonomously using instructions and tools.   | Most scenarios involving questions and answers, information lookup, and tool calls                                                                                                                                                      |
| <mark style="color:blue;">Canvas mode (Canvas)</mark>  | Execute complex tasks through a visual workflow orchestration tool. | When the Agent needs to create a finished result, such as a web page, interactive report, or chart; the result appears in the Canvas beside the conversation, where users can switch between the preview and source code or download it |

Canvas mode is available only when the selected model supports tool calling. Your organization's plan may also restrict the available Agent modes. Remember to click <mark style="color:blue;">Save</mark> after switching. See [Canvas](/maiagent-user-guide/en/work/maigpt/canvas.md) for how results are displayed, and [Text to SQL with a MaiAgent database](/maiagent-user-guide/en/build/database/text-to-sql-maiagent.md) for an example of creating a visual report with Text to SQL.

## 6. Pre-assign Agent permissions <a href="#pre-assign-agent-permissions" id="pre-assign-agent-permissions"></a>

{% hint style="info" %}
[RABC-based permission management architecture and explanation](/maiagent-user-guide/en/org/roles/role-permission.md)
{% endhint %}

Click “<mark style="color:blue;">Permission settings</mark>” in the left navigation to specify which roles' members can use the Agent. Under “<mark style="color:blue;">Quick permission scope selection</mark>,” choose <mark style="color:blue;">All roles</mark>, <mark style="color:blue;">Exclude default roles</mark>, or <mark style="color:blue;">Custom role selection</mark> to suit your use case.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-1d1403d3c009175117908a7cee8af19f3e57f045%2Fagent-builder-create-permissions.png?alt=media" alt="Create Agent dialog: Permission settings is selected in the left navigation, and the quick permission scope selection on the right offers All roles, Exclude default roles, and Custom role selection"><figcaption><p>Select the roles that can use this Agent in Permission settings</p></figcaption></figure>

### Who can see the Agent after it is created <a href="#who-can-see-new-agent" id="who-can-see-new-agent"></a>

Agents do not have a “draft” or “unpublished” state. Once you click <mark style="color:blue;">Confirm</mark> to create an Agent, it appears in the Agent list. The permission settings here determine who can see it:

* **Organization owners**: Can always see all Agents.
* **Other members**: Can see and use the Agent only if one of their roles is selected in its permission settings. If the creator is not an owner, they must select at least one role they belong to that has <mark style="color:blue;">AI assistant permissions</mark>; otherwise, they cannot create the Agent.
* **While you are still configuring it and do not want others to use it**: Select only your team's roles first. After testing, return to <mark style="color:blue;">Permission settings</mark> to add other roles.

Whether external visitors can use this Agent is controlled separately by the conversation channel's <mark style="color:blue;">Enabled</mark> setting. See [Feature settings](/maiagent-user-guide/en/build/conversation-settings/platform-settings/function-settings.md#activation-default-and-permission). For the rules mapping roles to resources, see [Role-based resource visibility control](/maiagent-user-guide/en/org/roles/group-resource-visibility.md).

## 7. Complete your Agent setup <a href="#complete-ai-agent-setup" id="complete-ai-agent-setup"></a>

After completing the steps above, click the blue “<mark style="color:blue;">Confirm</mark>” button in the bottom-right corner of the dialog to finish setup 🎉.

## Duplicate and delete Agents <a href="#duplicate-and-delete-agent" id="duplicate-and-delete-agent"></a>

The “<mark style="color:blue;">Actions</mark>” column on the right side of each row in the Agent list includes “<mark style="color:blue;">Duplicate</mark>” and “<mark style="color:blue;">Delete</mark>” as well as “<mark style="color:blue;">Edit</mark>.”

### Sync conversation channel names when renaming <a href="#sync-channel-names" id="sync-channel-names"></a>

After you change and save the Agent name in <mark style="color:blue;">Basic settings</mark>, a “<mark style="color:blue;">Sync conversation channel names</mark>” dialog appears if any of the Agent's conversation channels can be renamed along with it. The dialog asks whether to update the names of the listed channels as well. Select the channels to rename and click “<mark style="color:blue;">Update together</mark>.” Click “<mark style="color:blue;">Change assistant name only</mark>” to keep the channels' existing names. The two built-in channels, “Internal conversation” and “API,” are updated automatically and do not appear in the list. If the list is empty, the dialog displays “No conversation channels need to be renamed.”

The new name must also be unique among Agents in the organization. See [Names must be unique within the organization](#unique-agent-name).

### Duplicate an Agent <a href="#duplicate-agent" id="duplicate-agent"></a>

Click “<mark style="color:blue;">Duplicate</mark>” to open the “<mark style="color:blue;">Duplicate AI assistant</mark>” dialog. It displays the “<mark style="color:blue;">Source AI assistant</mark>” and prefills “<mark style="color:blue;">New AI assistant name</mark>” with “Original name Copy.” Edit the name and click “<mark style="color:blue;">Confirm</mark>.” The new Agent immediately appears in the list.

The new Agent's name must also be unique among Agents in the organization. If you remove “Copy” from the prefilled name and keep the source Agent's name, clicking “<mark style="color:blue;">Confirm</mark>” displays a red message below the name field, and the dialog stays open. Enter a different name to continue. See [Names must be unique within the organization](#unique-agent-name).

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-1de152b9af75453d74d111386e187171700591fd%2Fagent-builder-name-duplicate-copy.png?alt=media" alt="Duplicate AI assistant dialog: The new AI assistant name matches the source AI assistant name, and a red message below the field says that an AI assistant with this name already exists in the organization and asks for a different name"><figcaption><p>Keeping the original name when duplicating displays a message below the New AI assistant name field</p></figcaption></figure>

Duplicating preserves the original Agent's settings (response mode, role instructions, model, advanced settings, and more), along with its links to knowledge bases and skills. Conversation channels, conversation history, and usage statistics are not copied. Use a copy to test new role instructions or models before applying them to the production Agent.

### Delete an Agent <a href="#delete-agent" id="delete-agent"></a>

Click “<mark style="color:blue;">Delete</mark>” to open the “<mark style="color:blue;">Delete AI assistant and associated conversation channels</mark>” dialog, which lists all “<mark style="color:blue;">Associated conversation channels</mark>” under this Agent. After you click “<mark style="color:blue;">Confirm deletion</mark>”:

* **The Agent and all listed conversation channels are deleted together**: Connected channels such as your website and LINE are deleted along with the Agent. You cannot keep only the channels.
* **Conversation history is retained**: Conversation records from these channels remain available under “<mark style="color:blue;">Customer service conversations</mark>” → “<mark style="color:blue;">All conversations</mark>.”
* **This action cannot be undone**: You cannot restore the Agent's settings after deletion. To keep the settings for reference, first create a copy using “Duplicate” above.

{% hint style="info" %}
Every Agent has two built-in channels managed by the system: “<mark style="color:blue;">Internal conversation</mark>” and “<mark style="color:blue;">API</mark>.” They cannot be deleted individually from the conversation channel list and are deleted only when the Agent is deleted.
{% 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/build/agent/setup.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.