翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# エージェントの動作テストとトラブルシューティング
エージェントを作成すると、*作業用のドラフト*が作成されます。作業用のドラフトは、エージェントを反復的に構築するために使用できるエージェントのバージョンです。エージェントを変更するたびに、作業ドラフトが更新されます。エージェントの設定が完了したら、エージェントのスナップショットである*バージョン*と、バージョンを指す*エイリアス*を作成できます。その後、エイリアスを呼び出すことで、エージェントをアプリケーションにデプロイできます。詳細については、「[アプリケーションに Amazon Bedrock エージェントをデプロイして使用する](agents-deploy.md)」を参照してください。
次のリストは、エージェントのテスト方法を示しています。
+ Amazon Bedrock コンソールで、サイドテストウィンドウを開き、エージェントが応答するための入力を送信します。作業用のドラフトまたは作成したバージョンを選択できます。
+ API では、作業用のドラフトは `DRAFT` バージョンです。テストエイリアスを含む [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html)、`TSTALIASID`、または静的バージョンを指す別のエイリアスを使用して、エージェントに入力を送信することができます。エージェントをテストする前に、[https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html) を呼び出してエージェントを準備する必要があります。
## エージェントの動作をトレースする
エージェントの動作のトラブルシューティングに役立つように、Amazon Bedrock エージェントはエージェントとのセッション中に*トレース*を表示する機能を提供します。トレースには、エージェントのステップバイステップの推論プロセスが表示されます。トレースの詳細については、「[トレースを使用してエージェントのステップバイステップの推論プロセスを追跡する](trace-events.md)」を参照してください。
## エージェントをテストする
エージェントをテストするための手順を以下に示します。任意の方法のタブを選択し、その手順に従います。
------
#### [ Console ]
**エージェントをテストするには**
1. Amazon Bedrock コンソールを使用するためのアクセス許可を持つ IAM ID を使用して、AWS マネジメントコンソールにサインインします。Amazon Bedrock コンソール ([https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock)) を開きます。
1. 左側のナビゲーションペインで **[エージェント]** を選択します。次に、**[エージェント]** セクションでエージェントを選択します。
1. **[エージェント]** セクションで、エージェントのリストからテストするエージェントのリンクを選択します。
1. 右側のペインに **[テスト]** ウィンドウが表示されます。
**注記**
**[テスト]** ウィンドウが閉じている場合は、エージェントの詳細ページの上部にある **[テスト]**、またはその中の任意のページを選択して、再度開くことができます。
1. エージェントを作成したら、次のいずれかの方法で準備して、作業用のドラフトの変更を含めパッケージ化する必要があります。
+ **[テスト]** ウィンドウで、**[準備]** を選択します。
+ **[作業用のドラフト]** ページで、ページの上部にある **[準備]** を選択します。
**注記**
作業用のドラフトを更新するたびに、最新の変更を含めてエージェントをパッケージ化するようにエージェントを準備する必要があります。ベストプラクティスとして、**[作業用のドラフト]** ページの **[エージェントの概要]** セクションで、エージェントの **[最後の準備]** 時間を常に確認し、最新のエージェントをテストしていることを確認することをお勧めします。
1. **[テスト]** ウィンドウの上部にあるドロップダウンメニューを使用して、テストするエイリアスおよび関連するバージョンを選択します。デフォルトでは、**[TestAlias: 作業用のドラフト]** が選択されています。
1. (オプション) エイリアスのプロビジョンドスループットを選択するには、選択したテストエイリアスの下のテキストに **[ODT の使用]** または **[PT の使用]** と表示されます。プロビジョンドスループットモデルを作成するには、**[変更]** を選択します。詳細については、「[Amazon Bedrock のプロビジョンドスループットでモデル呼び出し容量を増やす](prov-throughput.md)」を参照してください。
1. (オプション) プロンプト管理からプロンプトを使用するには、メッセージボックスのオプションアイコン (![\[Vertical ellipsis icon representing a menu or more options.\]](http://docs.aws.amazon.com/ja_jp/bedrock/latest/userguide/images/icons/vertical-ellipsis.png)) を選択し、**[プロンプトをインポート]** を選択します。プロンプトとバージョンを選択します。**[変数値のテスト]** セクションにプロンプト変数の値を入力します。プロンプト管理でのプロンプトの詳細については、「[Amazon Bedrock でプロンプト管理を使用して再利用可能なプロンプトを構築して保存する](prompt-management.md)」を参照してください。
1. エージェントをテストするには、メッセージを入力して **[実行]** を選択します。レスポンスの生成を待つ間、または生成後に、次のオプションを使用できます。
+ プロンプト、推論設定、各ステップのエージェントの推論プロセス、アクショングループとナレッジベースの使用など、エージェントのオーケストレーションプロセスの各ステップの詳細を表示するには、**[トレースを表示]** を選択します。トレースはリアルタイムで更新されるため、レスポンスが返される前に確認できます。ステップのトレースを展開または折りたたむには、ステップの横にある矢印を選択します。**[トレース]** ウィンドウと表示される詳細については、「[トレースを使用してエージェントのステップバイステップの推論プロセスを追跡する](trace-events.md)」を参照してください。
+ エージェントがナレッジベースを呼び出す場合、レスポンスには脚注が含まれます。レスポンスの特定部分の引用情報を含む S3 オブジェクトへのリンクを表示するには、関連する脚注を選択します。
+ Lambda 関数を使用してアクショングループを処理するのではなく、エージェントにコントロールを返すように設定した場合、レスポンスには予測されたアクションとそのパラメータが含まれます。アクションの API または 関数からの出力値の例を指定し、**[送信]** を選択してエージェントレスポンスを生成します。例については、次の画像を参照してください。
![\[アクションの出力例を提供するテストウィンドウリクエスト。\]](http://docs.aws.amazon.com/ja_jp/bedrock/latest/userguide/images/agents/roc-testwindow.png)
**[テスト]** ウィンドウでは、次のアクションを実行できます。
+ エージェントと新しい会話を開始するには、更新アイコンを選択します。
+ **[トレース]** ウィンドウを表示するには、展開アイコンを選択します。**[トレース]** ウィンドウを閉じるには、縮小アイコンを選択します。
+ **[テスト]** ウィンドウを閉じるには、右矢印アイコンを選択します。
アクショングループとナレッジベースを有効または無効にできます。この機能を使用して、異なる設定でのエージェントの動作を評価し、更新が必要なアクショングループまたはナレッジベースを特定することで、エージェントのトラブルシューティングを行います。
**アクショングループまたはナレッジベースを有効にするには**
1. Amazon Bedrock コンソールを使用するためのアクセス許可を持つ IAM ID を使用して、AWS マネジメントコンソールにサインインします。Amazon Bedrock コンソール ([https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock)) を開きます。
1. 左側のナビゲーションペインで **[エージェント]** を選択します。次に、**[エージェント]** セクションでエージェントを選択します。
1. **[エージェント]** セクションで、エージェントのリストからテストするエージェントのリンクを選択します。
1. エージェントの詳細ページでの **[作業用のドラフト]** セクションで、**[作業用のドラフト]** のリンクを選択します。
1. **[アクショングループ]** または **[ナレッジベース]** セクションで、状態を変更するアクショングループまたはナレッジベースの **[状態]** にカーソルを合わせます。
1. [編集] ボタンが表示されます。編集アイコンを選択して、ドロップダウンメニューでアクショングループまたはナレッジベースに対し、**[有効]** または **[無効] **を選択します。
1. アクショングループが **[無効]** の場合、エージェントはアクショングループを使用しません。ナレッジベースが **[無効]** の場合、エージェントはナレッジベースを使用しません。アクショングループまたはナレッジベースを有効または無効にし、**[テスト]** ウィンドウを使用してエージェントのトラブルシューティングを行います。
1. テストする前にエージェントに加えた変更を適用するには、**[準備]** を選択します。
------
#### [ API ]
2025 年 3 月 31 日の`after`に作成されたエージェントの場合:
+ コンソールでエージェントを作成した場合、ストリーミングはデフォルトで有効になっています。ストリーミングはいつでも無効にできます。
+ エージェント実行ロールに、設定されたエージェントモデルの `bedrock:InvokeModelWithResponseStream` アクセス許可が含まれていることを確認します。
エージェントを初めてテストする前に、[Amazon Bedrock エージェントのビルドタイムエンドポイント](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt)を使用して [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_PrepareAgent.html) リクエストを送信し、エージェントを作業用ドラフトの変更を含めてパッケージ化する必要があります。リクエストに `agentId` を含めます。`TSTALIASID` エイリアスが指す `DRAFT` バージョンに変更が適用されます。
```
def prepare_agent(self, agent_id):
"""
Creates a DRAFT version of the agent that can be used for internal testing.
:param agent_id: The unique identifier of the agent to prepare.
:return: The response from Amazon Bedrock Agents if successful, otherwise raises an exception.
"""
try:
prepared_agent_details = self.client.prepare_agent(agentId=agent_id)
except ClientError as e:
logger.error(f"Couldn't prepare agent. {e}")
raise
else:
return prepared_agent_details
```
詳細については、「[Amazon Bedrock エージェントの始め方](bedrock-agent_example_bedrock-agent_Hello_section.md)」を参照してください。
**注記**
作業用のドラフトを更新するたびに、最新の変更を含めてエージェントをパッケージ化するようにエージェントを準備する必要があります。ベストプラクティスとして、[Amazon Bedrock エージェントのビルドタイムのエンドポイント](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt)を使用して [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_GetAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_GetAgent.html) リクエストを送信し (リクエストとレスポンスの形式およびフィールドの詳細についてはリンクを参照)、`preparedAt` 時間を確認してエージェントが最新の状態であるかどうかを確認してください。
エージェントをテストするには、エージェントに [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) リクエストを送信します。サンプルコードについては、「[アプリケーションからエージェントを呼び出す](agents-invoke-agent.md)」を参照してください。
**注記**
AWS CLI は [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) をサポートしていません。
リクエストには以下のフィールドが含まれます。
+ 少なくとも、次の必須フィールドを指定します。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/bedrock/latest/userguide/agents-test.html)
+ 次のフィールドはオプションです。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/bedrock/latest/userguide/agents-test.html)
レスポンスはイベントストリームで返されます。各イベントには、`bytes` フィールド内にレスポンスの一部を含む `chunk` が含まれています。これはデコードする必要があります。次のオブジェクトが返される場合もあります。
+ エージェントがナレッジベースをクエリした場合、`chunk` には `citations` も含まれます。
+ ストリーミングが有効で、エージェントにガードレールが設定されている場合、レスポンスはガードレール間隔に指定された文字間隔で生成されます。デフォルトでは、間隔は 50 文字に設定されています。
+ トレースを有効にすると、`trace` オブジェクトも返されます。エラーが発生すると、フィールドがエラーメッセージとともに返されます。トレースの読み取り方法の詳細については、「[トレースを使用してエージェントのステップバイステップの推論プロセスを追跡する](trace-events.md)」を参照してください。
+ Lambda 関数を使用してスキップするようにアクショングループを設定すると、`returnControl` フィールドに [ReturnControlPayload](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ReturnControlPayload.html) オブジェクトが返されます。[ReturnControlPayload](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ReturnControlPayload.html) オブジェクトの一般的な構造は次のとおりです。
```
{
"invocationId": "string",
"invocationInputs": [
[ApiInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ApiInvocationInput.html) or [FunctionInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FunctionInvocationInput.html),
...
]
}
```
`invocationInputs` リストの各メンバーは、次のいずれかです。
+ エージェントが予測する API オペレーションを含む [ApiInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ApiInvocationInput.html) オブジェクトは、API を満たすためにユーザーから取得するパラメータやその他の情報に加えて、ユーザー入力に基づいて呼び出す必要があります。[ApiInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_ApiInvocationInput.html) オブジェクトの構造は次のとおりです。
```
{
"actionGroup": "string",
"apiPath": "string",
"httpMethod": "string",
"parameters": [
{
"name": "string",
"type": "string",
"value": "string"
},
...
],
"requestBody": {
: {
"properties": [
{
"name": "string",
"type": "string",
"value": "string"
}
]
}
}
}
```
+ エージェントが予測する関数を含む [FunctionInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FunctionInvocationInput.html) オブジェクトは、ユーザーから取得する関数のパラメータに加えて、ユーザー入力に基づいて呼び出す必要があります。[FunctionInvocationInput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_FunctionInvocationInput.html) の構造は次のとおりです。
```
{
"actionGroup": "string",
"function": "string",
"parameters": [
{
"name": "string",
"type": "string",
"value": "string"
}
]
}
```
------