應用實例：Agent 優化顧問

建立 Agent 優化顧問，自動診斷 AI 回答品質問題並提供 Prompt 與知識庫文件的調整建議

概述

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

1. 自動取得對話紀錄、AI 回覆與知識庫檢索結果

2. 判斷問題屬於 Prompt 問題（AI 拿到對的資料但回答錯）還是知識庫文件問題（AI 沒拿到對的資料）

3. 產出具體的修改建議，含 Before / After 對照

組成元件

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

---

前置準備

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

---

Step 1：建立 Agent

1. 左側選單 → AI 助理 → 點擊 建立 AI 助理

2. 填寫基本設定：

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

1. 切換到 回答模式設定 tab，選擇 Agent 模式

回答模式必須設為 Agent 模式。RAG 問答模式無法使用 MCP 工具，會導致優化助理無法查詢對話紀錄和 Agent 配置。

1. 點擊 儲存

---

Step 2：設定角色指令

1. 在同一頁的 回答模式設定 tab 中，找到下方的角色指令區域

2. 將以下標準版角色指令完整貼入

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

點擊展開：標準版角色指令

# 角色定位

你是「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 標籤或明確分隔符 |

1. 點擊 儲存

---

Step 3：建立 MCP 工具

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

1. 左側選單 → 工具 → 點擊右上角 新增工具

2. 將 工具類型 從 API 切換為 MCP

3. 填寫以下設定：

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

填入 MCP URL 後，系統會自動偵測可用的工具

1. 建立完成後，進入 Agent 設定 → 工具 tab，可看到已綁定的 MCP 工具

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

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

如何取得 API Key？

點擊右上角頭像 → 個人資料 → 切換到 API 金鑰 頁籤 → 點擊 建立新金鑰，複製產生的 API Key。

API Key 建立後只會顯示一次，請立即複製並妥善保存。

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

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

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

點擊展開：標準版 Tool Prompt

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 必須依序執行，每步的輸出是下步的輸入。

1. 點擊 儲存

---

Step 4：綁定知識庫

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

1. 切換到 知識庫設定 tab

2. 點擊 新增知識庫，勾選目標 Agent 所使用的所有知識庫

3. 點擊 儲存

如果要分析多個 Agent，將所有 Agent 的知識庫都綁定到優化助理即可。建議在「進階設定」中將檢索 chunks 數量設為 12。

---

Step 5：驗證設定

驗證 MCP 工具連線

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

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

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

驗證診斷功能

從目標 Agent 的對話紀錄中取得一個 conversation_id：

1. 進入 所有對話 頁面

2. 點入任一筆對話，網址列中的 ID 即為 conversation_id

在優化助理中輸入：

請分析這筆對話：{conversation_id}

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

1. 搜尋可用的 API 工具（search_apis）

2. 呼叫 v1MessagesList 查詢對話訊息

3. 呼叫 v1RecordsRetrieve 取得對話紀錄詳情

4. 呼叫 v1ChatbotsRetrieve 取得被分析 Agent 的 Prompt

5. 產出完整的診斷摘要與修改建議

---

使用教學

用 conversation_id 分析

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

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

直接貼文字分析

若沒有 conversation_id，可直接提供：

請幫我分析以下問題：

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

診斷結果解讀

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

---

常見問題

Q：MCP 工具連線失敗怎麼辦？

1. 確認回答模式為 Agent 模式（最常見原因）

2. 確認 API Key 有效且未過期

3. 確認 MCP URL 為 https://mcp.maiagent.ai/mcp

4. 確認 Headers 使用 Api-Key 格式（如：Api-Key xxxxxxxx.xxxxxxxx）

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

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

---

設定速查表

• 建立 Agent（名稱：優化助理）

• 選擇模型（Claude Sonnet 4.6 或以上）

• 設為 Agent 模式

• 貼入標準版角色指令

• 建立 MCP 工具

  • MCP URL：https://mcp.maiagent.ai/mcp

  • Headers：API Key

  • 勾選 5 個 Allowed Tools

  • 貼入標準版 Tool Prompt

• 綁定目標 Agent 的知識庫

• 驗證 MCP 連線

• 驗證診斷功能