> 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/ja/build/optimizer-assistant.md).

# 活用例：Agent 最適化アドバイザー

Agent 最適化コンサルタントを構築し、AI の回答品質の問題を自動で診断して、Prompt とナレッジベース文書の調整案を提示します

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

Agent の回答が不正確だったり、形式が誤っていたり、情報を捏造したりする場合、通常は会話履歴を 1 件ずつ手作業で確認して原因を特定する必要があります。**最適化アシスタント**は、この診断プロセスを自動で行います。

1. 会話履歴、AI の回答、ナレッジベースの検索結果を自動で取得する
2. 問題が **Prompt の問題**（AI は正しいデータを取得したのに回答を誤った）か、**ナレッジベース文書の問題**（AI が正しいデータを取得できなかった）かを判断する
3. Before / After の対比を含む具体的な修正案を出力する

### 構成要素 <a href="#components" id="components"></a>

| 要素          | 説明                                                        |
| ----------- | --------------------------------------------------------- |
| **Agent**   | 最適化コンサルタントの土台となり、Agent モードを使用します                          |
| **ロール指示**   | 診断プロセス、分析の原則、出力形式を定義します                                   |
| **MCP ツール** | 最適化アシスタントが MaiAgent API を呼び出し、会話履歴や Agent の設定を照会できるようにします |
| **ナレッジベース** | 対象 Agent が使用しているナレッジベースを紐づけ、RAG の検索結果の検証に使用します            |

***

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

| 項目                | 説明                      | 入手方法                                                   |
| ----------------- | ----------------------- | ------------------------------------------------------ |
| 分析する Agent        | 最適化したい対象の Agent         | 管理コンソール → <mark style="color:blue;">AI アシスタント</mark>一覧 |
| 対象 Agent のナレッジベース | 対象 Agent に紐づいているナレッジベース | 対象 Agent を開く → ナレッジベースタブ                               |
| API Key           | MCP ツールの認証に使用します        | プロフィール → API キー（下記の説明を参照）                              |

***

## Step 1：Agent を作成する <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>をクリックします
2. 基本設定を入力します。

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

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

{% hint style="danger" %}
**回答モードは必ず Agent モードに設定してください**。RAG 問答モードでは MCP ツールを使用できず、最適化アシスタントが会話履歴や Agent の設定を照会できなくなります。
{% 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 アシスタントはナレッジベースから関連内容を検索し、その検索結果に基づいてユーザーに回答します。したがって、問題の原因は次の 2 種類のみです。
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 の指示を 1 つずつ取得する

**すべて取得してから診断に進まなければなりません。**

## Step 2：診断サマリーを提示する

**分析対象アシスタント**：[chatbot.name]（モデル：[llm.name]）
**ユーザーの質問**：[inputMessage]
**AI の回答の要約**：[outputMessage の先頭 200 文字]
**検索された情報源**：[citationNodes の fileName 一覧]
**スコア**：忠実度 [X] / 回答の関連性 [X] / 参照資料の関連性 [X]
**診断結果**：[Prompt の問題 / ナレッジベース文書の問題 / ナレッジベースの不足]

## Step 3：問題を分類する

**Q1：citationNodes に正しい答えが含まれているか？**
- はい → **Prompt の問題**
- いいえ → Q2 へ進む

**Q2：ナレッジベースに正しい答えが存在するか？**
- はい、ただし AI が検索できなかった → **ナレッジベース文書の問題**
- いいえ → ユーザーに**ナレッジベースの内容を追加**する必要があると伝える

---

# 7 つの最適化原則

| # | 原則 | 中心となる考え方 |
|---|-----|---------|
| 1 | 知識源の制限 | 「…のみを使用すること。…は使用しないこと」 |
| 2 | 引用の強制 | 「出典を必ず明記すること」 |
| 3 | 回答拒否の許可 | 「わからないと答えてよい」+ 定型文 |
| 4 | 明確なプロセス | 「ステップ 1…ステップ 2…」 |
| 5 | 絶対禁止事項 | 「絶対に禁止」「厳禁」 |
| 6 | フォールバック機構 | 「以下の場合は必ず有人対応に引き継ぐこと」 |
| 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 を照会して、会話履歴や Agent の設定を取得できます。

1. 左メニュー → <mark style="color:blue;">ツール</mark> → 右上の<mark style="color:blue;">ツールを追加</mark>をクリックします
2. <mark style="color:blue;">ツールタイプ</mark>を API から <mark style="color:blue;">MCP</mark> に切り替えます
3. 以下の設定を入力します。

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

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-a68428d6ebc79575b2d0cfabed8470c587f701a4%2Foptimizer-step3-mcp-edit-top.png?alt=media" alt=""><figcaption><p>MCP URL を入力すると、システムが利用可能なツールを自動で検出します</p></figcaption></figure>

4. 作成が完了したら、Agent の設定 → <mark style="color:blue;">ツール</mark>タブに進むと、紐づけ済みの MCP ツールを確認できます
5. **認証ヘッダー（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 をコピーします。
{% endhint %}

{% hint style="danger" %}
API Key は作成後に 1 度だけ表示されます。すぐにコピーして、安全な場所に保管してください。
{% 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 の検索結果を検証できるよう、**対象 Agent が使用しているナレッジベース**を紐づける必要があります。

1. <mark style="color:blue;">ナレッジベース設定</mark>タブに切り替えます
2. <mark style="color:blue;">ナレッジベースを追加</mark>をクリックし、対象 Agent が使用しているすべてのナレッジベースにチェックを入れます
3. <mark style="color:blue;">保存</mark>をクリックします

{% hint style="info" %}
複数の Agent を分析する場合は、すべての Agent のナレッジベースを最適化アシスタントに紐づけてください。「詳細設定」で、検索する chunk の数を **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>

対象 Agent の会話履歴から conversation\_id を取得します。

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

最適化アシスタントに次のように入力します。

```
この会話を分析してください：{conversation_id}
```

最適化アシスタントは、次のステップを自動で順に実行します。

1. 利用可能な API ツールを検索する（`search_apis`）
2. `v1MessagesList` を呼び出して会話メッセージを照会する
3. `v1RecordsRetrieve` を呼び出して会話履歴の詳細を取得する
4. `v1ChatbotsRetrieve` を呼び出して、分析対象 Agent の Prompt を取得する
5. 完全な診断サマリーと修正案を出力する

***

## 使い方 <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 の回答、ナレッジベースの検索結果、Agent の 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 つの最適化アシスタントで複数の Agent を分析できますか？** はい。API Key が同じ組織に属し、対象となるすべての Agent のナレッジベースが紐づけられていれば可能です。

**Q：顧客ごとに個別に作成する必要がありますか？** はい。API Key とナレッジベースは組織専用のため、顧客の組織ごとに独立した最適化アシスタントが必要です。
{% endhint %}

***

## 設定クイックリファレンス <a href="#quick-reference" id="quick-reference"></a>

* [ ] Agent を作成する（名前：最適化アシスタント）
* [ ] モデルを選択する（Claude Sonnet 4.6 以上）
* [ ] **Agent モードに設定する**
* [ ] 標準版ロール指示を貼り付ける
* [ ] MCP ツールを作成する
  * [ ] MCP URL：`https://mcp.maiagent.ai/mcp`
  * [ ] Headers：API Key
  * [ ] 5 つの Allowed Tools にチェックを入れる
  * [ ] 標準版 Tool Prompt を貼り付ける
* [ ] 対象 Agent のナレッジベースを紐づける
* [ ] 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.