> 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/build/tools/configure_tools.md).

# 為 Agent 配置工具

為 Agent 配置工具：在 Agent 設定頁選用已建立的 API／MCP 工具、關閉不需要的系統功能，以及啟用 MaiAgent 內建工具。

建立好的工具現在可以在 Agent 設定中被選用，賦予您的 Agent 更強大的能力。本指南將說明如何將您建立的工具配置給特定的 Agent。

## 配置工具 <a href="#configure-tools" id="configure-tools"></a>

### 1. 進入 Agent 設定 <a href="#step-1-enter-ai-agent-settings" id="step-1-enter-ai-agent-settings"></a>

首先，請從左側導航欄進入「<mark style="color:blue;">AI 功能</mark>」區塊，然後點擊「<mark style="color:blue;">AI 助理</mark>」。這將顯示您帳戶中所有已建立的 Agent 列表。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-87b5a1243ec25ab81a5f9c010df5c95917736f43%2Fagent-builder-list.png?alt=media" alt="Agent 列表：顯示名稱、大語言模型、回答模式等欄位，右上角有建立 Agent 按鈕，每列右側有操作按鈕"><figcaption><p>找到您想要配置工具的 Agent</p></figcaption></figure>

### 2. 選擇要配置的 Agent <a href="#step-2-select-ai-agent" id="step-2-select-ai-agent"></a>

在 Agent 列表中，找到您想要為其配置工具的 Agent，並點擊「<mark style="color:blue;">編輯</mark>」按鈕，進入該 Agent 的詳細設定頁面。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-87b5a1243ec25ab81a5f9c010df5c95917736f43%2Fagent-builder-list.png?alt=media" alt="Agent 列表，每列右側操作欄有編輯按鈕"><figcaption><p>點選操作欄的編輯按鈕，進入該 Agent 的設定頁面</p></figcaption></figure>

### 3. 切換 Agent 的回答模式 <a href="#step-3-switch-qa-mode" id="step-3-switch-qa-mode"></a>

{% hint style="danger" %}
**重要前提：** 只有設定為 **Agent 模式** 的 Agent 才能使用工具。如果您的 Agent 處於其他模式（例如：RAG 問答模式），則無法為其配置或使用工具。
{% endhint %}

在 Agent 的設定頁面中，點選左側導覽的「<mark style="color:blue;">回答模式設定</mark>」。

* **檢查**：確認當前選擇的模式是否為「<mark style="color:blue;">Agent 模式</mark>」
* **更改**：如果當前不是 Agent 模式，請將其**切換**為 Agent 模式。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-4720e2275f9ff8972360e8724ed7521dff892a68%2Fagent-builder-reply-mode-agent.png?alt=media" alt="回答模式設定：已選擇 Agent 模式，左側導覽顯示資料庫設定、工具等項目"><figcaption><p>確保 Agent 已設定為 Agent 模式才能使用工具</p></figcaption></figure>

### 4. 切換到工具配置頁面 <a href="#step-4-go-to-tool-config-page" id="step-4-go-to-tool-config-page"></a>

在 Agent 的設定頁面中，點選左側導覽的「<mark style="color:blue;">工具</mark>」。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-5ebd173d876bceafb12c2e62674512fb2c2a5781%2Fagent-builder-tools-page.png?alt=media" alt="Agent 設定頁：左側導覽選取工具，右側使用工具區塊列出已選的工具，右上角有選擇工具按鈕，右下角有儲存按鈕"><figcaption><p>工具配置頁面</p></figcaption></figure>

### 5. 選擇啟用的工具 <a href="#step-5-select-enabled-tools" id="step-5-select-enabled-tools"></a>

在此工具配置頁面，點選右上角「<mark style="color:blue;">選擇工具</mark>」按鈕，會開啟預先建置好的工具清單列表，並進行以下操作。

* **操作**：
  1. 瀏覽列表，找到您希望此 Agent 能夠使用的工具。
  2. 勾選您想要啟用的工具旁邊的複選框。
  3. 您可以根據 Agent 的任務和需求，選擇任意數量的工具。

{% hint style="info" %}
您可以選擇 MaiAgent 內建工具或您自行定義之工具
{% endhint %}

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-19d0d2ea8d6cb2d488c9058ec0eec8cda5640a34%2Fagent-builder-select-tools-modal.png?alt=media" alt="選擇工具視窗：上方有搜尋欄與工具類型篩選，列出已選擇的工具與系統內建工具清單，每個工具前有勾選框"><figcaption><p>勾選希望此 Agent 使用的工具</p></figcaption></figure>

{% hint style="info" %}
**提示：** 請確保只為 Agent 配置它確實需要且被授權使用的工具。配置過多不相關的工具可能會影響 AI 的判斷準確性和回應效率。
{% endhint %}

### 6. 檢視已選工具 <a href="#step-6-review-selected-tools" id="step-6-review-selected-tools"></a>

在勾選完成後，您可以再次確認配置給 Agent 的工具，確保為此 Agent 配置了正確的工具。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-5ebd173d876bceafb12c2e62674512fb2c2a5781%2Fagent-builder-tools-page.png?alt=media" alt="使用工具區塊列出已選的三個工具，每個工具右側有刪除圖示"><figcaption><p>確認已為 Agent 配置了正確的工具</p></figcaption></figure>

## 控制系統功能 <a href="#control-system-functions" id="control-system-functions"></a>

除了自行選擇的工具，Agent 也有預設開啟的系統功能，例如搜尋目前對話的歷史訊息、讀取附件及產生下載連結。您可以依每個 Agent 的工作需要個別關閉，減少不必要的 token 使用，也讓 Agent 的行為更容易預期。

例如，客服主管建立一個只回答常見問題、不處理附件的 Agent。她進入該 Agent 的進階設定，關閉附件讀取與解析功能並儲存；之後這個 Agent 仍能回答知識庫問題，但不會再嘗試解析顧客上傳的檔案。

{% stepper %}
{% step %}

### 1. 進入進階設定 <a href="#open-advanced-settings" id="open-advanced-settings"></a>

開啟要調整的 Agent，從設定頁左側選擇 <mark style="color:blue;">進階設定</mark>。
{% endstep %}

{% step %}

### 2. 調整系統功能 <a href="#adjust-system-functions" id="adjust-system-functions"></a>

捲動到 <mark style="color:blue;">系統功能</mark>，依需要開啟或關閉下列功能：

* 搜尋對話歷史
* 取得訊息前後文
* 讀取純文字附件
* 解析附件內容
* 列出可用解析器
* 產生下載連結

關閉後，Agent 將無法再使用該功能，相關回答也可能受到影響。

<mark style="color:blue;">讀取純文字附件</mark> 或 <mark style="color:blue;">解析附件內容</mark> 任一開啟時，Agent 還能找回本對話先前傳過的所有檔案，詳見[找回本對話的檔案](#conversation-files)。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-c9c94f6d31a9899182ab5b66fa1269ecbff5cfa7%2Fai-agent-system-functions.png?alt=media" alt="Agent 進階設定中的系統功能開關"><figcaption><p>依 Agent 的用途開啟或關閉系統功能</p></figcaption></figure>
{% endstep %}

{% step %}

### 3. 儲存設定 <a href="#save-system-functions" id="save-system-functions"></a>

點擊右下角 <mark style="color:blue;">儲存</mark>，讓設定生效。
{% endstep %}
{% endstepper %}

{% hint style="info" %}
清單中的後四項功能只在 <mark style="color:blue;">Agent 模式</mark> 生效。若這些開關無法操作，請先到 <mark style="color:blue;">回答模式設定</mark> 切換為 Agent 模式。
{% endhint %}

### 找回本對話的檔案 <a href="#conversation-files" id="conversation-files"></a>

<mark style="color:blue;">讀取純文字附件</mark> 或 <mark style="color:blue;">解析附件內容</mark> 任一開啟時，Agent 模式的 Agent 會自動多一個「列出本對話檔案」工具，不需要另外設定。對話一長，幾輪前傳的檔案容易被 Agent 忘記；使用者問起先前的檔案時，Agent 會先列出本對話的檔案清單，再重新打開需要的那一個，不必請使用者重新上傳。

例如，業務在 MaiGPT 先上傳一張收據照片和一份會議紀錄，接著問「這個對話裡有哪些檔案？請列出每個檔案的類型、大小和上傳者。」，Agent 列出兩個檔案的檔名、類型、大小與上傳者；再問「剛剛那張收據的合計金額是多少？」，Agent 重新讀取那張照片，回答收據上的合計金額。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-004171e1583f1ec6f71120c600b401f567cdbd91%2Fai-agent-conversation-files-list.png?alt=media" alt="MaiGPT 回覆上方的執行步驟顯示 list_conversation_files，下方表格列出 demo-meeting-notes.txt 與 demo-receipt.png 的類型、大小與上傳者"><figcaption><p>展開執行步驟可看到 Agent 使用了 list_conversation_files 列出本對話檔案</p></figcaption></figure>

* **列出範圍**：使用者傳的文件與圖片、真人客服傳的檔案，以及 Agent 自己產出的檔案（例如 Canvas）。Agent 只看得到目前這個對話的檔案。
* **篩選**：檔案多時，Agent 可依類型、上傳者、檔名或時間篩選。
* **重新打開**：文件與圖片透過 <mark style="color:blue;">解析附件內容</mark> 重新打開，圖片會重新辨識內容；txt、csv 等純文字檔也能用 <mark style="color:blue;">讀取純文字附件</mark> 打開。只開啟 <mark style="color:blue;">讀取純文字附件</mark> 時，其他類型的檔案只會列出，無法重新打開。
* **Agent 產出的檔案**：只列出、不重新讀取內容；開啟 <mark style="color:blue;">產生下載連結</mark> 時，Agent 可以再次提供 Canvas 的下載連結。
* **適用通路**：LINE、Messenger、網頁、MaiGPT 等所有通路都適用。

{% hint style="info" %} <mark style="color:blue;">讀取純文字附件</mark> 與 <mark style="color:blue;">解析附件內容</mark> 都關閉時，Agent 不會有這個工具，也就無法找回先前的檔案。
{% endhint %}

### 7. 💾 儲存 Agent 設定 <a href="#step-7-save-ai-agent-settings" id="step-7-save-ai-agent-settings"></a>

完成工具的選擇後，**請務必記得**點擊「<mark style="color:blue;">儲存</mark>」按鈕，以保存您對 Agent 設定所做的更改。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-5ebd173d876bceafb12c2e62674512fb2c2a5781%2Fagent-builder-tools-page.png?alt=media" alt="工具配置頁面右下角的儲存按鈕"><figcaption><p>點擊「儲存」以套用工具配置</p></figcaption></figure>

## Agent 模式的內建工具開關 <a href="#agent-mode-builtin-switches" id="agent-mode-builtin-switches"></a>

回答模式為 <mark style="color:blue;">Agent 模式</mark> 時，<mark style="color:blue;">回答模式設定</mark> 分頁還有一組不需另外建立工具、直接用開關控制的能力：

| 設定                                                | 畫面說明                                                                                 | 補充                                                                                                                                                     |
| ------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <mark style="color:blue;">啟用工具搜尋功能</mark>         | 啟用工具搜尋功能，會自動搜尋可用的工具來輔助回應                                                             | 預設開啟。工具很多時，Agent 先搜尋再呼叫，只用來搜尋工具的那幾輪不計入最大迭代次數，見[Agent 執行上限](/build/agent/custom-max-tokens.md#agent-iteration-timeout-relationship)                     |
| <mark style="color:blue;">Agent 模式</mark>         | <mark style="color:blue;">一般模式</mark>／<mark style="color:blue;">畫布模式 (Canvas)</mark> | 兩者差異見[Agent 模式的子選項](/build/agent/setup.md#agent-mode-normal-vs-canvas)                                                                                 |
| <mark style="color:blue;">Code Interpreter</mark> | 啟用後，AI 可以在沙盒環境中執行程式碼來完成任務。                                                           | 開啟後畫面列出四點提示（支援 Python、安全沙盒、檔案可在 Output 面板下載、適合計算與資料處理），詳見 [Code Interpreter](/build/agent/code-interpreter.md)                                         |
| <mark style="color:blue;">Browser Tool</mark>     | 啟用後，AI 助理可以操控瀏覽器瀏覽網頁並執行操作。                                                           | 畫面標示「此功能針對 Claude 模型最佳化，使用其他模型可能效果不佳」，詳見 [Browser Tool](/build/agent/browser-tool.md)                                                                  |
| <mark style="color:blue;">圖片搜尋</mark>             | 當知識庫使用多模態 embedding 模型時，提供 image\_search 工具搜尋圖片內容。關閉後將完全移除此工具。                       | 只有在關聯的知識庫使用多模態 Embedding 模型、且有上傳圖片時才有作用；不需要以圖找圖的 Agent 可關閉，省下工具描述佔用的 token。用量可在 [Agent 監控](/build/agent-ops/evaluations.md#view-image-search-usage) 查看 |

這些開關跟 <mark style="color:blue;">工具</mark> 分頁選用的 API／MCP 工具彼此獨立；改完同樣要按右下角 <mark style="color:blue;">儲存</mark>。

## 配置 MaiAgent 內建工具 <a href="#configure-maiagent-builtin-tools" id="configure-maiagent-builtin-tools"></a>

MaiAgent 內建三種 AI 圖像生成工具，您可以根據您的需求套用給 Agent 使用，不需額外設置：在「<mark style="color:blue;">選擇工具</mark>」視窗的「<mark style="color:blue;">系統內建工具</mark>」中勾選 <mark style="color:blue;">Gemini 3 Pro Image</mark>、<mark style="color:blue;">Gemini 3.1 Flash Image</mark> 或 <mark style="color:blue;">GPT Image 2 圖片生成工具</mark>。

{% hint style="info" %}
三種工具比較請參考：[MaiAgent 內建 AI 圖像生成工具](/build/tools/ai-image-generation-guide.md)
{% endhint %}

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-79b7d7d056695fd0b39063bb5214a57698409eb5%2Fai-image-tools-select-tools.png?alt=media" alt="選擇工具視窗中的 Gemini 3.1 Flash Image、GPT Image 2 圖片生成工具與 Gemini 3 Pro Image"><figcaption><p>「選擇工具」視窗中的圖像生成工具</p></figcaption></figure>

***

現在，您選擇的 Agent 已經擁有了使用這些已啟用工具的能力。在與該 Agent 互動時，如果觸發了相關的場景，AI 就會嘗試呼叫這些工具來完成任務或獲取信息。


---

# 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/build/tools/configure_tools.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.