本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 将亚马逊 Bedrock 托管知识库作为连接器目标
Amazon Bedrock 托管知识库提供完全托管的检索增强生成 (RAG)：Amazon Bedrock 负责处理矢量存储、数据摄取和检索优化，因此没有可供您预置或操作的检索基础设施。Amazon Bedrock AgentCore 将托管知识库作为原生网关连接器公开，您可以将其连接到 AgentCore 网关，您的代理通过标准模型上下文协议 (MCP) 调用来发现和查询该知识库，无需构建自定义检索集成。有关创建和管理托管知识库的详细信息，请参阅《亚马逊基岩用户指南》[*中的 Amazon Bedrock *](https://docs.amazonaws.cn/bedrock/latest/userguide/knowledge-base.html) 知识库。
连接器暴露了两个工具。第一个是`AgenticRetrieveStream`。它不是一次查询，而是规划检索策略，在您的托管知识库中运行多个检索步骤，有选择地扩展到完整文档，并将支持结果和综合的、有引文支持的答案传回去。`Retrieve`执行单一混合搜索并返回最相关的段落。
**注意**
此连接器仅支持亚马逊 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)
## 工作原理
亚马逊 Bedrock AgentCore 为亚马逊 Bedrock 托管知识库提供了内置连接器。网关处理架构管理、端点解析和服务身份验证。该连接器暴露了两个工具，您的代理通过以下方式发现了这两个工具：`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.amazonaws.cn/bedrock/latest/userguide/knowledge-base.html) 知识库。
有关请求和事件架构，请参阅[AgenticRetrieveStream 输入架构](#gateway-target-connector-managed-kb-agentic-input-schema)和[AgenticRetrieveStream 响应格式](#gateway-target-connector-managed-kb-agentic-response-format)。
## 使用案例
+ **企业知识助手 ** — 已纳入托管知识库的内部 Wiki、运行手册和政策文档中的地面代理回应。
+ **文档问答 ** — 无需构建或运营矢量存储即可回答有关大型文档集合的问题。
+ **Multi-source RAG ** — 在一次检索调用中查询来自多个数据源的内容，这些内容合并到单个托管知识库中。
+ **Multi-step 规划 ** — 用于回答`AgenticRetrieveStream`需要计划和多个检索步骤的多部分或模棱两可的问题，在一次通话中返回由引文支持的综合答案。
+ **Tool-augmented 代理 ** — 将托管知识库检索与您的其他 Gateway 工具相结合，这样代理既可以查找有根据的事实，也可以采取行动。
## 建立托管知识库
有关如何使用 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`调用。每个工具名称都以目标名称为前缀，形式为`managed-kb___Retrieve`（`__AgenticRetrieveStream`或）。
因为`AgenticRetrieveStream`，您的代理只能传递对话。检索器由管理员在目标系统上配置，因此代理不发送知识库 ID：
```
{
"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` | array | 是 | 代理检索对话。每条消息都有一个`role`（`user`或`assistant`）和`content.text`。 |
有关管理员设置的字段 — `retrievers`、`agenticRetrieveConfiguration`（基础模型、重新排序和防护`policyConfiguration`）和 `generateResponse` — 请参阅[设置托管知识库和配置参考。`maxAgentIteration`](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`、`Retrieval`、或`FullDocumentExpansion`）`SpeculativeRetrieval`、a`status`（`IN_PROGRESS`、或`FAILED`）`SUCCEEDED`、人类可读的`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` | array | 是 | 检索结果。每件物品都有`content`（带`text`或`byteContent`和 a`mimeType`）、生产`sourceRetriever`者以及可选`metadata`。 |
| `generatedResponse` | object | 否 | 默认情况下出现。仅当设置`generateResponse`为时才省略`false`。包含综合结果 `answer``citations`，将答案跨度 (`startIndex`,`endIndex`) 映射到支持结果。 |
| `nextToken` | 字符串 | 否 | 用于检索下一组结果（如果有）的令牌。 |
## 检索输入架构
返回的架构`tools/list`是您的代理在调用时可以设置的一组字段`Retrieve`。默认情况下，代理可见的唯一字段是。`retrievalQuery.text`托管知识库标识符和所有检索设置都是管理员在目标上设置的。要向代理公开检索设置（例如`numberOfResults`或元数据`filter`），请在目标系统`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` | 对象 | 是 | 要发送到托管知识库的查询。 |
| `retrievalQuery.text` | 字符串 | 是 | 查询的文本。 |
有关管理员设置和可覆盖的字段（元数据`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` | 对象 | 是 | 检索到的区块的内容。包括 `type` (`TEXT`、`IMAGE`、`ROW`、`AUDIO`、或`VIDEO`) 和相应的内容，`text`例如文本块。 |
| `location` | object | 否 | 源数据的位置。包括`type`（`S3`、`WEB`、`CONFLUENCE`、`SHAREPOINT``CUSTOM`、等）和匹配的位置对象，例如`s3Location.uri`。 |
| `score` | 数字 | 否 | 结果与查询的相关性。 |
| `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`使用您提供的基岩模型 ARN。 |
| `rerankingModelType` | `MANAGED`, `CUSTOM`, `NONE` | `MANAGED`使用服务管理的重新排名器（默认）。`CUSTOM`使用你自己的。`NONE`禁用重新排名。 |
| `foundationModelConfiguration.type` | `BEDROCK_FOUNDATION_MODEL` | 当`foundationModelType`为必填项`CUSTOM`。 |
| `maxAgentIteration` | integer | 限制计划和检索迭代的次数。 |
| `policyConfiguration.guardrailConfiguration` | `guardrailId`, `guardrailVersion` | 附上亚马逊基岩护栏。 |
** `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`一起传递。网关`userContext`进入知识库，知识库在此基础上应用访问控制过滤。网关不是根据调用者的 IAM 身份填充 `userContext` ——您的应用程序必须明确提供该身份。
要使用它，请执行以下操作：
1. 通过在目标系统`parameterOverrides`上进行配置`$.userContext`向代理公开-请参阅[控制代理可以设置的参数](gateway-add-target-api-target-config.md#gateway-add-target-api-connector-managed-kb-parameters)。
1. 让调用应用程序（不是模型）包含`userContext`在`tools/call`参数中：
```
{
"arguments": {
"retrievalQuery": { "text": "insurance benefits" },
"userContext": {
"userId": "user@example.com"
}
}
}
```