# Agent UI

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

傳統 AI 助理只能回覆純文字。**Agent UI** 讓你為 AI 助理設計視覺化的「資訊卡片」——當使用者提問時，AI 助理不只說話，還能直接送出結構清晰、帶圖片與按鈕的精美卡片。

目前支援的卡片格式為 **FlexMessage**，可在 Web Chat 及 LINE 頻道呈現豐富的卡片 UI。

{% hint style="success" %}
**Agent UI 的亮點：** AI 助理根據對話內容，自動判斷何時出牌、把對應的資訊填入卡片，使用者點卡片按鈕還可以繼續互動。
{% endhint %}

### 對比：純文字 vs. Agent UI 卡片 <a href="#comparison" id="comparison"></a>

| 場景       | 純文字回覆                                    | Agent UI 卡片回覆                                     |
| -------- | ---------------------------------------- | ------------------------------------------------- |
| 工業設備規格詢價 | 「IBX-7800 工業主機板，Intel i7、DDR5、NT$28,500」 | 規格表（處理器/I/O/工作溫度）+ 庫存標籤 + **立即詢價** / **下載規格書** 按鈕 |
| 信用卡對帳單查詢 | 「本期消費 $6,508，繳費截止 06/15」                 | 消費明細表 + 本期/回饋金/應繳金額 + **立即繳費** 按鈕                 |
| 看診預約確認   | 「心臟內科 06/03 14:00，掛號編號 R2026053-088」     | 醫師/時間/地點 + **報到 QR Code** + **查看候診進度** 按鈕         |
| 電子登機證    | 「JX 802 班機，TPE 09:25 → NRT 13:35，座位 12A」 | 航段/艙等/座位/行李 + **登機 QR Code** + **線上選位** 按鈕        |

### 實際對話效果 <a href="#live-demo" id="live-demo"></a>

無論是 B2B 製造業詢問產品規格、客戶查詢預約資訊，或是讓使用者直接在對話中查看登機證——AI 助理都能依對話情境自動回傳對應卡片，把資訊一次呈現清楚。

<figure><img src="/files/arO6mHEOYvUclS4AgtTU" alt="科技/電子製造業 產品卡"><figcaption><p>製造業範例：客戶問「推薦一張工業電腦主機板」，AI 助理回傳含處理器、I/O、工作溫度等規格與「立即詢價」按鈕的產品卡</p></figcaption></figure>

<figure><img src="/files/yewBnSyyp4gsiUBL50Zx" alt="醫療院所 預約確認卡片"><figcaption><p>醫療院所範例：使用者查詢看診資訊，AI 助理回傳含科別、時間、地點、QR Code 報到碼的預約確認卡，並提供「查看候診進度」按鈕</p></figcaption></figure>

<figure><img src="/files/BNAVsVdL0cm0JLOXbGqS" alt="航空業 電子登機證卡"><figcaption><p>航空業範例：使用者查詢航班資訊，AI 助理直接呈現含航段、艙等、座位、行李額度與登機 QR Code 的電子登機證卡</p></figcaption></figure>

更多產業情境請見下方「[五、應用範例：六大產業情境](#use-case-examples)」。

***

## <mark style="color:blue;">二、核心概念</mark> <a href="#core-concepts" id="core-concepts"></a>

### 固定欄位 vs. AI 動態生成 <a href="#fixed-vs-dynamic" id="fixed-vs-dynamic"></a>

每張卡片的每個欄位，都可以選擇「寫死預設值」或「讓 AI 從對話情境中即時填入」：

| 欄位                  | 設定方式            | 適用時機                                           |
| ------------------- | --------------- | ---------------------------------------------- |
| **固定值**（預設值）        | 你直接輸入固定文字       | 品牌名稱、卡片標題、固定標籤（如 `TRANSACTION`、`BOOKING PASS`） |
| **AI 動態生成**（AI 提示詞） | 用自然語言告訴 AI 要填什麼 | 客戶帳號末四碼、消費金額、本期應繳——任何需要從知識庫或對話抓取的資訊            |

**範例（金融對帳單卡片）：**

```
欄位            預設值（固定）         AI 提示詞（動態）
──────────────────────────────────────────────────────────
標題標籤        TRANSACTION（固定）    ─
卡片標題        信用卡對帳單（固定）   ─
對帳期間說明    ─                     從帳單資料庫取得對帳期間與卡號末四碼
消費明細列表    ─                     列出本期主要消費商家與金額
本期消費總額    ─                     從帳單資料庫取得本期消費總額
回饋金          ─                     從會員系統取得本期回饋金
應繳金額        ─                     計算本期消費扣除回饋金後的應繳金額
繳費截止日      ─                     從帳單資料庫取得繳費截止日
按鈕文字        立即繳費（固定）       ─
繳費連結        ─                     組合對帳單編號產生個人化繳費連結
```

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

FlexMessage 卡片支援兩種互動按鈕：

{% tabs %}
{% tab title="URL 按鈕" %}
點擊後直接開啟指定網址。

**應用場景：**

* 製造業：開啟產品技術規格書 PDF、預約 Demo 表單
* 金融業：跳轉到對帳單繳費頁、信用卡申辦表單
* 教育機構：開啟招生簡章、報名連結
* 醫療院所：查看候診進度、取消預約頁面
* 航空業：線上選位、加購行李或餐點

**設定方式：** 在「連結」欄位的 AI 提示詞填入「從知識庫取得該項目對應的頁面連結」，AI 自動帶入正確 URL。
{% endtab %}

{% tab title="Prompt 按鈕" %}
點擊後自動向 AI 助理發送一則訊息，AI 繼續接話。

**使用流程（以教育機構招生情境為例）：**

```
使用者：「介紹一下課程或招生資訊」
        ↓
AI 回傳課程進度卡（進行中課程 / 待繳作業 / 招生開放中）
        ↓
使用者點「立即報名」按鈕
        ↓  （按鈕觸發 prompt："我想報名暑期實習"）
AI 繼續接話：「請問你目前的學系與年級？預期實習領域是什麼？」
```

**應用場景：**

* 觸發後續流程（報名、預約、申辦、訂位）
* 詢問「查看完整明細」「查看其他房型」展開更多資訊
* 收集 AI 需要繼續服務的補充資訊
  {% endtab %}
  {% endtabs %}

***

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

{% stepper %}
{% step %}

### 進入 Agent UI 頁面

在左側選單點選 <mark style="color:blue;">AI 功能</mark> → <mark style="color:blue;">Agent UI</mark>，點擊右上角的 <mark style="color:blue;">新增 Agent UI</mark>。

<figure><img src="/files/K9k9nBKDqBsCMt660DSt" alt="Agent UI 列表頁"><figcaption><p>Agent UI 管理列表，顯示已建立的卡片工具及其關聯 AI 助理</p></figcaption></figure>
{% endstep %}

{% step %}

### 選擇卡片類型

目前提供 **FlexMessage 卡片資訊展示**，點選後進入設定頁面。

<figure><img src="/files/4mJsgbOzykfzSW94MyyK" alt="選擇 Agent UI 類型"><figcaption><p>選擇卡片類型，目前支援 FlexMessage</p></figcaption></figure>
{% endstep %}

{% step %}

### 填寫基本資訊

<figure><img src="/files/AKG5v7B9yhhH4iCugFBG" alt="FlexMessage 建立表單"><figcaption><p>填寫基本資訊後，即可選擇模板與設定 AI 欄位</p></figcaption></figure>

| 欄位       | 說明                                                                                                   |
| -------- | ---------------------------------------------------------------------------------------------------- |
| **顯示名稱** | 在管理後台顯示的名稱，方便識別（例：`金融/銀行/證券業 商品卡`）                                                                   |
| **工具名稱** | 供 AI 模型識別的英文名稱，命名規則：英文、底線，不含空格（例：`finance_product_card`、`medical_clinic_card`、`airline_flight_card`） |
| **描述**   | 說明此卡片工具的用途（選填）                                                                                       |
| **提示詞**  | 告訴 AI 助理何時應使用此卡片（例：「當使用者詢問信用卡對帳單、繳費資訊或本期消費明細時，回傳對帳單卡片」）                                              |

{% hint style="info" %}
**提示詞是觸發關鍵。** 寫得越具體，AI 越知道什麼時候要主動送出卡片，而不只是用文字回答。
{% endhint %}
{% endstep %}

{% step %}

### 選擇模板

點選左側預設模板，右側即時預覽卡片樣式；確認後點 <mark style="color:blue;">套用此模板</mark>。

**12 種內建模板與適用產業：**

| 模板           | 適用場景                  | 適合產業        |
| ------------ | --------------------- | ----------- |
| Restaurant   | 店家推薦、預約               | 餐飲、觀光       |
| Hotel        | 房型展示、訂房               | 飯店、旅宿       |
| Local Search | 地點搜尋、周邊推薦             | 觀光、零售       |
| Real Estate  | 物件介紹、看屋預約             | 房產、租賃       |
| Apparel      | 商品展示、規格介紹             | 零售、電商、製造業   |
| Transit      | 路線/航班/時刻              | 交通、航空、物流    |
| Shopping     | 商品比較、購物車              | 零售、電商       |
| Menu         | 品項展示、菜單               | 餐飲、零售       |
| Receipt      | 對帳單、訂單收據、消費明細         | 金融、零售、電商    |
| Ticket       | 票券、登機證、預約確認           | 航空、活動、醫療掛號  |
| Social       | 人物卡、社群檔案              | 教育、HR、社群    |
| TODO app     | 任務清單、課程進度、工單狀態        | 教育、客服、製造業工單 |
| **自訂**       | 貼入自訂 FlexMessage JSON | 任何需要客製版面的情境 |

{% hint style="info" %}
選擇模板只是起點，套用後可以在「AI 欄位設定」中任意調整每個欄位的內容與邏輯。
{% endhint %}
{% endstep %}

{% step %}

### 設定 AI 欄位

套用模板後，系統自動解析卡片中所有可編輯的欄位：

<figure><img src="/files/cPndANI4jpwQZEaDYek2" alt="AI 欄位設定"><figcaption><p>每個欄位可設定固定預設值，或填入 AI 提示詞讓 AI 動態生成內容</p></figcaption></figure>

每個欄位有三個屬性：

* **類型**：欄位的資料型別（文字、圖片、按鈕、連結）
* **預設值**：固定顯示的內容（若同時設定 AI 提示詞，AI 生成的內容優先）
* **AI 提示詞**：告訴 AI 這個欄位該填入什麼，例如「根據使用者查詢，從知識庫取得對應的產品名稱／帳戶資訊／科別」

右側**即時預覽**會隨設定更新，確認卡片視覺效果。
{% endstep %}

{% step %}

### 儲存

確認所有設定後，點擊右上角 <mark style="color:blue;">儲 存</mark>，Agent UI 工具即建立完成，可在列表中看到新增的項目。
{% endstep %}
{% endstepper %}

***

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

建立好 Agent UI 後，需要將它掛載到 AI 助理，AI 助理才知道可以使用這張卡片。

{% stepper %}
{% step %}

### 進入 AI 助理設定

前往 <mark style="color:blue;">AI 功能</mark> → <mark style="color:blue;">AI 助理</mark>，選擇要設定的 AI 助理，點選 <mark style="color:blue;">設定</mark>。
{% endstep %}

{% step %}

### 開啟 Agent UI 分頁

在設定頁面的分頁列中，點選 <mark style="color:blue;">Agent UI</mark>。

<figure><img src="/files/bjV5aZwdJ5nBFqaEpxLv" alt="AI 助理的 Agent UI 設定分頁"><figcaption><p>在 AI 助理的設定頁面中，可管理所有已綁定的 Agent UI 工具</p></figcaption></figure>
{% endstep %}

{% step %}

### 加入 Agent UI

點擊 <mark style="color:blue;">選擇 Agent UI</mark>，從清單中選取要加入的卡片工具。

* 一個 AI 助理可以綁定**多個** Agent UI
* 每個 Agent UI 的**提示詞**決定 AI 在哪種情況下使用哪張卡片
  {% endstep %}

{% step %}

### 儲存

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

***

## <mark style="color:blue;">五、應用範例：六大產業情境</mark> <a href="#use-case-examples" id="use-case-examples"></a>

從製造、金融、教育到醫療、服務、航空，每個產業都能依自身需求設計專屬卡片，讓 AI 助理用最直觀的方式回應使用者。以下是六種典型企業情境的實際對話效果。

{% hint style="info" %}
本節範例皆已在 MaiAgent 平台實際建立並測試。同一個 AI 助理可同時綁定多個 Agent UI，AI 會依使用者問題自動選用對應卡片。
{% endhint %}

### 多卡片同助理管理 <a href="#multi-card-management" id="multi-card-management"></a>

在管理後台一次設定多種產業情境，掛載到同一個 AI 助理：

<figure><img src="/files/Sm1VVvy6TWsGHhVqW4H9" alt="多產業 Agent UI 管理列表"><figcaption><p>同一個 AI 助理綁定六種產業卡片，AI 依使用者問題自動選用對應卡片</p></figcaption></figure>

### 範例設定教學：金融對帳單卡片 <a href="#example-finance-config" id="example-finance-config"></a>

下面以「金融業 對帳單查詢」為例，完整示範一張卡片從零設定到實際對話的流程。其他產業可比照辦理。

#### 情境說明 <a href="#example-scenario" id="example-scenario"></a>

一間銀行希望會員在 LINE 或 Web Chat 詢問本期帳單時，AI 助理直接回傳對帳單卡片（含消費明細、本期應繳金額、繳費截止日與「立即繳費」按鈕），而非單純文字回覆。

#### 設定內容 <a href="#example-config" id="example-config"></a>

**Agent UI 設定：**

| 欄位   | 設定                                  |
| ---- | ----------------------------------- |
| 顯示名稱 | 金融/銀行/證券業 商品卡                       |
| 工具名稱 | `finance_product_card`              |
| 提示詞  | 當使用者詢問本期消費、繳費資訊、信用卡帳單或對帳明細時，回傳對帳單卡片 |
| 模板   | Receipt                             |

**AI 欄位設定：**

| 欄位     | 預設值           | AI 提示詞             |
| ------ | ------------- | ------------------ |
| 標題標籤   | `TRANSACTION` | ─                  |
| 卡片標題   | 信用卡對帳單        | ─                  |
| 對帳期間說明 | ─             | 從帳單資料庫取得對帳期間與卡號末四碼 |
| 消費明細列表 | ─             | 列出本期主要消費商家與金額      |
| 本期消費總額 | ─             | 從帳單資料庫取得本期消費總額     |
| 回饋金    | ─             | 從會員系統取得本期回饋金       |
| 應繳金額   | ─             | 計算本期消費扣除回饋金後的應繳金額  |
| 繳費截止日  | ─             | 從帳單資料庫取得繳費截止日      |
| 對帳單編號  | ─             | 從帳單資料庫取得對帳單編號      |
| 按鈕文字   | 立即繳費          | ─                  |
| 繳費連結   | ─             | 組合對帳單編號產生個人化繳費連結   |

{% hint style="info" %}
**「固定值」vs.「AI 提示詞」的選擇邏輯：** 品牌標籤、按鈕文字等不會隨對話變動的內容用固定值；客戶帳號、消費金額、繳費連結等需從系統抓取的內容用 AI 提示詞。
{% endhint %}

#### 實際對話效果 <a href="#example-result" id="example-result"></a>

使用者提問後，AI 助理自動觸發卡片工具，從帳單資料庫與會員系統取得資料並填入欄位：

<figure><img src="/files/M3YYisPcRikImpljeHKM" alt="金融對帳單卡片 對話示範"><figcaption><p>使用者輸入「推薦一張信用卡或理財方案」（或「查我這期帳單」），AI 助理回傳含消費明細、應繳金額、繳費截止日的對帳單卡，使用者可點「立即繳費」直接完成繳費</p></figcaption></figure>

***

### 六大產業情境快覽 <a href="#case-overview" id="case-overview"></a>

掌握上方的設定邏輯後，可比照套用到不同產業。以下是六種典型情境：

### 1. 科技/電子製造業：產品型錄與規格詢價 <a href="#case-tech-electronics" id="case-tech-electronics"></a>

當客戶或業務詢問工業電腦、嵌入式系統、AOI 檢測設備等產品時，AI 助理自動回傳含完整規格、價格、庫存與「立即詢價／預約 Demo」按鈕的產品卡片，加速 B2B 銷售流程。

<figure><img src="/files/arO6mHEOYvUclS4AgtTU" alt="科技電子製造業產品卡"><figcaption><p>使用者：「推薦一張工業電腦主機板」— AI 助理回傳含處理器、I/O、工作溫度等完整規格的產品卡片</p></figcaption></figure>

### 2. 金融/銀行/證券業：對帳單與商品推薦 <a href="#case-finance" id="case-finance"></a>

對帳單、信用卡推薦、理財方案、保單查詢等金融場景，AI 助理可整合內部系統資料，回傳結構化的金融資訊卡與「立即繳費／申辦」CTA。

<figure><img src="/files/M3YYisPcRikImpljeHKM" alt="金融業 對帳單卡片"><figcaption><p>使用者：「推薦一張信用卡或理財方案」— AI 助理回傳含本期消費明細、回饋金、繳費截止日的對帳單卡，附「立即繳費」按鈕</p></figcaption></figure>

### 3. 教育機構：課程進度與招生報名 <a href="#case-education" id="case-education"></a>

學員可即時查詢課程進度、待繳作業、已完成成績與招生資訊，校方也能透過 AI 助理推播校內公告與報名連結。

<figure><img src="/files/AiokohGR9jfEjfrr3sy7" alt="教育機構 課程招生卡"><figcaption><p>使用者：「介紹一下課程或招生資訊」— AI 助理回傳含進行中課程、待繳作業、招生開放等多狀態的課程進度卡</p></figcaption></figure>

### 4. 醫療院所：預約掛號與門診資訊 <a href="#case-medical" id="case-medical"></a>

科別介紹、門診時段、預約掛號、QR Code 報到、衛教資訊等場景，讓病患直接在 LINE 或 Web Chat 完成預約並查看候診進度，減少電話客服負擔。

<figure><img src="/files/yewBnSyyp4gsiUBL50Zx" alt="醫療院所 預約確認卡"><figcaption><p>使用者：「看一下科別與門診時段」— AI 助理回傳含醫師、時間、地點、QR Code 的預約確認卡，提供「查看候診進度」與「取消預約」按鈕</p></figcaption></figure>

### 5. 服務/飯店業：訂房訂位與行銷推薦 <a href="#case-hotel-service" id="case-hotel-service"></a>

房型推薦、餐廳訂位、活動報名、會員權益等服務業場景，用視覺卡片呈現價格、評分、特惠與訂購 CTA，提升轉換率。

<figure><img src="/files/u3l85PuyTsQdp2kgqyfP" alt="服務/飯店業 推薦卡"><figcaption><p>使用者：「推薦飯店或訂位資訊」— AI 助理同時回傳房型與餐廳推薦，含評分、限時特惠、訂房／訂位按鈕</p></figcaption></figure>

### 6. 航空業：航班資訊與電子登機證 <a href="#case-airline" id="case-airline"></a>

航班查詢、艙等比較、行李規定、線上選位等場景，AI 助理可直接呈現電子登機證 QR Code、座位、行李額度等關鍵資訊，無需另外開啟 App。

<figure><img src="/files/BNAVsVdL0cm0JLOXbGqS" alt="航空業 電子登機證卡"><figcaption><p>使用者：「查詢航班與機位資訊」— AI 助理回傳含 TPE→NRT 航段、座位、行李額度與登機 QR Code 的電子登機證卡</p></figcaption></figure>

***

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

<details>

<summary>工具名稱有什麼命名限制？</summary>

工具名稱是 AI 模型識別此工具的唯一標識，必須：

* 使用英文字母
* 可包含底線（`_`）
* 不可含空格或中文
* 建議用描述性名稱，例如 `finance_statement_card`、`medical_clinic_card`、`airline_flight_card`

</details>

<details>

<summary>提示詞要怎麼寫才有效？</summary>

提示詞告訴 AI「什麼時候」要使用這張卡片。建議寫成具體的觸發條件：

**較模糊（效果差）：** 「需要時使用」

**較具體（效果好）：**

* 「當使用者詢問工業電腦、嵌入式系統、檢測設備等規格或報價時，回傳產品型錄卡片」
* 「使用者問到本期消費、繳費截止日或對帳單明細時，使用對帳單卡片」
* 「當需要展示班機、艙等、座位或登機資訊時，以電子登機證卡片呈現」

</details>

<details>

<summary>AI 欄位的 AI 提示詞沒填，欄位會顯示什麼？</summary>

若某欄位只填了「預設值」，AI 不會動態生成內容，直接顯示預設值。若兩者都沒填，該欄位顯示為空白。建議至少填入預設值，避免卡片出現空白欄位。

</details>

<details>

<summary>一個 AI 助理可以同時掛多個 Agent UI 嗎？</summary>

可以。AI 助理會根據每個 Agent UI 的「提示詞」判斷在當前對話中應使用哪張卡片。建議每個 Agent UI 的提示詞寫得清楚且不互相重疊，以避免 AI 選錯卡片。

</details>

<details>

<summary>Agent UI 可以用在 LINE 頻道嗎？</summary>

FlexMessage 原生支援 LINE 的卡片格式，在 LINE 頻道中呈現效果與 Web Chat 相同，都是完整的視覺化卡片。請確認 AI 助理已關聯 LINE 對話平台，並完成 LINE 頻道設定。

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maiagent.ai/tools/agent-ui.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.