翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# エージェント取り出しを使用してナレッジベースをクエリする
<a name="kb-test-agentic-retrieve"></a>

エージェント取り出しでは、基盤モデルを使用して複雑なクエリをインテリジェントにサブクエリに分解し、ナレッジベースから関連情報を繰り返し取得して、取得された結果が元のクエリに回答するのに十分かどうかを評価します。このアプローチにより、1 回の取り出しパスで完全には対処できない複雑な複数ステップの質問に対する取り出し精度が向上します。

例えば、クエリ*「最初に開始されたのはどのマガジン」、Arthur's"、または First for women?*「エージェント検索は、これを*「Arthur's" がいつ設立されたのか」などの個別のサブクエリに分割します。*と*「First for women founded?*」は、それぞれの結果を取得し、組み合わせた結果で十分かどうかを評価します。

## エージェント取り出しの仕組み
<a name="kb-agentic-retrieve-how-it-works"></a>

`AgenticRetrieveStream` API にリクエストを送信すると、次のプロセスが発生します。

1. **計画** – 基盤モデルはクエリを分析し、1 つ以上のサブクエリに分解する計画を作成します。各サブクエリは、設定した特定のリトリーバーを対象としています。取得結果が収集されると、基盤モデルは元のクエリに回答するのに十分かどうかを評価します。そうでない場合、設定された最大値まで追加の取得反復を計画して実行します。

1. **取得** – サブクエリは、設定されたナレッジベースリトリーバーに対して実行されます。結果は各取得から収集されます。

1. **完全なドキュメント拡張** – 基盤モデルがドキュメントの完全なコンテンツが必要であると判断した場合 (要約、完全性の検証、特定のセクションへのアクセスなど）、GetDocumentContent API を呼び出して完全なドキュメントコンテンツを取得します。

1. **レスポンスの生成** – `generateResponse`が `true` (デフォルト) に設定されている場合、基盤モデルは取得した結果から自然言語の回答を合成します。回答は`responseEvent`イベント経由でストリーミングされます。

1. **結果イベント** – 重複排除された取得は、すべての反復の結果であり、完全に合成された自然言語の回答と引用が返されます。トレースイベントは、オブザーバビリティのためにプロセス全体でストリーミングされます。

## 前提条件
<a name="kb-agentic-retrieve-prereqs"></a>

エージェント取り出しを使用する前に、以下が必要です。
+ フルマネージド型の Amazon Bedrock ナレッジベース。エージェント取り出しは現在、マネージドナレッジベースのみをサポートしています。
+ クエリの計画と評価に使用する Amazon Bedrock の基盤モデルへのアクセス。
+ 必須の IAM アクセス権限 詳細については、「[エージェントの取得に必要なアクセス許可](#kb-agentic-retrieve-permissions)」を参照してください。

## エージェント取り出しを使用してナレッジベースをクエリする
<a name="kb-agentic-retrieve-api"></a>

エージェント取り出しを使用するには、 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html)リクエストを送信します。レスポンスは、取得結果とトレースイベントを含むストリームです。

次の表に、キーリクエストフィールドを示します。


**必須フィールド**  

| フィールド | 説明 | 
| --- | --- | 
| messages | 入力クエリと会話履歴。各メッセージには、text値を持つroleフィールドとcontentフィールド (user または ) が含まれますassistant。 | 
| リトリーバー | データを取得するナレッジベースリトリーバー。最大 5 つのリトリーバーを指定できます。各リトリーバーは、ID でマネージドナレッジベースを指します。各リトリーバーには、オプションでメタデータフィルターと最大結果数を含めることができます。 | 
| agenticRetrieveConfiguration | クエリの計画と評価に使用する基盤モデル、およびオプションで再ランク付けモデルとエージェントの最大反復数を含む、エージェント取り出し設定。 | 


**任意フィールド**  

| フィールド | 説明 | 
| --- | --- | 
| policyConfiguration | エージェントの取得中に適用する Amazon Bedrock ガードレールを設定します。guardrailId と を指定しますguardrailVersion。 | 
| userContext | アクセスコントロールフィルタリングのユーザーコンテキストを提供します。 | 
| generateResponse | (デフォルト) true に設定すると、取得した結果から自然言語の回答を生成するように基盤モデルに指示するブール型フィールド。回答はテキストチャンクとしてストリーミングされ、結果イベントに含まれます。 | 

リクエストとレスポンスの完全な構文については、 API リファレンス[https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_AgenticRetrieveStream.html)の「」を参照してください。

## エージェント取り出しレスポンス
<a name="kb-agentic-retrieve-response"></a>

`AgenticRetrieveStream` レスポンスは、次のイベントタイプを含むストリームです。
+ **結果イベント** (`AgenticRetrieveResultEvent`) – 処理の完了時に配信される最終イベント。取得結果と、レスポンス生成が有効になっている場合に生成されたレスポンスが含まれます。結果イベントには以下が含まれます。
  + **取得結果** (`results`) – すべての反復で取得されたソースチャンク。各結果には、コンテンツ、ソースリトリーバー識別子、およびオプションのメタデータが含まれます。同じチャンクが複数のサブクエリによって取得されると、最終結果に 1 回のみ表示されます。
  + **生成されたレスポンス** (`generatedResponse`) – `generateResponse`が `true` (デフォルト) に設定されている場合、結果イベントには以下を含む`generatedResponse`オブジェクトが含まれます。
    + `answer` – 合成された完全な自然言語回答テキスト。
    + `citations` – 回答の範囲をサポートの取得結果にマッピングするオプションのリスト。各引用には以下が含まれています。
      + `startIndex` – 引用された文章が`answer`文字列内で始まる文字オフセット。
      + `endIndex` – 引用されたパッセージが終了する文字オフセット (排他的 — 引用されたテキストは から `startIndex` まで実行されますが、 は含まれません`endIndex`)。
      + `references` – 各リファレンスに、同じ結果イベントの`results`配列にインデックスを作成する`resultIndex`フィールドがあり、どの取得結果が引用されたスパンをサポートしているかを示すリスト。
+ **レスポンスイベント** (`AgenticRetrieveResponseEvent`) – `generateResponse`が `true` (デフォルト) に設定されている場合、`responseEvent`イベントはレスポンスの生成中にストリーミングされます。各イベントには、合成された自然言語回答の増分部分を含む`text`フィールドが含まれます。
+ **トレースイベント** (`AgenticRetrieveTraceEvent`) – エージェント取り出しプロセス中にストリーミングされ、各ステップを可視化するイベント。トレースイベントのタイプは次のとおりです。
  + **計画** – 基盤モデルがクエリを分析し、サブクエリを作成していることを示します。計画されたアクションとターゲットリトリーバーが含まれます。
  + **取得** — ナレッジベースに対して取得が実行されていることを示します。取得入力、出力、警告または失敗が含まれます。
  + **投機的取り出し** – レイテンシーを低減するために最初の計画ステップの前に実行される初期取り出し。単一のナレッジベースの場合、raw ユーザークエリを使用して結果を取得します。複数のナレッジベースの場合、プローブ検索を実行して、クエリを適切なリトリーバーにルーティングします。
  + **ドキュメントの完全拡張** — エージェントが特定のドキュメントの完全なコンテンツを取得していることを示します。ドキュメント ID、ソースリトリーバー、ステータス (InProgress、失敗) が含まれます。

## エージェントの取得に必要なアクセス許可
<a name="kb-agentic-retrieve-permissions"></a>

`AgenticRetrieveStream` API を使用するには、呼び出し元の IAM ID に次のアクセス許可が必要です。

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "bedrock:AgenticRetrieveStream",
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "bedrock:Retrieve",
                "bedrock:GetDocumentContent"
            ],
            "Resource": "arn:aws:bedrock:{{region}}:{{account-id}}:knowledge-base/*"
        },
        {
            "Effect": "Allow",
            "Action": "bedrock:InvokeModelWithResponseStream",
            "Resource": "*"
        }
    ]
}
```

エージェント取り出しでガードレールを使用する場合は、次のアクセス許可を追加します。

```
{
    "Effect": "Allow",
    "Action": [
        "bedrock:GetGuardrail",
        "bedrock:ApplyGuardrail"
    ],
    "Resource": "*"
}
```

## 考慮事項
<a name="kb-agentic-retrieve-considerations"></a>

エージェント取り出しを使用するときは、次の点に注意してください。
+ エージェント取り出しは、マネージド Amazon Bedrock ナレッジベースのみをサポートします。
+ リクエストごとのリトリーバーのクォータ、取得呼び出しごとの結果、およびエージェントの最大反復数については、「」を参照してください[マネージドナレッジベースのサービスクォータ](kb-managed-quotas.md)。
+ 最大反復回数を減らすと、エージェントが早期に停止し、複雑なクエリの精度が低下する可能性があります。
+ ガードレールを設定する場合、 `BLOCK`アクションのみがサポートされます。`MASK` アクションは、エージェント取り出しではサポートされていません。
+ お客様は、提供された場合、エージェント取り出し中に使用される基盤モデル、埋め込みモデル、再ランク付けモデルを提供して所有します。IAM 認証情報は、これらのモデルを呼び出すために使用されます。