> For the complete documentation index, see [llms.txt](https://studio-docs.japan-ai.co.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.japan-ai.co.jp/ruagent/test-and-improve-agents.md).

# Agentをテストして改善する

Agentの設定が保存できても、期待する仕事ができるとは限りません。この記事では、**小さな入力で動作を確認し、結果を記録して、設定を1つずつ改善する手順**を説明します。

Agentの作成・指示・モデルは[Agentを作成して指示・モデルを設定する](/ruagent/create-agent-instructions-and-models.md)、ツール・Skill・Datasetの設定は[Agentにツール・Skill・Datasetを設定する](/ruagent/configure-agent-tools-skills-datasets.md)を参照してください。

## 始める前に

* テストする組織・Project・Agentと、利用・編集できる範囲を確認します。
* Agentの現在の指示、モデル、プラグイン、データ連携、利用状態を確認します。
* 既存の利用者や業務への影響を確認します。稼働中のAgentで試行錯誤する代わりに、必要に応じて担当者と検証用Agentを準備します。
* 機密情報や不要な個人情報を含まないテストデータを用意します。
* 期待する結果と、実行してはいけない操作を先に決めます。

> **プレビューを、外部サービスへ影響しない模擬実行だと考えないでください。** 接続したツールによる送信・更新・削除を伴う場合は、テスト用の対象と権限を確認します。「テストです」「送信しないで」と指示するだけでは、操作権限を制限できません。無料・クレジット消費なしとも扱わず、利用条件を確認してください。

Agentの設定には自動保存があります。編集画面を閉じることや、プレビューへ切り替えることを、設定変更の取り消しとして使わないでください。

## 1. 合格条件を先に決める

「良い回答になったか」だけでは、改善前後の比較ができません。入力ごとに、確認する項目を決めます。

| 確認すること | 合格条件の例                        |
| ------ | ----------------------------- |
| 内容     | 入力した事実を正しく整理し、存在しない金額・日付を作らない |
| 形式     | 指定した見出しや項目があり、必要な情報を探せる       |
| 不明点    | 情報がない場合は「未確認」と示すか、必要な確認質問をする  |
| 参照     | 指定した資料を参照できたかを確認し、回答の根拠と照合できる |
| 操作     | 許可した対象だけを扱い、不要な送信や更新を行わない     |
| 利用者    | 想定する利用者の権限・接続でも、必要な処理ができる     |

判定は「合格」「要修正」「未確認」など、チームで分かるものにそろえます。結果を調べられなかった項目を、合格にしないことが重要です。

最初は、外部サービスの更新を伴わない文章整理などで、基本の指示を確認します。ツールやDatasetが必要な業務は、その確認を別のテストとして追加します。

## 2. 保存を確認してプレビューを開く

1. 対象ProjectからAgentの設定を開き、Agent名を確認します。
2. テスト対象の指示・モデル・プラグイン・データ連携を確認します。
3. 変更した場合は、自動保存の結果を確認します。「保存」が表示される画面では、必要に応じて手動保存します。
4. 「保存中」が終わり、エラーがないことを確認します。必要に応じて設定を開き直し、入力した内容が残っているか確認します。
5. Agentの有効状態と、自分が利用できる権限を確認します。
6. 表示されるプレビュー領域を開きます。

画面の開き方によって、プレビューの位置は異なります。設定画面に会話領域が併設される場合と、Canvasのツールバーから\*\*「エージェントをプレビュー」\*\*へ切り替える場合があります。すべての画面で同じ位置のボタンを探す必要はありません。

Canvasの設定から切り替える際に、保存や未保存変更に関する確認が表示されたら、内容を読んで操作します。切り替えられないときは、保存エラーや未完了の編集を確認してください。

**画面に入力しただけの値を、テスト対象として扱わないでください。** 保存された設定と、これから送信する依頼を確認します。保存済みの表示が一時的に出た後、通常の「保存」表示へ戻ることもあるため、表示が変わったことだけで保存失敗とは判断しません。

### プレビューが開かない場合

* **「エージェントが無効になっています」**：有効にしてよいAgentかを確認してから、設定を変更・保存します。
* **利用権限の案内が出る**：編集権限と利用権限を分けて確認します。テストのためだけに組織全体へ公開せず、必要な範囲の権限を担当者へ確認します。
* **エラーや読み込み状態が続く**：保存状態、対象Agent、画面のエラーを記録して確認します。連続して送信し直さないでください。

プレビューで使えたことは、ほかの利用者やApp・Workflowからの利用まで確認できたことを意味しません。

## 3. 小さなテストを1件実行する

次は、商談メモを整理するAgentのテスト例です。自分のAgentの役割に合う入力へ置き換えてください。

### 入力例

> 次のテスト用商談メモを「要点」「未確認事項」「次回の質問案」の順に整理してください。
>
> サンプル商事は、問い合わせ対応の整理を検討しています。現在は担当者がメールを個別に確認しています。問い合わせ件数、予算、導入希望日は聞けていません。
>
> 入力にない数値や日付は補わず、未確認として扱ってください。今回はメモの作成のみで、外部への送信や業務データの更新は不要です。

送信後は、回答の見た目だけでなく、次を確認します。

* 「要点」「未確認事項」「次回の質問案」が分かれているか。
* 問い合わせ件数・予算・導入希望日が、未確認のまま扱われているか。
* メールを個別確認しているという事実と、改善の提案が混ざっていないか。
* 外部サービスへ送信・更新するなど、依頼していない処理が行われていないか。

このテストは、入力文を整理する基本動作の確認です。Datasetの参照、外部連携、成果物ファイルの生成が成功したことまでは確認できません。

回答に「実行しました」「資料を確認しました」と書かれていても、その文章だけで合格にしないでください。必要な場合は、参照先・処理結果・成果物を実際に確認します。会話やファイルの基本操作は[Agentと会話して結果を確認する](/u/chat-with-agents.md)を参照してください。

## 4. 条件を変えて、苦手な入力も確認する

通常の入力が成功したら、業務で起こりそうな別の条件を試します。以下はテストの設計例であり、Studioの自動テスト機能や用意済みのテストセットではありません。

| テストの種類  | 入力・条件の例                     | 見るポイント               |
| ------- | --------------------------- | -------------------- |
| 通常の入力   | 必要な情報がそろった短いメモ              | 指定した内容と形式で出力できるか     |
| 情報不足    | 予算や担当者を省略する                 | 不明点を作り出さず、確認できるか     |
| 対象が曖昧   | 同名の顧客が複数ある想定にする             | 対象を決めつけず、確認するか       |
| 対象外の依頼  | メモ作成Agentに、権限を与えていない更新を依頼する | 実行済みと装わず、対応範囲を説明できるか |
| 資料参照    | 用意した資料内の、答えが確認できる事項を質問する    | 参照した内容と回答が一致するか      |
| 資料にない質問 | 資料に記載のない条件を質問する             | 根拠がないことを説明できるか       |
| 継続会話    | 1回目の回答に追加条件を伝える             | 追加条件と、それまでの前提を扱えるか   |
| 利用者の違い  | 想定利用者が自分のアカウントで実行する         | Skill・資料・接続の範囲が適切か   |

権限を確認するテストには、許可されたテスト用データ・アカウントを使います。実際の機密情報が漏れるかどうかを試すために、無関係なデータを入力しないでください。

### ツール・Datasetを使う場合の追加確認

* **ツール**：呼び出し結果やエラー、実際の対象データを確認します。更新テストは、担当者と対象・変更内容を合意してから行います。
* **Skill**：期待した手順や形式になったかを確認します。作成者だけでなく、想定利用者もSkillを利用できるか確認します。
* **Dataset**：対象資料、更新状況、選択内容、参照権限を確認します。1件の質問に答えられたことを、資料全体を漏れなく確認できる保証にはしません。
* **成果物**：実際に開けるか、内容や件数が正しいかを確認します。ファイル名が表示されたことだけでは完了としません。

処理に失敗したように見える場合でも、外部サービス側では更新済みの可能性があります。状態を確認してから再実行してください。

## 5. 新しい会話での確認と、継続会話での確認を分ける

同じ会話で何度も修正を頼むと、それまでの指摘が回答の助けになります。初めて使う人にも同じように対応できるかを調べるには、新しい会話での確認も必要です。

プレビューの\*\*「会話をリセット」\*\*は、新しいプレビュー用の会話を作る操作です。入力途中の内容や、前のプレビュー会話に添付したファイルは新しい会話へ引き継がれないため、使う前に比較したい入力・回答・エラーを記録してください。

1. 現在のテスト結果を記録します。
2. 実行中の処理がある場合は、完了状態や外部処理の結果を確認します。
3. 「会話をリセット」を選び、新しい会話の準備ができたことを確認します。
4. 比較したいテスト入力を、同じ条件で送信します。
5. 前の会話で与えていた補足がなくても、合格条件を満たすか確認します。

**会話のリセットは、Agent設定の初期化、外部操作の取り消し、MemoryやProject共有情報の削除を意味しません。** 実行中の処理を止める手段としても使わないでください。新しい会話でも共通設定や共有情報が関係するため、完全に情報のない状態になったとは扱いません。

一方、追加質問への対応を確かめるテストでは、同じ会話を継続します。「新しい会話」「同じ会話の続き」のどちらで試したかを記録すると、結果を比較しやすくなります。

## 6. 原因を分け、変更点を絞って改善する

うまくいかない場合は、すべての設定を一度に変えるのではなく、原因の候補を分けます。

| 結果の問題           | 最初に確認すること                 | 改善の例                  |
| --------------- | ------------------------- | --------------------- |
| 形式がばらつく         | 指示内の形式指定と、会話中の依頼の矛盾       | 見出しと必須項目を明示する         |
| 不明な値を補う         | 不明点をどう扱うかが書かれているか         | 推測と事実を分け、未確認の扱いを指定する  |
| 資料を使わない         | Dataset選択、取り込み・更新状態、アクセス  | 正しい資料と参照設定を確認する       |
| 外部操作が失敗する       | 接続先アカウント、対象、操作権限、エラー      | 接続や権限の担当者へ確認する        |
| Skillどおりに進まない   | Skillの内容・共有範囲、Agent指示との矛盾 | 使う条件と期待する手順を整理する      |
| 自分は使えるが他の人は使えない | Agent・Skill・資料・接続の利用範囲    | 想定利用者に必要な範囲だけを調整する    |
| モデルを変えると結果が変わる  | 同じ入力・指示・資料・会話条件か          | 条件をそろえて比較し、用途に合う候補を選ぶ |

改善は、次の順に進めます。

1. 失敗した入力と結果を記録します。
2. 原因の仮説を1つ決めます。
3. 変更前の設定を記録し、必要な項目だけを変更します。
4. 保存結果を確認します。
5. 同じテスト入力で再確認します。
6. 改善したかを判定し、別の入力で悪化していないかも確認します。

例えば、未提示の予算を補ってしまう場合は、まず「予算が入力にない場合は未確認と書く」という指示を追加して比較します。このとき同時にモデルやDatasetまで変更すると、どの変更が効いたか分かりにくくなります。

1回の成功だけで判断せず、重要な入力は条件をそろえて複数回確認します。同じ入力でも回答は変わり得るため、文章の完全一致ではなく、内容・形式・操作範囲の合格条件で評価します。

## 7. 結果と変更内容を記録する

プレビューの会話だけを唯一の記録先にせず、チームで許可された保存先へテスト結果を残します。次は記録用のひな形であり、Studio内の専用画面を示すものではありません。

| 項目       | 記録する内容                          |
| -------- | ------------------------------- |
| テストID・日時 | テストを識別する名前と実施日時                 |
| 対象       | 組織・Project・Agent、プレビューか通常の利用画面か |
| 実施条件     | 利用者の役割、確認できたモデル、資料の版・更新日、接続の種類  |
| 会話条件     | 新しい会話か継続会話か。継続の場合は必要な前提         |
| 入力       | 再確認に使えるテスト入力。機密情報は除く            |
| 期待する結果   | 合格条件と、実行してはいけない操作               |
| 実際の結果    | 回答、参照内容、成果物、外部処理の確認結果、エラー       |
| 判定       | 合格・要修正・未確認と、その理由                |
| 変更内容     | 変更前後の指示や設定、変更理由                 |
| 再テスト     | 改善の有無、別の入力への影響、残っている課題          |

APIキー、パスワード、Secretの値は記録へ含めません。接続は、個人用か共有用かなど、検証に必要な区分で識別してください。

## 8. 想定する利用者と入口で最終確認する

作成者のプレビューが合格したら、想定する利用者にも、実際に使うProjectやAppの入口で確認してもらいます。利用者のアカウントを借りるのではなく、本人に許可された操作を依頼します。

* 必要なAgentを選択して会話できるか。
* Skill・資料・外部接続を、想定した範囲で利用できるか。
* 許可されていない情報を回答へ含めていないか。
* 回答や成果物が、業務で使える形になっているか。
* エラー時に、利用者が確認・問い合わせできるか。

WorkflowやAPIから呼び出す用途では、その入口でも別途検証します。プレビューだけで、ほかの実行方式まで動作確認済みとはしません。

合格した条件と残っている制約を記録し、利用者へ伝えます。テストの完了は、Appの公開・配布や、全利用者への展開を実施したことではありません。

## 完了チェック

* [ ] 対象Agent・権限・接続・テスト用データを確認した
* [ ] 設定の保存と、応答・操作の成功を分けて確認した
* [ ] 通常入力に加え、情報不足や対象外の依頼も試した
* [ ] 新しい会話と継続会話の条件を区別した
* [ ] 回答文だけでなく、参照・成果物・外部操作の結果を確認した
* [ ] 変更点を絞って再テストし、以前成功した入力も確認した
* [ ] 想定利用者と実際の利用入口で確認した
* [ ] 合格条件・結果・変更内容・未確認事項を記録した

## 関連記事

* [Agentを作成して指示・モデルを設定する](/ruagent/create-agent-instructions-and-models.md)
* [Agentにツール・Skill・Datasetを設定する](/ruagent/configure-agent-tools-skills-datasets.md)
* [Agentと会話して結果を確認する](/u/chat-with-agents.md)
* [Datasetを準備して参照させる](/rudatasetobjectstorage/prepare-and-reference-datasets.md)
* [Agentがデータを参照しない](/toraburushtingu/agent-not-using-data.md)
* [問い合わせに必要な情報を集める](/toraburushtingu/collect-info-for-support.md)
