# AI 助理優化顧問

## 概述 <a href="#overview" id="overview"></a>

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

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

### 組成元件 <a href="#components" id="components"></a>

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

***

## 前置準備 <a href="#prerequisites" id="prerequisites"></a>

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

***

## Step 1：建立 AI 助理 <a href="#step1-create-ai-agent" id="step1-create-ai-agent"></a>

1. 左側選單 → <mark style="color:blue;">AI 助理</mark> → 點擊 <mark style="color:blue;">建立 AI 助理</mark>

<figure><img src="/files/6R4pb0suH3sO4k9bjC7Z" alt=""><figcaption><p>AI 助理列表頁面 — 點擊「建立 AI 助理」</p></figcaption></figure>

2. 填寫基本設定：

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

<figure><img src="/files/l6ajgTXfyOuF1k94am2O" 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="/files/3PNx63N1oITP3YvQZDTP" alt=""><figcaption><p>回答模式設定 — 必須選擇 Agent 模式才能使用 MCP 工具</p></figcaption></figure>

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

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

***

## Step 2：設定角色指令 <a href="#step2-configure-system-prompt" id="step2-configure-system-prompt"></a>

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 工具 <a href="#step3-create-mcp-tools" id="step3-create-mcp-tools"></a>

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

1. 左側選單 → <mark style="color:blue;">工具</mark> → 點擊右上角 <mark style="color:blue;">新增工具</mark>

<figure><img src="/files/l2E3jIyD7vCEcCQzixjU" alt=""><figcaption><p>新增工具彈窗（預設為 API 類型）</p></figcaption></figure>

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

<figure><img src="/files/dCeSdY6BA1iLMNlBYlOo" alt=""><figcaption><p>選擇 MCP 類型 — 表單顯示 MCP 配置區域</p></figcaption></figure>

3. 填寫以下設定：

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

<figure><img src="/files/ndqsPmCTgwlm17iOATAj" alt=""><figcaption><p>填入 MCP URL 後，系統會自動偵測可用的工具</p></figcaption></figure>

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

<figure><img src="/files/UT0YQwzAH4W6ILhubseY" 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="/files/KMl5Y8UIscg9z4O51mxJ" 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：綁定知識庫 <a href="#step4-bind-knowledge-base" id="step4-bind-knowledge-base"></a>

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

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

<figure><img src="/files/ngQswdrzoWpx1Xhg51I9" 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：驗證設定 <a href="#step5-verify-configuration" id="step5-verify-configuration"></a>

### 驗證 MCP 工具連線 <a href="#verify-mcp-tool-connection" id="verify-mcp-tool-connection"></a>

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

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

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

### 驗證診斷功能 <a href="#verify-diagnostic-function" id="verify-diagnostic-function"></a>

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

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

<figure><img src="/files/SdqYAyrnD2dJXgsKTsuA" 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="/files/k0BiE4EQ2Wbs2FGmeMvJ" alt=""><figcaption><p>優化助理實際運作畫面 — 自動搜尋 API 並依序呼叫工具取得對話紀錄</p></figcaption></figure>

***

## 使用教學 <a href="#usage-guide" id="usage-guide"></a>

### 用 conversation\_id 分析 <a href="#analyze-by-conversation-id" id="analyze-by-conversation-id"></a>

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

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

### 直接貼文字分析 <a href="#analyze-by-pasting-text" id="analyze-by-pasting-text"></a>

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

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

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

### 診斷結果解讀 <a href="#interpret-diagnostic-results" id="interpret-diagnostic-results"></a>

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

***

## 常見問題 <a href="#faq" id="faq"></a>

{% 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 %}

***

## 設定速查表 <a href="#quick-reference" id="quick-reference"></a>

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


---

# 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/application/optimizer-assistant.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.