> 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/maiagent-user-guide/maiagent-user-guide-ja/application/optimizer-assistant.md).

# AI アシスタント最適化コンサルタント

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

AI アシスタントに回答が不正確、フォーマットが誤っている、情報を勝手に補完するといった問題が発生した場合、通常は対話履歴を 1 件ずつ手作業で確認して問題を特定する必要があります。**最適化アシスタント**は、この診断プロセスを自動で完了できます。

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/Ok83FCbRcexL13C5Z85C" alt=""><figcaption><p>AI アシスタント一覧ページ — 「AI アシスタントを作成」をクリック</p></figcaption></figure>

2. 基本設定を入力します。

| 項目          | 推奨値                                   |
| ----------- | ------------------------------------- |
| **名称**      | `最適化アシスタント` または `AI アシスタント最適化コンサルタント` |
| **LLM モデル** | Claude Sonnet 4.6 以上（高い分析・推論能力が必要です）  |

<figure><img src="/files/yF5mcGkDsFXlkZbfXIG8" alt=""><figcaption><p>基本設定 — 名称を入力し、Claude 4.6 Sonnet モデルを選択</p></figcaption></figure>

3. <mark style="color:blue;">回答モード設定</mark> タブに切り替え、<mark style="color:blue;">Agent モード</mark> を選択します

<figure><img src="/files/MOY6crN75zqWIIC5SnXp" alt=""><figcaption><p>回答モード設定 — MCP ツールを使用するには Agent モードを選択する必要があります</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> タブで、下部の**役割指示**エリアを見つけます
2. 以下の標準版の役割指示をそのまま貼り付けます

{% hint style="info" %}
役割指示は最適化アシスタントの中核であり、診断プロセス、7 つの最適化原則、出力フォーマットを定義しています。標準版をそのまま使用し、変更しないことをおすすめします。
{% 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/muxvBGX1uLMb4vDwm5iv" alt=""><figcaption><p>ツール追加ポップアップ（デフォルトは API タイプ）</p></figcaption></figure>

2. <mark style="color:blue;">ツールタイプ</mark> を API から <mark style="color:blue;">MCP</mark> に切り替えます

<figure><img src="/files/GSgXjrEJzpM6ZZPoq39m" alt=""><figcaption><p>MCP タイプを選択 — フォームに MCP 設定エリアが表示されます</p></figcaption></figure>

3. 以下の設定を入力します。

| 項目              | 値                             |
| --------------- | ----------------------------- |
| **表示名**         | `MaiAgent API`                |
| **説明**          | `AI 回答分析ツール`                  |
| **MCP ツール URL** | `https://mcp.maiagent.ai/mcp` |

<figure><img src="/files/EmO37MSZg60fEruqJoSE" alt=""><figcaption><p>MCP URL を入力すると、システムが利用可能なツールを自動的に検出します</p></figcaption></figure>

4. 作成が完了したら、アシスタント設定 → <mark style="color:blue;">ツール</mark> タブに移動すると、紐づけ済みの MCP ツールを確認できます

<figure><img src="/files/7p5gYszwddpx3BojW3cD" 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/EldOhUnAkHHBFc2xBfPh" 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> タブに切り替えます

<figure><img src="/files/EoUwfiByCVpjQkjm4cL1" 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 つ取得します。

1. <mark style="color:blue;">すべての対話</mark> ページに移動します
2. いずれかの対話を開くと、アドレスバーの ID が conversation\_id です

<figure><img src="/files/mS0jv5t6e3jqFGaqelGg" 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/VozYlvt7vZ9nnldtVbDG" 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：1 つの最適化アシスタントで複数のアシスタントを分析できますか？** できます。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
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 dynamically by asking a question.

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

```
GET https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-ja/application/optimizer-assistant.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.