本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Amazon Bedrock 受管知識庫作為連接器目標
Amazon Bedrock 受管知識庫提供全受管擷取擴增產生 (RAG)：Amazon Bedrock 處理向量存放區、資料擷取和擷取最佳化，因此沒有擷取基礎設施可供您佈建或操作。Amazon Bedrock AgentCore 將受管知識庫公開為原生閘道連接器，您可以將其連接到 AgentCore Gateway，而您的代理程式會使用標準模型內容協定 (MCP) 呼叫來探索和查詢它，而不需要建置自訂擷取整合。如需建立和管理受管知識庫的詳細資訊，請參閱《[Amazon Bedrock 使用者指南](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html)*》中的 Amazon Bedrock* 知識庫。
連接器會公開兩個工具。第一個是 `AgenticRetrieveStream`。它會規劃擷取策略，在受管知識庫中執行多個擷取步驟，選擇性地擴展到完整文件，並串流回支援的結果和合成的引述回的答案。 `Retrieve`會執行單一混合搜尋並傳回最相關的段落。
**注意**
此連接器僅支援 Amazon Bedrock 受管知識庫。
下列各節會逐步解說連接器的運作方式、深入客服人員擷取、常見使用案例、如何設定目標，以及這兩種工具的輸入和回應結構描述。
**Topics**
+ [運作方式](#gateway-target-connector-managed-kb-how-it-works)
+ [代理程式擷取](#gateway-target-connector-managed-kb-agentic-retrieval)
+ [使用案例](#gateway-target-connector-managed-kb-use-cases)
+ [設定受管知識庫](#gateway-target-connector-managed-kb-setup)
+ [設定閘道服務角色](#gateway-target-connector-managed-kb-service-role)
+ [叫用工具](#gateway-target-connector-managed-kb-invoke)
+ [AgenticRetrieveStream 輸入結構描述](#gateway-target-connector-managed-kb-agentic-input-schema)
+ [AgenticRetrieveStream 回應格式](#gateway-target-connector-managed-kb-agentic-response-format)
+ [擷取輸入結構描述](#gateway-target-connector-managed-kb-input-schema)
+ [擷取回應格式](#gateway-target-connector-managed-kb-response-format)
+ [組態參考](#gateway-target-connector-managed-kb-config-reference)
+ [存取控制篩選](#gateway-target-connector-managed-kb-access-control)
## 運作方式
Amazon Bedrock AgentCore 為 Amazon Bedrock 受管知識庫提供內建連接器。Gateway 會處理結構描述管理、端點解析和服務身分驗證。連接器會公開兩個工具，您的代理程式會使用 來探索這些工具`tools/list`：
+ `AgenticRetrieveStream` — 多步驟串流代理程式擷取，傳回結果、規劃和擷取追蹤事件，以及具有引文的合成答案 （預設為傳回；使用 停用`generateResponse: false`)。
+ `Retrieve` — 單一混合式搜尋，傳回具有來源參考的最相關段落。
單一`Retrieve`調用遵循此流程：
1. **閘道設定** — 建立閘道並新增 Amazon Bedrock 受管知識庫目標，參考您要公開的受管知識庫。Gateway 會快照工具結構描述並佈建整合。
1. **工具探索** — 您的客服人員在閘道端點`tools/list`上呼叫 ，並探索具有其輸入結構描述的擷取工具。
1. **擷取調用** — 您的客服人員`tools/call`使用自然語言查詢呼叫 。Gateway 會向後端進行身分驗證，並將請求路由至受管知識庫，該知識庫會跨您的擷取內容執行混合搜尋。
1. **結果** — 工具會在工具結果的文字內容中傳回最相關的段落，並將來源參考作為 JSON。
1. **基礎回應** — 您的代理程式會使用結果來編寫具有引用來源的回應。
如需客服人員擷取流程，請參閱[客服人員擷取](#gateway-target-connector-managed-kb-agentic-retrieval)。
## 代理程式擷取
`AgenticRetrieveStream` 會將問題視為任務： 而不是針對一個查詢`Retrieve`執行的單一混合搜尋，它會規劃擷取策略、跨受管知識庫執行多個擷取步驟，以及串流傳回支援結果和合成的引文後端答案 - 全都在一個工具呼叫中。預設會傳回合成的答案；將 `generateResponse`設定為 `false`僅傳回結果。
您的客服人員透過對話叫用它 (`messages`)。其查詢的擷取器 — 每個指向受管知識庫 — 由目標上的管理員設定，而不是由代理程式提供。透過 MCP 規劃和擷取進度串流，`notifications/message`結果和答案會在工具結果中傳回。
如需代理程式擷取運作方式的詳細資訊，請參閱《[Amazon Bedrock 使用者指南](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html)*》中的 Amazon Bedrock* 知識庫。
如需請求和事件結構描述，請參閱 [AgenticRetrieveStream 輸入結構描述](#gateway-target-connector-managed-kb-agentic-input-schema)和 [AgenticRetrieveStream 回應格式](#gateway-target-connector-managed-kb-agentic-response-format)。
## 使用案例
+ **企業知識助理** — 內部 Wiki、執行手冊和政策文件中已擷取到受管知識庫的 Ground 代理程式回應。
+ **文件問答**：在不建置或操作向量存放區的情況下，回答大型文件集合的問題。
+ **多來源 RAG** — 在單一擷取呼叫中，從合併為單一受管知識庫的多個資料來源查詢內容。
+ **多步驟規劃** — `AgenticRetrieveStream`用於回答需要規劃和數個擷取步驟的分段或模棱兩可問題，並在一次呼叫中傳回合成的引述後端答案。
+ **經工具驗證的代理**程式 — 將受管知識庫擷取與其他閘道工具結合，讓代理程式可以查詢基本事實並採取動作。
## 設定受管知識庫
如需如何使用 Amazon Bedrock 受管知識庫連接器組態建立閘道目標的指示，包括使用 Python SDK 和 CLI 的設定範例，請參閱目標組態指南中的[設定受管知識庫](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-setup)。
## 設定閘道服務角色
Gateway 需要一個服務角色，允許 AgentCore 服務代表您在受管知識庫上執行擷取動作。如需必要的 IAM 許可和政策組態，請參閱目標組態指南中的[設定閘道服務角色](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-service-role)。
## 叫用工具
建立目標之後，您的客服人員會使用 探索工具`tools/list`，並使用 呼叫它們`tools/call`。每個工具名稱的字首都是目標名稱，格式為 `__AgenticRetrieveStream`或 `managed-kb___Retrieve`)。
對於 `AgenticRetrieveStream`，您的代理程式只會傳遞對話。擷取器是由管理員在目標上設定，因此代理程式不會傳送知識庫 IDs：
```
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "managed-kb___AgenticRetrieveStream",
"arguments": {
"messages": [
{ "role": "user", "content": { "text": "How do I configure a knowledge base target?" } }
]
}
}
}
```
對於 `Retrieve`，受管知識庫識別符繫結至目標，因此您的代理程式只會傳遞查詢：
```
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "managed-kb___Retrieve",
"arguments": {
"retrievalQuery": { "text": "What is Amazon Bedrock AgentCore?" }
}
}
}
```
如果您將擷取參數公開給客服人員 （請參閱[控制客服人員可以設定的參數](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-parameters))，客服人員可以在呼叫時覆寫管理員設定的預設值：
```
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "managed-kb___Retrieve",
"arguments": {
"retrievalQuery": { "text": "insurance benefits" },
"retrievalConfiguration": {
"managedSearchConfiguration": { "numberOfResults": 2 }
}
}
}
}
```
## AgenticRetrieveStream 輸入結構描述
傳回的結構描述`tools/list`是您的客服人員在呼叫 時可以設定的欄位集`AgenticRetrieveStream`。根據預設，唯一的客服人員可見欄位為 `messages`。要查詢的擷取器和所有擷取組態都是目標上的管理員設定 — 請參閱[設定受管知識庫](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-setup)。若要向客服人員公開更多欄位，請在目標`parameterOverrides`上設定 - 請參閱[控制客服人員可以設定的參數](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-parameters)。
```
{
"type": "object",
"properties": {
"messages": {
"description": "The messages for the agentic retrieval conversation. Contains the user query and conversation history.",
"type": "array",
"items": {
"type": "object",
"properties": {
"role": {
"description": "The role of the message sender (user or assistant).",
"type": "string",
"enum": ["user", "assistant"]
},
"content": {
"description": "The content of the message.",
"type": "object",
"properties": {
"text": {
"description": "The text content of the message.",
"type": "string"
}
}
}
},
"required": ["content", "role"]
}
}
},
"required": ["messages"]
}
```
| 欄位 | 類型 | 必要 | 說明 |
| --- | --- | --- | --- |
| `messages` | 陣列 | 是 | 客服人員擷取對話。每個訊息都有 `role`(`user` 或 `assistant`) 和 `content.text`。 |
如需管理員設定欄位 — `retrievers`、 `agenticRetrieveConfiguration`（基礎模型、重新排名`maxAgentIteration`、 和透過 的護欄`policyConfiguration`)，以及 `generateResponse` — 請參閱[設定受管知識庫](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-setup)和[組態參考](#gateway-target-connector-managed-kb-config-reference)。
## AgenticRetrieveStream 回應格式
`AgenticRetrieveStream` 會串流一系列事件。透過 MCP，追蹤事件會以即時進度`notifications/message`的形式交付，擷取結果和合成的答案會在工具結果中交付。串流會發出下列事件類型：
| 事件 | 說明 |
| --- | --- |
| `traceEvent` | 規劃或擷取步驟，包含 `step`(`Planning`、`SpeculativeRetrieval`、 或 `FullDocumentExpansion`)`Retrieval`、 `status`(`SUCCEEDED`、 或 `FAILED`)`IN_PROGRESS`、人類可讀的 `message`、`actions`採用的 ，以及任何 `warnings`或 `failures`。 |
| `responseEvent` | 產生答案文字的區塊。預設發出；只有在 `generateResponse` 設定為 時才會隱藏`false`。 |
| `result` | 擷取`results`，除非 `generateResponse` 設定為 `false`，否則為`generatedResponse`具有答案和引文的最終 。 |
`result` 事件具有下列結構：
```
{
"result": {
"results": [
{
"content": {
"text": "Amazon Bedrock AgentCore manages the storage, indexing, and retrieval infrastructure for a managed knowledge base...",
"mimeType": "text/plain"
},
"sourceRetriever": { "identifier": "kb-retriever-1" },
"metadata": { "x-amz-bedrock-kb-source-uri": "s3://example-bucket/docs/overview.pdf" }
}
],
"generatedResponse": {
"answer": "A managed knowledge base lets Amazon Bedrock AgentCore handle the vector store, ingestion, and retrieval for you.",
"citations": [
{
"startIndex": 0,
"endIndex": 98,
"references": [ { "..." : "references to supporting results" } ]
}
]
}
}
}
```
| 欄位 | 類型 | 必要 | 說明 |
| --- | --- | --- | --- |
| `results` | 陣列 | 是 | 擷取結果。每個項目都有 `content`（使用 `text`或 `byteContent`和 `mimeType`)、`sourceRetriever`產生它的 ，以及選用的 `metadata`。 |
| `generatedResponse` | object | 否 | 預設存在。只有在 `generateResponse` 設定為 時才會省略`false`。包含合成的 `answer``citations`，並將答案範圍 (`startIndex`、`endIndex`) 映射到支援的結果。 |
| `nextToken` | string | 否 | 擷取下一組結果的字符，如果有的話。 |
## 擷取輸入結構描述
傳回的結構描述`tools/list`是您的客服人員在呼叫 時可以設定的欄位集`Retrieve`。根據預設，唯一的客服人員可見欄位為 `retrievalQuery.text`。受管知識庫識別符和所有擷取設定都是目標上的管理員設定。若要`filter`向代理程式公開擷取設定，例如 `numberOfResults`或中繼資料，請在目標`parameterOverrides`上設定 - 請參閱[控制代理程式可以設定的參數](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-parameters)。
```
{
"type": "object",
"properties": {
"retrievalQuery": {
"description": "Contains the query to send the managed knowledge base.",
"type": "object",
"properties": {
"text": {
"description": "The text of the query made to the managed knowledge base.",
"type": "string"
}
}
}
},
"required": ["retrievalQuery"]
}
```
| 欄位 | 類型 | 必要 | 說明 |
| --- | --- | --- | --- |
| `retrievalQuery` | object | 是 | 要傳送至受管知識庫的查詢。 |
| `retrievalQuery.text` | string | 是 | 查詢的文字。 |
如需管理員集和可覆寫的欄位 — `numberOfResults`、中繼資料 `filter`、、`overrideSearchType`重新排名和多模式映像查詢 — 請參閱[組態參考](#gateway-target-connector-managed-kb-config-reference)。
## 擷取回應格式
`Retrieve` 工具會傳回包裝在 JSON-RPC 信封中的 MCP `tools/call`結果。`isError` 和 `content` 欄位位於 內`result`，而 `text` 欄位包含序列化`retrievalResults`承載：
```
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"isError": false,
"content": [
{
"type": "text",
"text": "{\"retrievalResults\":[{\"content\":{\"type\":\"TEXT\",\"text\":\"Amazon Bedrock AgentCore manages the storage, indexing, and retrieval infrastructure for a managed knowledge base...\"},\"location\":{\"type\":\"S3\",\"s3Location\":{\"uri\":\"s3://example-bucket/docs/overview.pdf\"}},\"score\":0.87,\"metadata\":{\"x-amz-bedrock-kb-source-uri\":\"s3://example-bucket/docs/overview.pdf\"}}]}"
}
]
}
}
```
中的每個項目`retrievalResults`都有下列結構：
| 欄位 | 類型 | 必要 | 說明 |
| --- | --- | --- | --- |
| `content` | object | 是 | 擷取區塊的內容。包括 `type`(`TEXT`、`IMAGE`、`AUDIO`、 `ROW`或 `VIDEO`) 和對應的內容，例如`text`文字區塊。 |
| `location` | object | 否 | 來源資料的位置。包括 `type`(`S3`、`WEB`、`CONFLUENCE``SHAREPOINT`、`CUSTOM`、 等） 和相符的位置物件，例如 。 `s3Location.uri` |
| `score` | number | 否 | 結果與查詢的相關性。 |
| `metadata` | object | 否 | 中繼資料屬性及其在資料來源中來源檔案的值。 |
## 組態參考
下列欄位是由管理員在 中設定`parameterValues`，或在建立目標`parameterOverrides`時向客服人員公開。如需設定它們的位置，請參閱[設定受管知識庫](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-setup)和[控制代理程式可以設定的參數](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-parameters)。
** `AgenticRetrieveStream` — `agenticRetrieveConfiguration` **
| 欄位 | 有效值 | 備註 |
| --- | --- | --- |
| `foundationModelType` | `MANAGED`, `CUSTOM` | `MANAGED` 使用服務受管模型 （預設）。 `CUSTOM`使用您提供的 Bedrock 模型 ARN。 |
| `rerankingModelType` | `MANAGED`, `CUSTOM`, `NONE` | `MANAGED` 使用服務受管的重新排名器 （預設）。 `CUSTOM`使用您自己的 。 `NONE`會停用重新排名。 |
| `foundationModelConfiguration.type` | `BEDROCK_FOUNDATION_MODEL` | 當 `foundationModelType`為 時為必要`CUSTOM`。 |
| `maxAgentIteration` | integer | 限制規劃和擷取反覆運算的數量。 |
| `policyConfiguration.guardrailConfiguration` | `guardrailId`, `guardrailVersion` | 連接 Amazon Bedrock 護欄。 |
** `Retrieve` — `managedSearchConfiguration` **
| 欄位 | 有效值 | 備註 |
| --- | --- | --- |
| `numberOfResults` | 整數 (1–100) | 要擷取的來源區塊數量。 |
| `overrideSearchType` | `HYBRID`, `SEMANTIC` | `HYBRID` 結合關鍵字和向量搜尋。 `SEMANTIC` 僅使用向量搜尋。 |
| `rerankingModelType` | `MANAGED`, `CUSTOM`, `NONE` | 與 相同`AgenticRetrieveStream`。 |
| `rerankingConfiguration.type` | `BEDROCK_RERANKING_MODEL` | 使用自訂重新排名時為必要。 |
| `rerankingConfiguration.bedrockRerankingConfiguration.metadataConfiguration.selectionMode` | `SELECTIVE`, `ALL` | 控制哪些中繼資料欄位會傳遞給重新排名者。 |
| `filter` | `equals`, `notEquals`, `greaterThan`, `greaterThanOrEquals`, `lessThan`, `lessThanOrEquals`, `in`, `notIn`, `startsWith`, `listContains`, `stringContains`, `andAll`, `orAll` | 中繼資料篩選條件。僅提供一個運算子。 |
## 存取控制篩選
如果您的受管知識庫使用存取控制來篩選每個使用者或群組的結果，呼叫應用程式必須與請求`userContext`一起傳遞 。Gateway 會`userContext`傳遞至知識庫，根據其套用存取控制篩選。Gateway 不會`userContext`從發起人的 IAM 身分填入 - 您的應用程式必須明確提供。
若要使用它：
1. 在目標`parameterOverrides`上設定 `$.userContext`以向代理程式公開 — 請參閱[控制代理程式可以設定的參數](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-parameters)。
1. 讓呼叫應用程式 （而非模型） 包含在`tools/call`引數`userContext`中：
```
{
"arguments": {
"retrievalQuery": { "text": "insurance benefits" },
"userContext": {
"userId": "user@example.com"
}
}
}
```