# AI 助理優化顧問

## 概述

當 AI 助理出現回答不準確、格式錯誤、腦補資訊等問題時，通常需要人工逐筆檢查對話紀錄來定位問題。**優化助理**能自動完成這個診斷流程：

1. 自動取得對話紀錄、AI 回覆與知識庫檢索結果
2. 判斷問題屬於 **Prompt 問題**（AI 拿到對的資料但回答錯）還是**知識庫文件問題**（AI 沒拿到對的資料）
3. 產出具體的修改建議，含 Before / After 對照

### 組成元件

| 元件         | 說明                                |
| ---------- | --------------------------------- |
| **AI 助理**  | 作為優化顧問的載體，使用 Agent 模式             |
| **角色指令**   | 定義診斷流程、分析原則、輸出格式                  |
| **MCP 工具** | 讓優化助理能呼叫 MaiAgent API，查詢對話紀錄和助理配置 |
| **知識庫**    | 綁定目標助理所使用的知識庫，用於驗證 RAG 檢索結果       |

***

## 前置準備

| 項目       | 說明            | 如何取得                 |
| -------- | ------------- | -------------------- |
| 要分析的助理   | 希望優化的目標 AI 助理 | 管理後台 → AI 助理列表       |
| 目標助理的知識庫 | 目標助理所掛載的知識庫   | 點入目標助理 → 知識庫頁籤       |
| API Key  | 用於 MCP 工具認證   | 個人資料 → API 金鑰（見下方說明） |

***

## Step 1：建立 AI 助理

1. 左側選單 → <mark style="color:blue;">AI 助理</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-3c9b2e35a8eec02af8922463ca403e02c2bc3327%2Foptimizer-chatbot-list.png?alt=media" alt=""><figcaption><p>AI 助理列表頁面 — 點擊「建立 AI 助理」</p></figcaption></figure>

2. 填寫基本設定：

| 欄位         | 建議值                                |
| ---------- | ---------------------------------- |
| **名稱**     | `優化助理` 或 `AI 助理優化顧問`               |
| **LLM 模型** | Claude Sonnet 4.6 或以上（需要較強的分析推理能力） |

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-c0e809ef540ba9da47d1ee8241aaebbe0f1f32be%2Foptimizer-step1-basic.png?alt=media" alt=""><figcaption><p>基本設定 — 填寫名稱並選擇 Claude 4.6 Sonnet 模型</p></figcaption></figure>

3. 切換到 <mark style="color:blue;">回答模式設定</mark> tab，選擇 <mark style="color:blue;">Agent 模式</mark>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-12bd3c879c67584006efb1969c8f120a88dbc0d9%2Foptimizer-step2-agent-mode.png?alt=media" alt=""><figcaption><p>回答模式設定 — 必須選擇 Agent 模式才能使用 MCP 工具</p></figcaption></figure>

{% hint style="danger" %}
**回答模式必須設為 Agent 模式**。RAG 問答模式無法使用 MCP 工具，會導致優化助理無法查詢對話紀錄和助理配置。
{% endhint %}

4. 點擊 <mark style="color:blue;">儲存</mark>

***

## Step 2：設定角色指令

1. 在同一頁的 <mark style="color:blue;">回答模式設定</mark> tab 中，找到下方的**角色指令**區域
2. 將以下標準版角色指令完整貼入

{% hint style="info" %}
角色指令是優化助理的核心，定義了診斷流程、七大優化原則和輸出格式。建議直接使用標準版，不做修改。
{% endhint %}

<details>

<summary>點擊展開：標準版角色指令</summary>

```
# 角色定位

你是「AI 助理優化顧問」，負責診斷 MaiAgent 平台上 AI 助理的回答品質，並提供 Prompt 或知識庫文件的調整建議。

你的技術基礎是 RAG（Retrieval-Augmented Generation）：AI 助理從知識庫檢索相關內容，再基於檢索結果回答用戶。因此問題只有兩種來源：
1. **Prompt 問題** — AI 拿到對的資料但回答錯
2. **知識庫文件問題** — AI 沒拿到對的資料

---

# 診斷流程

## Step 1：收集資訊

用戶提供 conversation_id 後，依序執行：

1. 使用 MaiAgent API 工具，以 conversation_id 查詢訊息列表，找到 recordId
2. 用 recordId 取得對話紀錄詳情（含 citationNodes、context、評分）
3. 從紀錄中的 chatbot.id 取得被分析助理的 Prompt（instructions + skills）
4. 如有 skills，逐一取得 skill 指令

**必須全部取得後才進入診斷。**

## Step 2：展示診斷摘要

**被分析助理**：[chatbot.name]（模型：[llm.name]）
**用戶問題**：[inputMessage]
**AI 回覆摘要**：[outputMessage 前 200 字]
**檢索到的來源**：[citationNodes 的 fileName 列表]
**評分**：忠實度 [X] / 回答相關性 [X] / 參考資料相關性 [X]
**診斷結果**：[Prompt 問題 / 知識庫文件問題 / 知識庫缺漏]

## Step 3：問題分類

**Q1：citationNodes 中是否包含正確答案？**
- 是 → **Prompt 問題**
- 否 → 繼續 Q2

**Q2：知識庫中是否存在正確答案？**
- 是，但 AI 沒檢索到 → **知識庫文件問題**
- 否 → 告知用戶需要**新增知識庫內容**

---

# 七大優化原則

| # | 原則 | 核心概念 |
|---|-----|---------|
| 1 | 限制知識來源 | 「只能使用...不得使用...」 |
| 2 | 強制引用 | 「必須標註來源」 |
| 3 | 授權拒答 | 「你可以說不知道」+ 標準話術 |
| 4 | 明確流程 | 「步驟 1...步驟 2...」 |
| 5 | 絕對禁區 | 「絕對禁止」「嚴禁」 |
| 6 | Fallback 機制 | 「以下情況必須轉人工」 |
| 7 | 結構化格式 | XML 標籤或明確分隔符 |
```

</details>

3. 點擊 <mark style="color:blue;">儲存</mark>

***

## Step 3：建立 MCP 工具

MCP 工具讓優化助理能查詢 MaiAgent API，取得對話紀錄和助理配置。

1. 左側選單 → <mark style="color:blue;">工具</mark> → 點擊右上角 <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-d12d21bfefba59122fdd910b1550be39d223e093%2Foptimizer-step3-new-tool.png?alt=media" alt=""><figcaption><p>新增工具彈窗（預設為 API 類型）</p></figcaption></figure>

2. 將 <mark style="color:blue;">工具類型</mark> 從 API 切換為 <mark style="color:blue;">MCP</mark>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-6cd940bf2494048a44ecceff61da87ff3a3b32ad%2Foptimizer-step3-mcp-form.png?alt=media" alt=""><figcaption><p>選擇 MCP 類型 — 表單顯示 MCP 配置區域</p></figcaption></figure>

3. 填寫以下設定：

| 欄位           | 值                             |
| ------------ | ----------------------------- |
| **顯示名稱**     | `MaiAgent API`                |
| **描述**       | `AI 回覆分析工具`                   |
| **MCP 工具網址** | `https://mcp.maiagent.ai/mcp` |

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-a68428d6ebc79575b2d0cfabed8470c587f701a4%2Foptimizer-step3-mcp-edit-top.png?alt=media" alt=""><figcaption><p>填入 MCP URL 後，系統會自動偵測可用的工具</p></figcaption></figure>

4. 建立完成後，進入助理設定 → <mark style="color:blue;">工具</mark> tab，可看到已綁定的 MCP 工具

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-c9378cd5daa1442adab6924d340f598d56a84a96%2Foptimizer-step3-tools-empty.png?alt=media" alt=""><figcaption><p>助理工具頁籤 — 已綁定 MaiAgent API (optimizer) MCP 工具</p></figcaption></figure>

3. **認證標頭（MCP Headers）** — 填入以下 JSON：

```json
{
  "Authorization": "Api-Key {您的 API Key}"
}
```

{% hint style="info" %}
**如何取得 API Key？**

點擊右上角頭像 → <mark style="color:blue;">個人資料</mark> → 切換到 <mark style="color:blue;">API 金鑰</mark> 頁籤 → 點擊 <mark style="color:blue;">建立新金鑰</mark>，複製產生的 API Key。

<img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-9a41e29e6db6e3e6327fd4b6d4f032cf055e46bc%2Foptimizer-api-key.png?alt=media" alt="個人資料 → API 金鑰頁籤" data-size="original">
{% endhint %}

{% hint style="danger" %}
API Key 建立後只會顯示一次，請立即複製並妥善保存。
{% endhint %}

4. **允許的工具（Allowed Tools）** — 勾選以下 5 個：

| 工具                    | 用途          |
| --------------------- | ----------- |
| `debug_auth`          | 驗證認證是否正確    |
| `list_api_categories` | 列出 API 分類   |
| `search_apis`         | 搜尋 API 端點   |
| `get_api_details`     | 取得 API 詳細規格 |
| `call_api`            | 執行 API 呼叫   |

5. **Tool Prompt** — 將以下內容完整貼入：

<details>

<summary>點擊展開：標準版 Tool Prompt</summary>

```
MaiAgent 平台 API 呼叫工具。用於查詢對話紀錄、取得助理配置、讀取知識庫內容。

## 核心操作流程

### Step 1：從 conversation_id 找到 recordId
call_api(operation_id: 'v1MessagesList', query_params: { conversation: '<conversation_id>', pageSize: 50 })

### Step 2：取得對話紀錄詳情
call_api(operation_id: 'v1RecordsRetrieve', path_params: { id: '<record_id>' })

### Step 3：取得被分析助理的 Prompt
call_api(operation_id: 'v1ChatbotsRetrieve', path_params: { id: '<chatbot_id>' })

### Step 4：取得 Skill 指令（如有 skills）
call_api(operation_id: 'v1SkillsRetrieve', path_params: { id: '<skill_id>' })

### Step 5（選用）：取得 TextNode 詳情
call_api(operation_id: 'v1ChatbotTextNodesRetrieve', path_params: { id: '<textnode_id>' })

Step 1~4 必須依序執行，每步的輸出是下步的輸入。
```

</details>

6. 點擊 <mark style="color:blue;">儲存</mark>

***

## Step 4：綁定知識庫

優化助理需要綁定**目標助理所使用的知識庫**，才能在診斷時驗證 RAG 檢索結果。

1. 切換到 <mark style="color:blue;">知識庫設定</mark> tab

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-2f20c2c9709983362bbffa3bb4b0e9830f095218%2Foptimizer-kb-tab.png?alt=media" alt=""><figcaption><p>知識庫設定 — 選擇目標助理所使用的知識庫</p></figcaption></figure>

2. 點擊 <mark style="color:blue;">新增知識庫</mark>，勾選目標助理所使用的所有知識庫
3. 點擊 <mark style="color:blue;">儲存</mark>

{% hint style="info" %}
如果要分析多個 AI 助理，將所有助理的知識庫都綁定到優化助理即可。建議在「進階設定」中將檢索 chunks 數量設為 **12**。
{% endhint %}

***

## Step 5：驗證設定

### 驗證 MCP 工具連線

在優化助理的對話框中輸入：

```
請驗證 MCP 工具連線是否正常
```

優化助理應成功呼叫 `debug_auth`，回傳認證資訊。

### 驗證診斷功能

從目標助理的對話紀錄中取得一個 conversation\_id：

1. 進入 <mark style="color:blue;">所有對話</mark> 頁面
2. 點入任一筆對話，網址列中的 ID 即為 conversation\_id

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-39ef51e3fc2178398f6f06ad74a061225ef7a0af%2Foptimizer-conversation-list.png?alt=media" alt=""><figcaption><p>所有對話頁面 — 點入對話，從網址列取得 conversation_id</p></figcaption></figure>

在優化助理中輸入：

```
請分析這筆對話：{conversation_id}
```

優化助理會自動依序執行以下步驟：

1. 搜尋可用的 API 工具（`search_apis`）
2. 呼叫 `v1MessagesList` 查詢對話訊息
3. 呼叫 `v1RecordsRetrieve` 取得對話紀錄詳情
4. 呼叫 `v1ChatbotsRetrieve` 取得被分析助理的 Prompt
5. 產出完整的診斷摘要與修改建議

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-a0164708f6b873d6dc31bbe354c63b68c847d182%2Foptimizer-test-result.png?alt=media" alt=""><figcaption><p>優化助理實際運作畫面 — 自動搜尋 API 並依序呼叫工具取得對話紀錄</p></figcaption></figure>

***

## 使用教學

### 用 conversation\_id 分析

```
請分析這筆對話：abc123-def456-ghi789
```

優化助理會自動取得對話紀錄、AI 回覆、知識庫檢索結果與助理 Prompt，產出完整的診斷報告。

### 直接貼文字分析

若沒有 conversation\_id，可直接提供：

```
請幫我分析以下問題：

【用戶問題】如何申請信用卡掛失？
【AI 回覆】（貼上 AI 的實際回覆）
【問題描述】AI 多提到了不存在的「線上掛失」功能
```

### 診斷結果解讀

| 診斷類型          | 意思                | 下一步              |
| ------------- | ----------------- | ---------------- |
| **Prompt 問題** | AI 拿到對的資料但回答方式有問題 | 按建議修改角色指令或 Skill |
| **知識庫文件問題**   | 文件結構導致 AI 檢索到錯誤內容 | 按建議改寫知識庫文件       |
| **知識庫缺漏**     | 知識庫根本沒有相關內容       | 需要新增知識庫文件        |

***

## 常見問題

{% hint style="info" %}
**Q：MCP 工具連線失敗怎麼辦？**

1. 確認回答模式為 **Agent 模式**（最常見原因）
2. 確認 API Key 有效且未過期
3. 確認 MCP URL 為 `https://mcp.maiagent.ai/mcp`
4. 確認 Headers 使用 `Api-Key` 格式（如：`Api-Key xxxxxxxx.xxxxxxxx`）

**Q：一個優化助理可以分析多個助理嗎？** 可以。只要 API Key 屬於同一組織，且已綁定所有目標助理的知識庫。

**Q：需要為每個客戶分別建立嗎？** 是。每個客戶組織需要獨立的優化助理，因為 API Key 和知識庫是組織專屬的。
{% endhint %}

***

## 設定速查表

* [ ] 建立 AI 助理（名稱：優化助理）
* [ ] 選擇模型（Claude Sonnet 4.6 或以上）
* [ ] **設為 Agent 模式**
* [ ] 貼入標準版角色指令
* [ ] 建立 MCP 工具
  * [ ] MCP URL：`https://mcp.maiagent.ai/mcp`
  * [ ] Headers：API Key
  * [ ] 勾選 5 個 Allowed Tools
  * [ ] 貼入標準版 Tool Prompt
* [ ] 綁定目標助理的知識庫
* [ ] 驗證 MCP 連線
* [ ] 驗證診斷功能