> 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/tool-display-settings.md).

# 自訂工具訊息顯示

工具執行時對話中顯示的狀態文案（執行中、完成、失敗、沒有結果），以及如何自訂 API、MCP 與 Function 工具的文案、詳細程度與結果格式。

當 Agent 呼叫工具時，您可以決定對話中要顯示多少執行資訊，也可以把工具回傳結果整理成容易閱讀的格式。這些設定適用於 API、MCP 與 Function 工具。

{% hint style="info" %}
具有該工具編輯權限的成員，可以編輯顯示文案、顯示模式與輸出渲染模板；沒有編輯權限時，這些設定會以唯讀方式顯示。
{% endhint %}

## 使用情境 <a href="#use-case" id="use-case"></a>

客服主管建立了一個查詢試用申請的 API 工具，希望客服人員能看見查詢進度，但不需要展開所有技術細節。她在工具的「顯示文案」頁籤選擇「精簡」，並設定完成時顯示的文字。之後 Agent 呼叫工具時，客服人員會看見簡短的執行狀態，而不是完整的工具輸入與輸出。

## 對話中的工具狀態 <a href="#tool-status" id="tool-status"></a>

Agent 呼叫工具時，對話中的工具卡會依執行進度顯示一句狀態文案。沒有工具自訂文案時，系統會先使用組織設定的工具類別文案；組織也沒有設定時，才顯示平台預設文案：

| 狀態   | 什麼時候出現                          | 平台預設文案範例       |
| ---- | ------------------------------- | -------------- |
| 執行中  | 工具開始執行                          | 正在搜尋知識庫：退貨流程   |
| 完成   | 工具執行完成                          | 已搜尋知識庫 · 3 個來源 |
| 失敗   | 工具回傳錯誤                          | 知識庫搜尋失敗        |
| 沒有結果 | 知識庫查詢、網頁搜尋、資料庫查詢、檔案處理類的工具找到 0 筆 | 知識庫搜尋沒有結果      |

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-7245910d44c1ddc2ecd2e3cc0c5f97e495995763%2Ftool-status-copy-kb-result.png?alt=media" alt="Web Chat 回覆上方的工具狀態顯示「已搜尋知識庫 · 3 個來源」"><figcaption><p>知識庫查詢完成後，狀態文案附上找到的來源數</p></figcaption></figure>

平台預設文案有以下規則：

* **跟著對話語言顯示**：狀態文案以對話的語言顯示，例如 Web Chat 訪客使用英文介面時會看到「Searched the knowledge base · 5 sources」。對話沒有帶語言資訊時（例如 LINE），系統會依使用者訊息的文字判斷中文、日文、韓文或泰文。
* **執行中附上查詢主詞**：冒號後會帶出這次查詢的內容，例如搜尋關鍵字、網址或檔名；內容過長時會截斷。只取與查詢有關的輸入欄位，其他輸入不會顯示在狀態文案中。
* **完成時附上結果摘要**：能計算筆數時，會在「·」後附上結果數，例如「7 筆結果」「3 個來源」；工具只回傳一段文字時，只顯示完成文案。
* **一般工具顯示工具名稱**：工具類別為「其他」或「第三方整合」時，文案會帶出工具的顯示名稱，例如「正在使用 訂單查詢」「已使用 訂單查詢」。

各類別的平台預設文案可在[回覆等待樣式](/build/conversation-settings/platform-settings/loading-display.md#tool-category-copy)查看，組織也可以在該頁依類別覆寫。

## 設定顯示方式 <a href="#configure-display" id="configure-display"></a>

{% stepper %}
{% step %}

### 開啟工具編輯視窗 <a href="#open-tool-editor" id="open-tool-editor"></a>

從左側選單進入 <mark style="color:blue;">AI 功能</mark> → <mark style="color:blue;">工具</mark>。在工具列表找到要設定的工具，點擊右側的編輯圖示。
{% endstep %}

{% step %}

### 進入顯示文案頁籤 <a href="#open-display-copy" id="open-display-copy"></a>

在「編輯工具」視窗選擇 <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-ba75d806ec4e5b77dbc50734491123d9fef655a1%2Ftool-display-settings-prod.png?alt=media" alt="工具編輯視窗的顯示文案頁籤，包含顯示文案、顯示模式與輸出渲染模板"><figcaption><p>工具的顯示文案與顯示模式設定</p></figcaption></figure>
{% endstep %}

{% step %}

### 選擇顯示模式 <a href="#choose-display-mode" id="choose-display-mode"></a>

依對話使用者需要看到的資訊量，選擇一種模式：

| 模式       | 對話中的效果                  |
| -------- | ----------------------- |
| 跟隨對話平台設定 | 沿用對話平台的預設顯示方式；目前預設為「完整」 |
| 完整       | 顯示工具執行的完整資訊             |
| 精簡       | 只顯示精簡的執行資訊              |
| 隱藏       | 不顯示工具執行區塊               |

{% hint style="warning" %}
「隱藏」只會隱藏對話中的工具執行區塊，不會停用工具。若要阻止 Agent 呼叫工具，請到 Agent 的「工具」設定取消配置該工具。
{% endhint %}
{% endstep %}

{% step %}

### 自訂顯示文案 <a href="#customize-display-copy" id="customize-display-copy"></a>

在「顯示文案」區域點擊 <mark style="color:blue;">新增</mark>，選擇語系後填寫 <mark style="color:blue;">執行中文案</mark> 與 <mark style="color:blue;">完成後文案</mark>。文案中可使用變數帶入工具名稱、查詢主詞、結果摘要或工具輸入參數，詳見[在自訂文案中使用變數](#copy-variables)。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-207265c0bf67556320dd85f36ba2fe2ce66cd6d9%2Ftool-status-copy-custom-template.png?alt=media" alt="顯示文案頁籤的繁體中文文案：執行中文案與完成後文案都使用變數帶入訂單編號"><figcaption><p>在顯示文案中用變數帶入訂單編號與結果摘要</p></figcaption></figure>
{% endstep %}

{% step %}

### 設定輸出渲染模板 <a href="#configure-output-template" id="configure-output-template"></a>

若要整理工具回傳內容，在「輸出渲染模板」區域點擊 <mark style="color:blue;">新增</mark>。模板可使用 `{{output}}` 帶入完整工具結果，或用 `{{變數}}` 帶入工具輸入的第一層參數。找不到變數時會顯示空字串；模板留空時則會顯示原始 JSON。

完成後點擊 <mark style="color:blue;">確認</mark> 儲存。
{% endstep %}
{% endstepper %}

## 在自訂文案中使用變數 <a href="#copy-variables" id="copy-variables"></a>

客服主管把訂單查詢 API 工具配置給客服 Agent，希望客戶查詢時能看到正在查哪一張訂單。她在工具的「顯示文案」新增繁體中文，執行中文案填 `正在查詢訂單 {{orderId}}`，完成後文案填 `已查到訂單 {{orderId}} · {{result}}`。客戶詢問訂單 A1024 時，工具卡先顯示「正在查詢訂單 A1024」，完成後顯示「已查到訂單 A1024」；這支工具的回傳沒有可計算的筆數，所以結果摘要留空，後面的「·」也一併省略。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-3eeb7c512c977486db54143528a1ff855816ee7c%2Ftool-status-copy-custom-running.png?alt=media" alt="對話中的工具步驟顯示「正在查詢訂單 A1024」"><figcaption><p>執行中：帶入工具輸入的訂單編號</p></figcaption></figure>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-147abac6d4696014ee24ac6218e6b241dbffb29f%2Ftool-status-copy-custom-completed.png?alt=media" alt="展開的步驟清單中，工具步驟顯示「已查到訂單 A1024」"><figcaption><p>完成後：結果摘要為空時，分隔符號一併省略</p></figcaption></figure>

自訂文案（工具的「顯示文案」與回覆等待樣式的工具類別文案表）可使用以下變數：

| 變數            | 帶入內容                                    |
| ------------- | --------------------------------------- |
| `{{tool}}`    | 工具的顯示名稱                                 |
| `{{subject}}` | 這次查詢的主詞，例如搜尋關鍵字、網址或檔名                   |
| `{{result}}`  | 結果摘要，例如「7 筆結果」；只在完成狀態有值                 |
| `{{參數名稱}}`    | 工具輸入的第一層參數，例如 `{{query}}`、`{{orderId}}` |

* 變數沒有值時顯示為空字串，緊鄰的「：」「·」或空括號會一起移除。
* 自訂文案會照您寫的內容顯示，系統不會自動在後面附上主詞或結果數；需要時請自行放入 `{{subject}}` 或 `{{result}}`。
* 自訂文案依對話語言挑選；該語言沒有填寫時改用預設語系（英文）的自訂文案，兩者都沒有時，先使用組織設定的工具類別文案（同樣先找對話語言，再找預設語系），仍沒有才顯示平台預設文案。例如工具只填繁體中文時，英文對話會先使用組織設定的英文類別文案；組織未設定時才顯示英文的平台預設文案。
* 「顯示文案」只能設定執行中與完成後兩種文案。工具找到 0 筆時沿用完成後文案；工具執行失敗時，先使用組織設定的該類別失敗文案；組織未設定時才顯示平台預設失敗文案。

## 選擇模式的建議 <a href="#mode-guidance" id="mode-guidance"></a>

* 工具結果需要供使用者核對時，選擇「完整」。
* 使用者只需要知道系統正在處理時，選擇「精簡」並搭配清楚的顯示文案。
* 執行細節不適合出現在對話中時，選擇「隱藏」。

設定完成後，建議將工具配置給測試用 Agent 並實際發送一次問題，確認文案與輸出模板符合工具真正回傳的欄位。

## MCP 互動卡片（MCP Apps） <a href="#mcp-apps" id="mcp-apps"></a>

有些 MCP 伺服器除了回傳資料，還會附上一份互動介面，Agent 呼叫後對話中會出現一張可直接操作的卡片。卡片不受上方「顯示模式」影響：即使選擇「隱藏」，互動卡片仍會顯示。卡片的呈現方式、條件、安全限制與常見問題見 [MCP 互動卡片（MCP Apps）](/build/tools/mcp-apps.md)。


---

# 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/tool-display-settings.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.