用 Agentic Retrieve 在 Amazon Bedrock Managed Knowledge Base 上构建带记忆的 AI 智能体
Build memory-aware AI agents with Agentic Retrieve on Amazon Bedrock Managed Knowledge Base
AWS 介绍在 Amazon Bedrock Managed Knowledge Base 的 AgenticRetrieveStream 请求中加入 memoryConfiguration,把 AgentCore memory 作为检索来源,实现会话恢复、事实提取与按用户隔离。
知识增强型应用的用户期望它能记住自己,而不仅仅是搜索得好。他们会提出只有在上一轮对话语境下才说得通的追问。他们期望关于某项政策或流程的回答能反映自己上个月告诉应用的信息。而且他们仍然期望每个回答都基于自己有权阅读的文档,并附上引用。无论这个应用是客户支持助手、SaaS 产品内的文档聊天,还是基于公司政策的内部助手,期望都是一样的。
满足这一期望并不容易,因为能让搜索更精准的上下文存在于知识库之外。用户的位置、角色或产品层级,往往是在几周前一次不相关的对话中提到的。要利用这些信息,应用必须存储每一次对话,从中提取持久事实,判断哪些事实对当前问题重要,并将它们注入请求。当许多用户共用这个应用时,上述每一步还必须按用户隔离,每一份文档也是如此。
Amazon Bedrock Managed Knowledge Base 和 Amazon Bedrock AgentCore memory(Amazon Bedrock AgentCore 的一项能力) 现在接管了这些步骤:存储每一次对话、从中提取事实,并将相关事实带入搜索。你只需在 AgenticRetrieveStream 请求中添加一个 memoryConfiguration 即可开启此功能,这会让 AgentCore memory 成为与知识库并列的检索来源。在同一次调用中,服务会恢复对话,规划器会自行判断何时关于用户的事实会有帮助。它从长期记忆中检索该事实,并用它来组织发送给知识库的子查询。生成回答后,服务会将该轮对话保存回记忆。同一个请求还携带一个 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)标识用户的内存,经过验证的 email 向知识库的 ACL 过滤器标识用户。三名测试用户登录:两名工程师 Maya 和 Liam,以及一名销售人员 Sofia。本文中的跟踪摘录取自 GitHub 仓库中示例应用程序的一次运行。
图 1:具备内存感知能力的员工助手架构。应用程序对用户进行身份验证并构造请求(步骤 1–4)。Amazon Bedrock Managed Knowledge Base 恢复会话、检索信息、返回答案,并将交互保存到 AgentCore 内存(步骤 5–8)。短期事件和长期记录属于同一个内存资源。
- 员工使用 Cognito 登录并收到 ID 令牌,即由用户池签名的 JSON Web Token(JWT)。
- 应用程序的 API 验证令牌——生产环境中是 Amazon API Gateway JWT 授权方,示例中是一个小型 FastAPI 服务。未经身份验证的请求不会到达处理程序。
- 处理程序从已验证的令牌中读取两个声明:
sub成为内存actorId和命名空间,email成为userContext.userId。客户端请求体仅携带{ question, sessionId? }。然后,处理程序为此用户代入应用程序的 IAM 角色,并带有会话标签userId=<sub>。 - 处理程序调用
AgenticRetrieveStream,以知识库作为检索器、userContext,以及绑定到该用户的memoryConfiguration。 - Managed Knowledge Base 从 AgentCore 内存中的短期内存(STM)恢复由
sessionBinding标识的参与者和会话的对话历史。 - Managed Knowledge Base 基于
userContext从知识库中进行带 ACL 过滤的检索。它还可以通过推测性检索或由规划器选择的内存搜索来检索用户配置的长期内存。 - Managed Knowledge Base 将带引用的答案和跟踪事件流式传输回处理程序。处理程序使用关联 ID 记录跟踪信息,并将答案和跟踪信息转发到 UI。
- 使用
persistenceMode: DEFAULT,服务将问题和生成的答案保存到会话中。然后,AgentCore 内存根据配置的策略异步提取长期记录。
图 2:使用 userContext 和 memoryConfiguration 的一次 AgenticRetrieveStream 轮次。第一个箭头和最后一个箭头之间的所有内容都是服务的工作。
Managed Knowledge Base 负责摄取、ACL 过滤、索引、排序、规划、检索和生成。借助 memoryConfiguration,它还负责会话恢复、内存搜索和持久化。AgentCore 内存负责存储、保留、加密和提取。你的应用程序负责身份验证、UI 以及从令牌中读取用户身份。没有对话表:当 UI 列出或重新打开对话时,它读取的是同一个内存资源。
身份如何映射到请求
每个值都由应用程序从已验证的 ID 令牌派生。没有任何值来自请求体。
| 请求字段 | 派生自 | 作用域 | 由谁强制执行 |
userContext.userId |
ID 令牌 email(已验证,在用户池中不可变) |
可以检索哪些文档 | 知识库 ACL 过滤 |
memoryConfiguration.sessionBinding.actorId |
ID token sub |
恢复并写入谁的短期记忆,以及长期命名空间中的 {actorId} |
AgentCore 记忆键控,外加一个 IAM 条件 |
memoryConfiguration.sessionBinding.sessionId |
由应用程序为新对话生成。与 ListSessions 一起列出 |
该 actor 内的哪个对话 | 以 actorId 为键 |
memoryConfiguration.retrievalConfigs[0].namespacePath |
/anycompany/<sub> |
规划器可以搜索哪些长期记录 | 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/<folder>/ 下。Amazon S3 本身没有可供爬取的权限系统,因此你在同一存储桶中的全局 ACL 文件中提供 ACL。每个条目将一个 S3 前缀映射到可读取它的电子邮件:
[
{"keyPrefix": "s3://BUCKET/docs/hr/",
"aclEntries": [{"Name": "maya@example.com", "Type": "USER", "Access": "ALLOW"},
{"Name": "liam@example.com", "Type": "USER", "Access": "ALLOW"},
{"Name": "sofia@example.com", "Type": "USER", "Access": "ALLOW"}]},
{"keyPrefix": "s3://BUCKET/docs/engineering/",
"aclEntries": [{"Name": "maya@example.com", "Type": "USER", "Access": "ALLOW"},
{"Name": "liam@example.com", "Type": "USER", "Access": "ALLOW"}]},
{"keyPrefix": "s3://BUCKET/docs/sales/",
"aclEntries": [{"Name": "sofia@example.com", "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},AgentCore memory 在提取时从每个事件中解析出它。有两个选择很重要。
策略。这两种策略提取的内容不同。摘要策略会为每段对话生成摘要,因此能捕捉用户顺带提到的事实,例如“我在法兰克福办公室用 Mac”。这些事实正是让之后关于(比如)PTO 的回答个性化的依据。用户偏好策略会把明确表达的偏好提取为结构化记录(“偏好简短的项目符号回答,不要表格”“总是先部署到 eu-central-1”),而不会把顺带提及的内容当作偏好。摘要给你的是“我们讨论过什么”。偏好给你的是“这个人希望被怎样回答”。两者都要用。
布局。retrievalConfigs 只接受一个条目,因此单个 namespacePath 必须覆盖规划器应当为用户看到的全部内容。把 {actorId} 直接放在根下:这样 namespacePath: "/anycompany/<sub>" 就能覆盖个人资料和每段对话摘要。像 /anycompany/profile/{actorId} 和 /anycompany/summaries/{actorId} 这样的布局会让一个条目只能覆盖其中之一。
memory = control.create_memory(
name="anycompany_assistant_memory",
eventExpiryDuration=30, # days; raw conversation events expire after this
# encryptionKeyArn=CMK_ARN, # optional customer managed key
memoryStrategies=[
{"userPreferenceMemoryStrategy": {
"name": "EmployeeProfile",
"namespaces": ["/anycompany/{actorId}/profile"],
}},
{"summaryMemoryStrategy": {
"name": "ConversationSummaries",
"namespaces": ["/anycompany/{actorId}/summaries/{sessionId}"],
}},
],
)["memory"]等待记忆达到 ACTIVE。创建记忆不需要用户或 actorId,因此第 2 步和第 3 步的顺序无关紧要。不会按用户预置任何内容:新的 Cognito 用户第一次提问时就会成为新的 actor。
第 3 步:设置 Cognito 并授予应用程序权限
创建一个用户池和一个不带客户端密钥的应用客户端。电子邮件决定用户可读取哪些文档,因此要将其设为必填、已验证且用户不可更改:
pool_id = idp.create_user_pool(
PoolName="anycompany-assistant-employees",
AutoVerifiedAttributes=["email"],
Schema=[{"Name": "email", "Required": True, "Mutable": False, "AttributeDataType": "String"}],
AdminCreateUserConfig={"AllowAdminCreateUserOnly": True},
)["UserPool"]["Id"]Mutable 在用户池创建后无法更改。如果电子邮件可变,已登录用户就可以把自己的电子邮件改成同事的地址。如果你的用户从 Okta 或 Microsoft Entra ID 联合登录,请将 IdP 的电子邮件映射到此属性,使其与数据源 ACL 中的电子邮件一致。
示例启用了 USER_PASSWORD_AUTH,以便本地 UI 和测试可以直接登录。生产应用程序通常使用 Cognito 托管登录或 AWS Amplify。
为应用程序设置 IAM 角色。后端会按用户假定该角色一次,并带上会话标签 userId=<sub>,每条记忆语句都以该标签为条件。以下是示例运行时使用的完整策略:
{
"Version": "2012-10-17",
"Statement": [
{ "Sid": "AgenticRetrieve", "Effect": "Allow",
"Action": "bedrock:AgenticRetrieveStream", "Resource": "*" },
{ "Sid": "KnowledgeBaseRetrieval", "Effect": "Allow",
"Action": ["bedrock:Retrieve", "bedrock:GetDocumentContent"],
"Resource": "arn:aws:bedrock:us-west-2:111122223333:knowledge-base/KB_ID" },
{ "Sid": "PlannerAndGeneration", "Effect": "Allow",
"Action": "bedrock:InvokeModelWithResponseStream", "Resource": "*" },
{ "Sid": "MemoryDescribe", "Effect": "Allow",
"Action": "bedrock-agentcore:GetMemory",
"Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:memory/MEMORY_ID" },
{ "Sid": "MemorySessionsScopedToCaller", "Effect": "Allow",
"Action": ["bedrock-agentcore:ListEvents", "bedrock-agentcore:CreateEvent",
"bedrock-agentcore:ListSessions"],
"Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:memory/MEMORY_ID",
"Condition": {"StringEquals": {"bedrock-agentcore:actorId": "${aws:PrincipalTag/userId}"}} },
{ "Sid": "MemoryRecordsScopedToCaller", "Effect": "Allow",
"Action": ["bedrock-agentcore:RetrieveMemoryRecords", "bedrock-agentcore:ListMemoryRecords"],
"Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:memory/MEMORY_ID",
"Condition": {"StringLike": {"bedrock-agentcore:namespacePath": "/anycompany/${aws:PrincipalTag/userId}/*"}} }
]
}ListEvents 与 sessionBinding 一起必需,RetrieveMemoryRecords 与 retrievalConfigs 一起必需,当 persistenceMode 为 DEFAULT 时需要 CreateEvent。ListSessions 和 ListMemoryRecords 用于应用程序自身的读取(对话列表和“记忆对你了解什么”视图),不用于 AgenticRetrieveStream。该角色的信任策略允许来自后端自身身份(生产环境中为 AWS Lambda 执行角色或 Amazon Elastic Container Service (Amazon ECS) 任务角色)的 sts:AssumeRole、sts:TagSession 和 sts:SetSourceIdentity。如果记忆使用客户托管密钥,请在该密钥上添加 kms:Decrypt。
第 4 步:从令牌中读取用户,然后构建请求
验证 ID 令牌并读取两个声明。只有 ID 令牌携带 email。访问令牌不携带:
@dataclasses.dataclass(frozen=True)
class Principal:
sub: str # -> memory actorId and namespace
email: str # -> userContext.userId (document ACLs)
def namespace_path(self, root: str) -> str:
return f"{root}/{self.sub}" # resolved literal, e.g. /anycompany/a8e1b390-...
def verify(id_token: str) -> Principal:
key = jwks.get_signing_key_from_jwt(id_token) # public keys from {issuer}/.well-known/jwks.json
claims = jwt.decode(id_token, key.key, algorithms=["RS256"], issuer=ISSUER, audience=CLIENT_ID)
if claims.get("token_use") != "id" or claims.get("email_verified") is not True:
raise PermissionError("a verified ID token is required")
return Principal(sub=claims["sub"], email=claims["email"].lower())jwt.decode 会检查签名、签发者(你的用户池)、过期时间和受众(你的应用客户端)。有关声明的详细信息,请参阅 了解身份 (ID) 令牌。使用 API Gateway 时,JWT 授权方会执行相同的检查,并将声明传递给处理程序。
接下来,获取用户的 AWS 凭证。后端会为此用户假定应用程序角色,并缓存会话直到临近过期:
creds = sts.assume_role(
RoleArn=APP_ROLE_ARN,
RoleSessionName=f"user-{principal.sub}",
SourceIdentity=principal.sub,
Tags=[{"Key": "userId", "Value": principal.sub}],
)["Credentials"]现在,为此用户进行的每次调用(包括代理式检索代表调用方进行的记忆调用)都以 assumed-role/anycompany-assistant-app-role/user-<sub> 运行,并携带第 3 步中策略所检查的标签。
决定 sessionId。对于新对话,应用程序会生成一个,例如 "conv-" + uuid4().hex,并将其返回给客户端。要延续对话,客户端会将其发回。要展示用户的对话,请使用用户的 actorId 调用 ListSessions:
def list_conversations(principal):
try:
resp = memory.list_sessions(memoryId=MEMORY_ID, actorId=principal.sub, maxResults=50)
except memory.exceptions.ResourceNotFoundException:
return [] # the user has not asked anything yet, so there is no actor
return [{"sessionId": s["sessionId"], "createdAt": s["createdAt"].isoformat()} for s in resp["sessionSummaries"]]你不需要自己的表来将用户映射到会话。接受来自客户端的 sessionId 是安全的,因为短期记忆以 (memoryId, actorId, sessionId) 为键,而 actorId 来自令牌。如果 Liam 发送了 Maya 的 sessionId,它命名的是 Liam 自己空间内的一个会话,而该空间是空的。Agentic 检索本身并不验证你提供的 actorId、sessionId 或命名空间是否属于发起请求的用户,因此它们绝不能来自客户端。仅当你需要记忆不保存的数据(例如对话标题)时,才保留你自己的会话表。
然后构建请求:
def build_request(principal, question, session_id):
return {
# With sessionBinding, messages carries ONLY the current question.
"messages": [{"role": "user", "content": {"text": question}}],
"retrievers": [{"configuration": {"knowledgeBase": {"knowledgeBaseId": KB_ID}},
"description": KB_DESCRIPTION}],
# Document ACLs: only documents this email may read are retrieved.
"userContext": {"userId": principal.email},
"agenticRetrieveConfiguration": {
"foundationModelType": "MANAGED",
"rerankingModelType": "MANAGED",
"maxAgentIteration": 3,
},
"generateResponse": True,
"memoryConfiguration": {
"memoryId": MEMORY_ID,
"sessionBinding": {"actorId": principal.sub, "sessionId": session_id},
"persistenceMode": "DEFAULT",
"retrievalConfigs": [{"namespacePath": principal.namespace_path("/anycompany")}],
},
}没有 userContext,启用了 ACL 的数据源将完全不返回任何结果。将请求与它所替代的无状态处理程序进行比较:
history = history_table.query(KeyConditionExpression=Key("sessionId").eq(session_id))
messages = [*replay(history), {"role": "user", "content": {"text": question}}]
response = runtime.agentic_retrieve_stream(messages=messages, retrievers=..., agenticRetrieveConfiguration=...)
history_table.put_item(Item={"sessionId": session_id, "q": question, "a": consume(response)})调用前的查询和调用后的写入都消失了,并且 messages 只有一个元素。sessionBinding 附带三条规则,每条规则都由特定的 ValidationException 强制执行。第一,messages 仅携带当前问题,因此你为每个请求选择一个历史来源。第二,persistenceMode: DEFAULT(默认值)将问题和生成的答案作为一个事件写入,因此它需要 generateResponse: true。第三,仅 memoryId 是无效的。persistenceMode: NONE 恢复历史且不写入任何内容,用于审计或重放视图。
第 5 步:更新客户端契约并渲染历史
客户端发送 { question, sessionId? }。对于新对话,应用程序生成一个 sessionId 并将其作为第一个流式帧返回。客户端在后续轮次中回传它,并在重新开始时省略它。
由于记忆资源归你所有,应用程序直接读取它以渲染对话:
def conversation_history(principal, session_id):
resp = memory.list_events(memoryId=MEMORY_ID, actorId=principal.sub, sessionId=session_id,
includePayloads=True, maxResults=100)
return [{"role": p["conversational"]["role"].lower(), "text": p["conversational"]["content"]["text"]}
for ev in sorted(resp["events"], key=lambda e: e["eventTimestamp"])
for p in ev["payload"] if "conversational" in p]每个持久化的轮次恰好是一个事件,包含两个有效载荷:用户的问题和最终答案。因此,历史记录会渲染为一份干净的转录文本,并且仍可供其他 AgentCore 记忆客户端使用。
第 6 步:从跟踪中验证
跟踪会逐轮告诉你知识库和记忆做了什么:
| 跟踪事件 | 出现时机 | 需要查看的内容 |
SessionHistoryLoad |
第一个事件,只要设置了 sessionBinding |
_memory_event_count 和 _memory_message_count,在新会话上均为 0 |
SpeculativeRetrieval |
规划之前 | 在新会话上,retrievalMetadata 还会列出 BedrockAgentCoreMemory。记忆项带有 _memory_* 元数据且没有文本。知识库项带有 _source_uri |
Planning |
每次迭代 | actions[].memoryRetrieve 表示规划器选择搜索记忆,并附上它编写的查询 |
Retrieval 与 retrievalType: BedrockAgentCoreMemory |
每个计划的记忆操作 | _memory_record_count。计数为 0 是正常结果 |
带有 status: FAILED 的记忆事件 |
记忆不可用或访问被拒绝 | failures[].message。记忆是尽力而为的:请求继续,答案从知识库生成 |
以下运行展示了该行为。摘录为逐字内容,为长度而做了裁剪。
文档 ACL:Maya 和 Sofia,同一个问题。“每周待命津贴是多少?”待命指南位于 docs/engineering/。Maya 的检索包含了 docs/engineering/oncall.md,答案是“每周 500 USD 或 450 EUR”。Sofia 的推测性检索和规划器的后续子查询只返回了 HR 和销售块:
Planning/SUCCEEDED actions: retrieve("on-call stipend compensation policy")
Retrieval/SUCCEEDED [BedrockKnowledgeBase] 9 items # docs/hr/*, docs/sales/commission-plan.md她的答案说,在她可访问的来源中没有记录待命津贴。应用程序没有做出访问决定。它传递了 userContext.userId: "sofia@example.com",由知识库进行过滤。佣金计划的情况则相反:Sofia 获得 12% 的加速器,而 Maya 的检索不包含 docs/sales/。
第 1 轮:Maya,新对话。“如何在我的笔记本电脑上设置 VPN?我在法兰克福办公室使用 Mac。”
SessionHistoryLoad/SUCCEEDED "Restored 0 short-term memory event(s)"
SpeculativeRetrieval/SUCCEEDED [BedrockAgentCoreMemory, BedrockKnowledgeBase] 10 items
Planning/SUCCEEDED答案给出了法兰克福网关(vpn-fra.anycompany.example)以及 macOS 的操作步骤。随后,会话上的 ListEvents 显示了一个包含两个负载的事件。
第 2 轮:Maya,同一对话。“它每隔几分钟就断连一次。我该试什么?”该请求只携带了这一句话:
{"step": "SessionHistoryLoad", "status": "SUCCEEDED",
"message": "Restored 1 short-term memory event(s)",
"retrievalResponse": [{"metadata": {"_memory_session_id": "conv-d25dccca6cbf47a6af893621e546905d",
"_memory_event_count": 1, "_memory_message_count": 2}}]}规划器发送了 retrieve("VPN disconnects every few minutes troubleshooting") 和 retrieve("Cisco Secure Client macOS frequent disconnect fix")。答案解析了“它”,并指向 iCloud Private Relay,即指南中针对 macOS 的原因。在延续的会话上,SpeculativeRetrieval 只查询知识库。该步骤中的长期记忆查找发生在新会话上。
第 3 轮:Maya,稍后的一个新对话。“我每年有多少天带薪休假,未使用的天数可以结转吗?”她的办公室决定答案,而她在这个对话中从未提及。推测性检索用原始问题搜索长期记忆,找到了一条记录:
{"step": "SpeculativeRetrieval",
"retrievalMetadata": [{"identifier": "JQUFTMTNZV", "retrievalType": "BedrockKnowledgeBase"},
{"identifier": "anycompany_assistant_memory-5llXYu8f2i", "retrievalType": "BedrockAgentCoreMemory"}],
"retrievalResponse": [
{"content": {"mimeType": "text/plain", "text": "# AnyCompany Paid Time Off (PTO) Policy ..."},
"metadata": {"_document_title": "pto-policy.md", "_data_source_type": "S3",
"_source_uri": "https://.../docs/hr/pto-policy.md"},
"sourceRetriever": {"identifier": "JQUFTMTNZV"}},
{"content": {"mimeType": "text/plain"},
"metadata": {"_memory_strategy_id": "ConversationSummaries-JFDHQVB4VU",
"_memory_query": "How many days of PTO do I get per year, and do unused days carry over?",
"_memory_namespace_path": "/anycompany/a8e1b390-10f1-70d9-ee85-b68b610ee0c4",
"_memory_record_count": 1},
"sourceRetriever": {"identifier": "anycompany_assistant_memory-5llXYu8f2i"}}]}知识库条目和记忆条目共用一个 retrievalResponse。通过 sourceRetriever.identifier 或 _memory_* 键来区分它们。该记录是她 VPN 对话的摘要。这就足够了:规划器直接给出了答案,答案说“由于你的记忆表明你位于法兰克福办公室……你每年有 30 天带薪休假,于 1 月 1 日全额授予,任何未使用的天数必须在次年 3 月 31 日前使用。”一个来自 IT 对话的事实使一个 HR 答案个性化。
第 4 轮:Liam,新对话,相同问题。相同的处理程序,相同的记忆资源,不同的令牌。推测性检索没有找到关于他的任何内容,因此规划器决定用自己的查询搜索记忆:
{"step": "Planning", "status": "SUCCEEDED",
"actions": [{"memoryRetrieve": {"inputQuery": {"text": "employee office location"},
"memoryId": "anycompany_assistant_memory-5llXYu8f2i"}}]}
{"step": "Retrieval", "status": "SUCCEEDED",
"message": "Retrieved 0 long-term memory record(s)",
"retrievalMetadata": [{"identifier": "anycompany_assistant_memory-5llXYu8f2i", "retrievalType": "BedrockAgentCoreMemory"}],
"retrievalResponse": []}Liam 收到了所有三个办公室的表格,以及一个要求他说出自己所在办公室的请求。应用程序选择规划器可以查看的位置。规划器决定是否查看以及询问什么:只有当规划器决定另一次记忆搜索会有帮助时,才会出现 memoryRetrieve 操作。使用 Liam 的令牌通过历史端点读取 Maya 的 sessionId 返回了空列表。
![]() |
![]() |
图 3:来自两个用户的相同问题。Maya 的跟踪显示记忆命中以及针对法兰克福的答案。Liam 的跟踪显示零条记忆记录和通用表格。
长期提取是异步的,并在轮次持久化后运行。在我们的运行中,第一条记录在第 2 轮后 81 秒出现,但时间并非承诺。为最终可用性而设计。在此对话中陈述的事实不保证在下一个对话中立即检索到。示例在运行第 3 轮之前轮询 ListMemoryRecords。
安全与多用户隔离
在本演练中,应用程序进行身份验证。知识库进行过滤。ACL 感知检索是过滤,不是授权。仅从带有 email_verified: true 的已验证 ID 令牌中获取电子邮件,使其在池中不可变,并处理电子邮件重用:如果某个地址被重新分配给另一个人,该人将获得旧所有者的文档访问权限。知识库故障关闭:没有 ACL 的文档或 ACL 错误意味着结果更少,而不是更多。如果结果缺失,请检查电子邮件是否与 ACL 条目匹配。
身份来自令牌(步骤 4),记忆也是如此:actorId 和命名空间来自已验证的 sub,绝不来自客户端。
IAM 条件键,作为纵深防御。 AgentCore memory 在 ListEvents、CreateEvent 和 ListSessions 上公开 bedrock-agentcore:actorId,并在 RetrieveMemoryRecords 和 ListMemoryRecords 上公开 bedrock-agentcore:namespacePath。代理检索在请求期间发出的记忆调用会根据调用方身份进行授权。这就是为什么调用方的策略必须授予这些操作,以及为什么第 3 步中的条件适用于它们。使用为 Maya 代入的会话,绑定到 Maya 的 actorId 的请求会正常进行。绑定 Liam 的 actorId 的请求正是此策略所防范的缺陷,并且它在每个记忆操作上都会被拒绝:
SessionHistoryLoad/FAILED failures: ["AccessDeniedException"]
SpeculativeRetrieval/SUCCEEDED failures: ["AccessDeniedException"] # memory leg denied, KB leg answered没有向 Liam 的记忆写入任何内容:他的会话计数保持为 0。答案仍然是从知识库生成的。由于每个用户都有自己的角色会话,AWS 还能看到每次调用是为哪个用户发出的:调用方是带有 SourceIdentity=<sub> 的 assumed-role/anycompany-assistant-app-role/user-<sub>,这是会话持有者无法更改的。
还有两点。记忆是客户拥有的资源,你账户中的其他系统也可能写入它。将其内容视为输入,并通过 policyConfiguration 将 Amazon Bedrock guardrail 附加到请求。并规划数据生命周期。原始事件按 eventExpiryDuration 过期,但提取的记录不会。因此,用户删除工作流涵盖参与者的会话的 DeleteEvent 以及参与者命名空间下的 DeleteMemoryRecord。
可观测性和故障行为
使用每轮的相关 ID 记录完整跟踪。规划器的子查询与其最终结果一样值得审计。AWS/Bedrock/KnowledgeBases 为 Operation=AgenticRetrieveStream 报告 Invocations、ClientErrors 和 TotalIterationCount。AWS/Bedrock-AgentCore 为每个记忆操作报告 Invocations、Latency、Errors 和 UserErrors,并为提取的每个策略报告 InputTokenUsage/OutputTokenUsage。启用 Amazon CloudWatch Transaction Search 后,AgentCore Observability(Amazon Bedrock AgentCore 的一项能力)会端到端显示一轮的跨度。
记忆操作在设计上是尽力而为的。如果记忆调用失败或被拒绝,请求不会失败。跟踪会携带带有失败消息的 FAILED 记忆事件,并且该轮在没有该记忆的情况下继续。答案是从知识库生成的。决定你的 UI 是否显示该降级状态。
注意事项
- 在对话的生命周期内使用稳定的
sessionId。API 接受每个请求的新 ID,但新 ID 会静默地破坏连续性,并每轮生成一条摘要记录。 - 使用
namespacePath访问用户的所有长期记录。retrievalConfigs接受一个条目,最多五个metadataFilters。namespace按前缀匹配,namespacePath按层次结构匹配,因此namespacePath适合根下的每用户 ID。提供完全解析的命名空间,因为像/anycompany/{actorId}这样的模板会被拒绝。 - 预期只恢复
USER和ASSISTANT对话事件。其他系统写入的具有TOOL或OTHER角色的事件会被跳过。 - 当你的应用程序需要精确控制每个请求携带的历史记录时,继续发送
messages而不是sessionBinding。例如,你现有的历史存储可能是对话的记录系统,或者你可能在发送前编辑或修订历史记录。使用sessionBinding,服务会为你恢复并持久化对话。你不能在一个请求中组合两者。 - 一个请求最多可以携带五个知识库。当有多个检索器时,规划器会根据知识库
description路由每个子查询,因此请仔细编写它。 - 规划延迟和成本。会话恢复会增加约 200 毫秒。在我们的运行中,使用托管模型时,一个包含一个知识库、ACL 和记忆的完整轮次耗时 4–10 秒。规划迭代是驱动该时间的主要因素,而非记忆。这些是观测到的数据,并非服务承诺。Agentic 检索按每次调用加底层检索计费,调用期间进行的记忆操作按 AgentCore 记忆用量计费。详情请参阅 Amazon Bedrock 定价 和 Amazon Bedrock AgentCore 定价。
清理
在示例中运行 python infra/teardown.py,以删除知识库、S3 存储桶及其对象、记忆资源(包括对话历史和长期记录)、Cognito 用户池以及 IAM 角色。
结论
Amazon Bedrock Managed Knowledge Base 已经以服务形式为您提供了检索栈。该栈涵盖数据摄取、文档 ACL、索引、排序,以及 AgenticRetrieveStream 中将难题转化为带引用答案的规划循环。借助 memoryConfiguration,同一次调用现在会携带对话和用户历史。对于多用户应用,这省去了对话存储、历史重放和提取管道。剩下的是一份简短的责任清单。对用户进行身份验证,并从 ID 令牌中读取两个声明:将已验证的电子邮件作为 userContext 传入,以便知识库筛选文档;并将 sub 用作一个记忆资源的 actorId,其命名空间以 {actorId} 为根。在每用户角色会话上使用 IAM 条件键作为第二道防线,该防线在 agentic 路径中持续有效。
要开始使用,请从 GitHub 仓库 部署示例。然后阅读 AgenticRetrieveStream API 参考、访问控制列表感知启用 和 将 AgentCore 记忆与 agentic 检索配合使用。关于检索循环本身,请参阅 Amazon Bedrock Managed Knowledge Base 的 Agentic 检索。关于记忆概念,请参阅 Amazon Bedrock AgentCore 记忆:构建上下文感知代理。
关于作者
Peng Yang
Peng 是 Amazon Bedrock Managed Knowledge Base 团队的高级软件工程师。过去几年,他的工作涵盖 Amazon Kendra、Amazon Q Business、AWS Quick 和 Amazon Bedrock Managed Knowledge Base 中的检索和生成式 AI 系统。
Renya Kujirada
Renya 是 Amazon Web Services Japan 的 AI 专家解决方案架构师。他是日本 Amazon Bedrock AgentCore 的技术负责人,与各行业客户合作开发代理、设计代理平台并微调 LLM。加入 AWS 之前,他曾担任数据科学家,开发深度学习模型并构建代理驱动的解决方案。他入选了 2025 年 Japan AWS Top Engineer 和 AWS Community Builder。
Jason Sheng
Jason 是 Amazon Bedrock Knowledge Bases 的高级软件工程师。他专注于构建机器学习和生成式 AI 服务,在过去六年中为 Amazon Q、Bedrock Knowledge Bases、Amazon Kendra 和 Amazon Translate 做出了贡献。
Siddhant Sahu
Siddhant 是 AWS 的高级产品经理,也是 Amazon Bedrock Managed Knowledge Base 的唯一负责人,作为产品负责人负责其战略、路线图和发布。他构思并推出了该产品的智能体检索和应用程序连接器,使 AI 智能体能够在 SharePoint、Confluence、S3 等关键业务应用中,对企业数据执行复杂的搜索查询。自 2026 年 6 月发布以来,该服务已被 OpenAI、Syngenta、MRH Trowe、Sony 以及其他基于企业数据构建 AI 智能体的企业采用。
来源:AWS Machine Learning Blog · aws.amazon.com



