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

# Agent UI

建立 Agent UI／FlexMessage（LINE Flex Message／Flex 卡片），綁定到 Agent，讓 Web Chat 回覆以資訊卡片呈現。

## <mark style="color:blue;">一、什麼是 Agent UI？</mark> <a href="#what-is-agent-ui" id="what-is-agent-ui"></a>

Agent UI 讓 Agent 在對話中呈現資訊卡片或互動選項。本頁介紹 **FlexMessage**：把文字、圖片與按鈕放在卡片中，讓使用者更容易閱讀資訊。

在 <mark style="color:blue;">新增 Agent UI</mark> 時，可以選擇 **FlexMessage**、[Quick Reply](/build/tools/agent-ui/quick-reply.md) 或 [快速選單](/build/tools/quick-menu.md)。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-4cb414d3dbbae7b27b0edeb25c0b1a65cb64f1f3%2Fagent-ui-prod-types.png?alt=media" alt="選擇 Agent UI 類型，顯示 FlexMessage 與快速選單"><figcaption><p>新增時先選擇要建立的類型</p></figcaption></figure>

### 使用情境 <a href="#live-demo" id="live-demo"></a>

客服主管想讓同事看懂收據卡片的呈現方式。她建立一張 <mark style="color:blue;">Receipt</mark> 模板卡片，保留虛構品項與金額，將卡片綁定到測試 Agent，再於 Web Chat 請 Agent 展示虛構示範收據。Agent 呼叫卡片工具後，對話中會出現品項、總額與付款編號，方便確認版面。

{% hint style="warning" %}
卡片模板與 AI 提示詞不會自動串接帳單、會員、訂房或掛號系統。若要展示真實即時資料，須先另外提供知識庫內容或配置可取得資料的工具；按鈕開啟連結，也不代表已完成付款或預約。下方收據為虛構模板資料。
{% endhint %}

## <mark style="color:blue;">二、卡片欄位與按鈕</mark> <a href="#how-it-works" id="how-it-works"></a>

卡片的欄位可設定 <mark style="color:blue;">預設值</mark>，也可以填入 <mark style="color:blue;">AI 提示詞</mark>，告訴 Agent 該欄位應呈現什麼內容。未設定 AI 提示詞的欄位使用預設值。

### 卡片按鈕可以做什麼？ <a href="#button-types" id="button-types"></a>

* **URL 按鈕**：開啟指定網址，例如商品說明頁。
* **Prompt 按鈕**：向 Agent 送出一則訊息，接續對話，例如「查看其他商品」。

按鈕的結果取決於連結目的地或 Agent 已配置的能力，請在正式提供給使用者前測試。

## <mark style="color:blue;">三、建立 Agent UI（FlexMessage）</mark> <a href="#create-agent-ui" id="create-agent-ui"></a>

{% stepper %}
{% step %}

### 1. 進入 Agent UI 頁面 <a href="#open-agent-ui" id="open-agent-ui"></a>

在左側選單點選 <mark style="color:blue;">AI 功能</mark> → <mark style="color:blue;">Agent UI</mark>，再點 <mark style="color:blue;">新增 Agent UI</mark>。選擇 **FlexMessage**，進入設定頁面。
{% endstep %}

{% step %}

### 2. 填寫基本資訊 <a href="#basic-information" id="basic-information"></a>

| 欄位       | 說明                                  |
| -------- | ----------------------------------- |
| **顯示名稱** | 後台用來識別卡片的名稱，例如「虛構收據卡」               |
| **工具名稱** | 供 AI 識別的英文名稱，例如 `demo_receipt_card` |
| **描述**   | 說明用途，例如「展示虛構示範收據」                   |
| **提示詞**  | 說明使用時機，例如「當使用者詢問虛構示範收據時，使用此卡片」      |

{% hint style="info" %}
工具名稱使用英文識別名稱，不要含空格或中文。提示詞寫明使用時機，較有助於 Agent 判斷何時呼叫卡片。
{% endhint %}
{% endstep %}

{% step %}

### 3. 選擇模板與設定欄位 <a href="#select-template" id="select-template"></a>

點選模板查看預覽，再點 <mark style="color:blue;">套用此模板</mark>。內建模板包括 Restaurant、Apparel、Hotel、Local Search、Real Estate、Social、TODO app、Transit、Receipt、Shopping、Menu 與 Ticket；也可選擇 <mark style="color:blue;">自訂</mark>，貼入 FlexMessage JSON。

套用後，在 <mark style="color:blue;">AI 欄位設定</mark> 調整 <mark style="color:blue;">預設值</mark> 與 <mark style="color:blue;">AI 提示詞</mark>。先用固定的虛構資料確認版面，再逐步加入需要動態生成的欄位。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-578eb72aa551ed3a36a68b0d368e47e9f09234a9%2Fagent-ui-prod-receipt-editor.png?alt=media" alt="Receipt 卡片編輯頁，包含基本資訊與卡片預覽"><figcaption><p>Receipt 卡片的基本資訊與預覽</p></figcaption></figure>
{% endstep %}

{% step %}

### 4. 儲存卡片 <a href="#save-agent-ui" id="save-agent-ui"></a>

點擊右上角 <mark style="color:blue;">儲存</mark>。完成後回到列表，可看到新建立的卡片。
{% endstep %}
{% endstepper %}

## <mark style="color:blue;">四、綁定到 Agent</mark> <a href="#bind-to-chatbot" id="bind-to-chatbot"></a>

{% stepper %}
{% step %}

### 1. 開啟 Agent 設定 <a href="#open-agent-settings" id="open-agent-settings"></a>

前往 <mark style="color:blue;">AI 功能</mark> → <mark style="color:blue;">AI 助理</mark>，開啟要設定的 Agent。請使用 <mark style="color:blue;">Agent 模式</mark>，才能配置 Agent UI。
{% endstep %}

{% step %}

### 2. 選擇卡片 <a href="#select-agent-ui" id="select-agent-ui"></a>

在設定頁點選 <mark style="color:blue;">Agent UI</mark>，再點 <mark style="color:blue;">選擇 Agent UI</mark>。勾選卡片後按 <mark style="color:blue;">確認</mark>；已加入的卡片會出現在 <mark style="color:blue;">已使用的 Agent UI</mark>。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-8de08b02a3ecee2058cd6963929c27eba89c8a16%2Fagent-ui-prod-binding.png?alt=media" alt="已使用的 Agent UI 顯示虛構收據卡與選擇 Agent UI 按鈕"><figcaption><p>確認卡片已加入 Agent</p></figcaption></figure>
{% endstep %}

{% step %}

### 3. 儲存與測試 <a href="#test-agent-ui" id="test-agent-ui"></a>

點擊 <mark style="color:blue;">儲存</mark>，再開啟此 Agent 的測試對話或 Web Chat。輸入「請展示虛構示範收據」，確認 Agent 呼叫卡片工具且卡片內容正確。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-09620aeaebbd7e0d88d59650c318c118d6efd645%2Fagent-ui-prod-receipt-chat.png?alt=media" alt="Web Chat 中的虛構 Receipt 卡片，顯示品項、總額與付款編號"><figcaption><p>Agent 在對話中呈現虛構收據卡片；金額只供示範</p></figcaption></figure>
{% endstep %}
{% endstepper %}

## <mark style="color:blue;">五、應用情境</mark> <a href="#use-case-examples" id="use-case-examples"></a>

可以將模板改成商品型錄、旅宿介紹、課程資訊或活動票券等資訊卡。先準備內容與可用連結，再設定卡片欄位與提示詞；若需要查詢庫存、訂單或預約狀態，先配置對應資料來源與工具。

一個 Agent 可以綁定多張卡片。請把每張卡片的使用時機寫清楚，並分別測試，確認 Agent 在對應問題下選用正確卡片。

## <mark style="color:blue;">六、Agent UI 提問工具（ask\_user\_question）</mark> <a href="#ask-user-question" id="ask-user-question"></a>

除了 FlexMessage 卡片，也可以使用 <mark style="color:blue;">Agent UI 提問工具</mark>，讓 Agent 列出選項供使用者回答。在 Agent 的 <mark style="color:blue;">工具</mark> 設定中加入此內建工具，操作方式見 [為 Agent 配置工具](/build/tools/configure_tools.md)。

Web Chat 的選項呈現方式由對話平台的 [提問集選項顯示模式](/build/conversation-settings/platform-settings/function-settings.md#ask-option-display-mode) 決定。

## <mark style="color:blue;">七、常見問題</mark> <a href="#faq" id="faq"></a>

<details>

<summary>卡片沒有出現怎麼辦？</summary>

確認 Agent 使用 Agent 模式、卡片已綁定並儲存，再檢查提示詞是否清楚描述使用時機。Agent 是否呼叫卡片仍依對話內容判斷，請用具體問題測試。

</details>

<details>

<summary>卡片會自己查詢外部系統嗎？</summary>

不會。卡片負責呈現內容；查詢外部系統需另外配置工具或資料來源，不能只在欄位提示詞寫「取得帳單」就完成串接。

</details>


---

# 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/agent-ui.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.