当用户使用基于知识的应用时,他们期望系统不仅能精准搜索,还能记住自己。他们提出的后续问题只有结合上一轮对话的上下文才有意义;他们期望关于政策或流程的回答能反映上个月自己告诉应用的信息;同时,他们仍然期望每个答案都有引用,并且只基于自己有权阅读的文档。无论是客户支持助手、SaaS 产品内的文档聊天,还是公司内部政策助手,这种期望都是一致的。
然而,满足这一期望并不容易,因为能够提升搜索质量的相关上下文往往存在于知识库之外。用户的位置、角色或产品层级可能在几周前一次无关的对话中被提及。为了利用这些信息,应用必须存储每次对话,从中提取持久事实,判断哪些事实对当前问题重要,并将它们注入请求。当众多用户共享应用时,上述每一步都必须按用户隔离,每个文档也不例外。
现在,Amazon Bedrock 托管知识库和 Amazon Bedrock AgentCore 内存(AgentCore 的一项能力)接管了这些步骤:存储每次对话、提取事实并将相关事实带入搜索。只需在 AgenticRetrieveStream 请求中添加 memoryConfiguration,即可将 AgentCore 内存作为知识库之外的检索源启用。在同一次调用中,服务会恢复对话,规划器自主判断何时需要用户事实,从长期记忆中检索该事实,并用它来构造发送给知识库的子查询。生成答案后,服务将本轮对话保存回记忆。同一个请求携带 userContext,因此知识库仅返回用户访问控制列表(ACL)允许的文档。此集成是可选且向后兼容的。应用只需保留真正属于自己的部分:验证用户身份并传递用户标识。
本文展示如何为共享一个知识库和一个内存资源的众多用户构建这样的助手。每个用户只能看到自己有权阅读的文档,每个用户的记忆保持私有。运行示例是虚构公司 AnyCompany 的内部员工助手。员工通过 Amazon Cognito 登录,并针对 HR 政策、IT 指南、工程运行手册和销售计划提问。我们将展示如何从 Cognito ID 令牌读取用户身份,如何将其传递给 AgenticRetrieveStream 以实现文档 ACL 和记忆,如何为多用户设计记忆命名空间,以及如何读取跟踪信息以了解规划器何时使用了记忆。最后,我们让 AWS Identity and Access Management (IAM) 强制执行每用户记忆隔离,即使应用代码出错也能生效。如果您已部署“Build multi-tenant agentic chat applications on enterprise data with Amazon Bedrock Managed Knowledge Base”中的应用,本文可替代其中“自行持久化对话历史”的步骤。
解决方案概述
AnyCompany 将文档存储在 Amazon Simple Storage Service (Amazon S3) 中。一个托管知识库通过启用了 ACL 的 Amazon S3 数据源同步这些文档。同一存储桶中的全局 ACL 文件规定哪些员工可以阅读每个文件夹:所有人可读 HR 和 IT,只有工程师可读工程运行手册,只有销售人员可读佣金计划。一个 AgentCore 内存资源由所有员工共享。Amazon Cognito 对员工进行身份验证,其 ID 令牌提供两个声明:sub(用户 ID)标识用户记忆,已验证的电子邮件标识用户以用于知识库的 ACL 过滤器。三个测试用户登录:两名工程师 Maya 和 Liam,以及一名销售人员 Sofia。本文中的跟踪摘录取自 GitHub 仓库中示例应用的一次运行。
图 1:具备记忆的员工助手架构。应用验证用户并构造请求(步骤 1-4)。Amazon Bedrock 托管知识库恢复会话、检索信息、返回答案并将交互保存到 AgentCore 内存(步骤 5-8)。短期事件和长期记录属于同一个内存资源。
- 员工通过 Cognito 登录并获得 ID 令牌,这是一个由用户池签名的 JSON Web Token (JWT)。
- 应用的 API 验证令牌——生产环境中使用 Amazon API Gateway JWT 授权器,示例中使用一个小型 FastAPI 服务。未认证请求无法到达处理程序。
- 处理程序从已验证的令牌中读取两个声明:sub 成为记忆 actorId 和命名空间,email 成为 userContext.userId。客户端请求体仅包含 { question, sessionId? }。然后处理程序代入应用程序为此用户设置的 IAM 角色,会话标签为 userId=。
- 处理程序调用 AgenticRetrieveStream,将知识库作为检索器,传递 userContext 和绑定到该用户的 memoryConfiguration。
- 托管知识库从 AgentCore 内存的短期记忆 (STM) 中恢复 sessionBinding 所标识的 actor 和会话的对话历史。
- 托管知识库根据 userContext 从知识库检索并进行 ACL 过滤。它还可以通过推测性检索或规划器选择的内存搜索来检索用户配置的长期记忆。
- 托管知识库将带有引用的答案和跟踪事件流式传输回处理程序。处理程序使用关联 ID 记录跟踪信息,并将答案和跟踪信息转发到 UI。
- 当 persistenceMode: DEFAULT 时,服务将问题和生成的答案保存到会话。然后 AgentCore 内存根据配置的策略异步提取长期记录。
图 2:一次带有 userContext 和 memoryConfiguration 的 AgenticRetrieveStream 轮次。第一个和最后一个箭头之间的所有内容都是服务的工作。
托管知识库负责摄取、ACL 过滤、索引、排序、规划、检索和生成。借助 memoryConfiguration,它还负责会话恢复、内存搜索和持久化。AgentCore 内存负责存储、保留、加密和提取。您的应用负责身份验证、UI 以及从令牌读取用户身份。没有对话表:当 UI 列出或重新打开对话时,它读取的是同一个内存资源。
身份如何映射到请求
每个值都由应用从已验证的 ID 令牌派生,没有一个来自请求体。
| 请求字段 | 派生自 | 作用范围 | 执行者 | |---------|--------|----------|--------| | userContext.userId | ID 令牌 email(在用户池中已验证且不可变) | 哪些文档可以被检索 | 知识库 ACL 过滤 | | memoryConfiguration.sessionBinding.actorId | ID 令牌 sub | 恢复和写入谁的短期记忆,以及长期命名空间中的 {actorId} | AgentCore 内存键控,加上 IAM 条件 | | memoryConfiguration.sessionBinding.sessionId | 应用为新对话生成,通过 ListSessions 列出 | 该 actor 内的哪个对话 | 在 actorId 下键控 | | memoryConfiguration.retrievalConfigs[0].namespacePath | /anycompany/ | 规划器可以搜索哪些长期记录 | IAM 条件 |
两个不同的声明承担两项不同的工作。知识库通过电子邮件识别用户,因为这是连接的数据源在其 ACL 中记录的内容。内存需要一个永不更改且永不复用的 actorId。Cognito sub 两者兼具。电子邮件地址可以被更改,或在某人离开后重新分配给新员工,那个人就会继承旧记忆。您可以使用自己用户存储中的另一个稳定用户 ID 作为 actorId。重要的是它永远不会转移到其他人身上。
先决条件
- 本演练使用位于美国西部(俄勒冈)区域 (us-west-2) 的托管知识库和 AgentCore 内存资源。如代理检索文档所述,与此集成一起使用的内存资源必须与知识库位于同一 AWS 账户中,并处于 ACTIVE 状态。
- Python 3.10 或更高版本,以及 Boto3 1.43.72 或更高版本。
- 具有创建 S3 存储桶、Cognito 用户池、IAM 角色、知识库和内存资源的权限。示例的 infra/setup.py 以幂等方式创建所有这些资源。
解决方案演练
以下步骤创建知识库及其数据源,设置内存资源和 Amazon Cognito,构造请求,并读取跟踪信息以确认结果。
步骤 1:创建具有 ACL 启用数据源的知识库
托管知识库不需要向量存储。按照“为托管 Amazon Bedrock 知识库创建服务角色”配置服务角色,并在 roleArn 中传递其 ARN。关于模型访问要求,请同时查看托管和自定义模型的先决条件。
kb = agent.create_knowledge_base(
name="anycompany-assistant-docs",
description="AnyCompany internal documents: HR policies, IT guides, engineering runbooks, sales plans.",
roleArn=kb_service_role_arn,
knowledgeBaseConfiguration={
"type": "MANAGED",
"managedKnowledgeBaseConfiguration": {"embeddingModelType": "MANAGED"},
},
)["knowledgeBase"]文档位于存储桶的 docs// 下。Amazon S3 没有自己的权限系统可供爬取,因此您在同一存储桶的全局 ACL 文件中提供 ACL。每个条目将 S3 前缀映射到可读取它的电子邮件:
[
{"keyPrefix": "s3://BUCKET/docs/hr/",
"aclEntries": [{"Name": "[email protected]", "Type": "USER", "Access": "ALLOW"},
{"Name": "[email protected]", "Type": "USER", "Access": "ALLOW"},
{"Name": "[email protected]", "Type": "USER", "Access": "ALLOW"}]},
{"keyPrefix": "s3://BUCKET/docs/engineering/",
"aclEntries": [{"Name": "[email protected]", "Type": "USER", "Access": "ALLOW"},
{"Name": "[email protected]", "Type": "USER", "Access": "ALLOW"}]},
{"keyPrefix": "s3://BUCKET/docs/sales/",
"aclEntries": [{"Name": "[email protected]", "Type": "USER", "Access": "ALLOW"}]}
]示例文件还为所有人提供 docs/it/。然后创建数据源。对于托管知识库,每个连接器的类型均为 MANAGED_KNOWLEDGE_BASE_CONNECTOR,connectorParameters.type 选择源:
ds = agent.create_data_source(
knowledgeBaseId=kb["knowledgeBaseId"],
name="s3-docs-acl",
dataSourceConfiguration={
"type": "MANAGED_KNOWLEDGE_BASE_CONNECTOR",
"managedKnowledgeBaseConnectorConfiguration": {
"connectorParameters": {
"type": "S3",
"version": "1",
"connectionConfiguration": {"bucketName": BUCKET, "bucketOwnerAccountId": ACCOUNT_ID},
"filterConfiguration": {"inclusionPrefixes": ["docs/"]},
"aclEnabled": True,
"aclConfiguration": {"globalAccessControlListS3Uri": f"s3://{BUCKET}/acl/global-acl.json"},
}
},
},
)["dataSource"]数据源创建后,aclEnabled 无法更改。CreateDataSource 是异步的,因此需等待状态变为 AVAILABLE。然后调用 StartIngestionJob 并等待 COMPLETE。同步过程会读取文档和 ACL 文件,并为每个文档索引其 ACL。在示例中,所有 11 个文档均被扫描并索引,0 失败。未被任何 ACL 条目覆盖的文档不会被摄取,电子邮件不匹配任何条目的用户将从此数据源获得无结果。
该模型同样适用于从源系统爬取权限的连接器,例如 Microsoft SharePoint、Google Drive 和 Atlassian Confluence。在那里,权限来自源系统,组从源解析,知识库还会实时检查每个结果与源。您的应用代码无需更改:它仍然在 userContext 中传递用户的电子邮件。完整列表请参阅访问控制列表感知启用。
步骤 2:创建内存资源并设计命名空间
一个内存资源服务于每个用户。按用户分离来自命名空间设计:长期记录存储在包含 {actorId} 的命名空间下,确保每个用户的记忆不会混淆。IAM 策略可以进一步限制对特定命名空间路径的访问,从而即使应用代码出错,也能保证用户只能访问自己的记忆。
通过为每个用户分配唯一的 actorId(例如 Cognito sub),并将长期记忆命名空间设置为类似 /anycompany/{actorId}/,您可以实现严格的每用户隔离。在生产环境中,添加 IAM 条件,要求请求中的 actorId 与调用者的身份匹配,从而在服务层面强制隔离。
这样,多用户共享的知识库和内存资源就能安全地支持具备记忆的智能体,同时满足文档级 ACL 和记忆隐私的要求。