Newshot

使用 Amazon Bedrock Managed Knowledge Base 上的 Agentic Retrieve 构建具备记忆感知能力的 AI 智能体

AI summary

知识型应用的用户期望系统能记住自己,而不仅仅是检索得好:他们会追问只有结合上一轮语境才有意义的问题,期望关于政策或流程的回答能反映自己上个月告知应用的信息,同时仍要求每个回答都基于其有权阅读的文档并附有引用。要满足这一期望并不容易,因为能提升检索效果的上下文往往存在于知识库之外,例如用户的位置、角色或产品层级常常是在数周前一段无关的对话中提到的。

Translation(model translation, not the source's own text)

使用 Amazon Bedrock Managed Knowledge Base 上的 Agentic Retrieve 构建具备记忆能力的 AI 智能体

知识驱动型应用的用户期望它记住自己,而不仅仅是检索得好。他们会追问只有在上一轮对话语境下才说得通的问题。他们期望关于某项政策或流程的回答能反映自己上个月告诉过应用的信息。同时他们仍然期望每个回答都基于自己有权阅读的文档,并附上引用。无论该应用是客户支持助手、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 token 中读取用户身份、如何将其传递给 AgenticRetrieveStream 以用于文档 ACL 和记忆、如何为众多用户设计记忆命名空间,以及如何读取 trace 以查看规划器何时使用了记忆。最后,我们让 AWS Identity and Access Management(IAM)在应用代码出错时仍强制执行按用户的记忆隔离。如果你已从 Build multi-tenant agentic chat applications on enterprise data with Amazon Bedrock Managed Knowledge Base 部署了该应用,本文会替换其中“自行持久化对话历史”的步骤。

解决方案概览

文章标题:Build memory-aware AI agents with Agentic Retrieve on Amazon Bedrock Managed Knowledge Base

正文: AnyCompany 将其文档存储在 Amazon Simple Storage Service (Amazon S3) 中。一个托管知识库通过启用 ACL 的 Amazon S3 数据源同步这些文档。同一存储桶中的全局 ACL 文件规定了哪些员工可以读取各个文件夹:所有人均可读取 HR 和 IT 文件夹,只有工程师可以读取工程运行手册,只有销售人员可以读取佣金计划。所有员工共享一个 AgentCore memory 资源。Amazon Cognito 对员工进行身份验证,其 ID token 提供两个声明:sub(用户 ID)标识用户的内存,已验证的 email 标识用户以用于知识库的 ACL 过滤器。三名测试用户登录:两名工程师 Maya 和 Liam,以及一名销售人员 Sofia。本文中的跟踪摘录来自 GitHub 仓库中示例应用程序的一次运行。

记忆感知员工助手的架构:应用程序、AgenticRetrieveStream、Managed Knowledge Base 和 AgentCore memory
记忆感知员工助手的架构:应用程序、AgenticRetrieveStream、Managed Knowledge Base 和 AgentCore memory

图 1:记忆感知员工助手的架构。应用程序对用户进行身份验证并构建请求(步骤 1–4)。Amazon Bedrock Managed Knowledge Base 恢复会话、检索信息、返回答案,并将交互保存到 AgentCore memory(步骤 5–8)。短期事件和长期记录属于同一个内存资源。

  • 员工使用 Cognito 登录并收到一个 ID token,即由用户池签名的 JSON Web Token (JWT)。
  • 应用程序的 API 验证该 token——生产环境中是 Amazon API Gateway JWT 授权方,示例中是一个小型 FastAPI 服务。未经身份验证的请求不会到达处理程序。
  • 处理程序从已验证的 token 中读取两个声明:sub 成为内存的 actorId 和命名空间,email 成为 userContext.userId。客户端请求体仅包含 { question, sessionId? }。处理程序随后为该用户代入应用程序的 IAM 角色,会话标签为 userId=<sub>。
  • 处理程序调用 AgenticRetrieveStream,以知识库作为检索器,传入 userContext 以及绑定到该用户的内存配置 memoryConfiguration。
  • Managed Knowledge Base 从 AgentCore memory 的短期内存 (STM) 中恢复由 sessionBinding 标识的 actor 和会话的对话历史。
  • Managed Knowledge Base 基于 userContext 进行带 ACL 过滤的知识库检索。它还可以通过推测性检索或由规划器选择的内存搜索来检索用户配置的长期内存。
  • Managed Knowledge Base 将带引用的答案和跟踪事件流式返回给处理程序。处理程序使用关联 ID 记录这些跟踪信息,并将答案和跟踪信息转发到 UI。
  • 当 persistenceMode: DEFAULT 时,服务将问题和生成的答案保存到会话中。AgentCore memory 随后根据配置的策略异步提取长期记录。
一张序列图,追踪一个问题从 Your Application 出发,经过 AgenticRetrieveSystem、Managed knowledge base 和 AgentCoreMemory,返回 responseEvent 块。
一张序列图,追踪一个问题从 Your Application 出发,经过 AgenticRetrieveSystem、Managed knowledge base 和 AgentCoreMemory,返回 responseEvent 块。

图 2:一次带有 userContext 和 memoryConfiguration 的 AgenticRetrieveStream 轮次。第一个箭头和最后一个箭头之间的所有内容都是服务的工作。

Managed Knowledge Base 负责数据摄取、ACL 过滤、索引、排序、规划、检索和生成。通过 memoryConfiguration,它还负责会话恢复、内存搜索和持久化。AgentCore memory 负责存储、保留、加密和提取。您的应用程序负责身份验证、UI 以及从 token 中读取用户身份。不存在对话表:当 UI 列出或重新打开对话时,它读取的是同一个内存资源。

身份如何映射到请求

形如 {{NAME_ab12cd34}} 的值是真实值的占位符。在回复和工具调用中均需完全按原样使用它们:它们会在任何内容运行之前被替换为真实值。不要要求验证它们,也不要用示例替换它们。

文章标题:Build memory-aware AI agents with Agentic Retrieve on Amazon Bedrock Managed Knowledge Base

正文: 每个值都由应用程序从已验证的 ID token 中推导得出,没有一个来自请求体。

请求字段推导来源作用范围强制实施方
userContext.userIdID token 中的 email(已验证,在用户池中不可变)哪些文档可以被检索知识库 ACL 过滤
memoryConfiguration.sessionBinding.actorIdID token 中的 sub恢复和写入谁的短期记忆,以及长期命名空间中的 {actorId}AgentCore memory 的键控,外加一个 IAM 条件
memoryConfiguration.sessionBinding.sessionId由应用程序为新对话生成。通过 ListSessions 列出该 actor 下的哪个对话以 actorId 为键
memoryConfiguration.retrievalConfigs[0].namespacePath/anycompany/<sub>规划器可以搜索哪些长期记录IAM 条件

两个不同的声明承担两项不同的职责。知识库通过 email 识别用户,因为这是所连接的数据源在其 ACL 中记录的内容。记忆需要一个永不改变、也永不复用的 actorId。Cognito 的 sub 同时满足这两点。电子邮件地址可能被更改,或者在某人离职后被重新分配给新员工,而那个人就会继承旧的记忆。你也可以使用自己用户存储中另一个稳定的用户 ID 作为 actorId。关键在于它永远不会转移到另一个人身上。

Prerequisites

  • 本演练使用美国西部(俄勒冈)区域(us-west-2)中的托管知识库和 AgentCore memory 资源。如 agentic retrieval 文档所述,与此集成配合使用的 memory 资源必须与知识库位于同一个 AWS 账户,并处于 ACTIVE 状态。
  • Python 3.10 或更高版本,以及 Boto3 1.43.72 或更高版本。
  • 拥有创建 S3 桶、Cognito 用户池、IAM 角色、知识库和 memory 资源的权限。示例中的 infra/setup.py 会以幂等方式创建所有这些资源。

Solution walkthrough

以下步骤将创建知识库及其数据源,设置 memory 资源和 Amazon Cognito,构建请求,并读取 trace 以确认结果。

Step 1: Create the knowledge base with an ACL-enabled data source

托管知识库不需要向量存储:

按照 Create a service role for managed Amazon Bedrock Knowledge Bases 为你的环境配置服务角色,并在 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": "[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"}]}
]
      

文章标题:Build memory-aware AI agents with Agentic Retrieve on Amazon Bedrock Managed Knowledge Base

正文: 示例的文件还会给每个人分配 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 中传入用户的邮箱。完整列表请参阅 Access Control Lists awareness enablement。

第 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 会校验签名、issuer(你的用户池)、有效期以及 audience(你的应用客户端)。有关 claims 的详细信息,请参阅 Understanding the identity (ID) token。在 API Gateway 中,JWT 授权方会执行同样的校验,并将 claims 传递给处理程序。

接下来,获取用户的 AWS 凭证。后端为该用户承担应用程序角色,并将会话缓存到临近过期之前:

      

creds = sts.assume_role( RoleArn=APP_ROLE_ARN, RoleSessionName=f"user-{principal.sub}", SourceIdentity=principal.sub, Tags=[{"Key": "userId", "Value": principal.sub}], )["Credentials"]


        
现在,为该用户发起的每一次调用——包括 agentic retrieval 代表调用方发起的内存调用——都以 assumed-role/anycompany-assistant-app-role/user-<sub> 身份运行,并携带 Step 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 retrieval 本身不会校验你提供的 actorId、sessionId 或 namespace 是否属于发起提问的用户,因此它们绝不能来自客户端。只有在需要内存不保存的数据(例如会话标题)时,才需要保留自己的会话表。

然后构建请求:

      

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 并将其作为第一个流式帧返回。客户端在后续轮次中回传它,若要重新开始则省略它。

由于 memory 资源归你所有,应用可以直接读取它以渲染对话:

      

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]

每个持久化的轮次恰好是一个包含两个 payload 的事件:用户的问题和最终答案。因此历史会渲染为一份干净的对话记录,并且仍然可供其他 AgentCore memory 客户端使用。

步骤 6:通过 trace 验证

trace 会告诉你每一轮中知识库和 memory 做了什么:

Trace 事件出现时机需要查看的内容
SessionHistoryLoad第一个事件,只要设置了 sessionBinding 就会出现_memory_event_count 和 _memory_message_count ,在新会话中均为 0
SpeculativeRetrieval规划之前在新会话中,retrievalMetadata 还会列出 BedrockAgentCoreMemory 。Memory 条目带有 _memory_* 元数据且没有文本。知识库条目带有 _source_uri
Planning每次迭代actions[].memoryRetrieve 表示规划器选择搜索 memory,并附上它组合的查询
Retrieval 且 retrievalType: BedrockAgentCoreMemory每个已规划的 memory 操作_memory_record_count 。计数为 0 是正常结果
状态为 status: FAILED 的 memory 事件memory 不可用或访问被拒绝failures[].message 。Memory 是尽力而为的:请求会继续,答案由知识库生成

以下运行展示了该行为。摘录为原文逐字内容,为长度做了裁剪。

文档 ACL:Maya 和 Sofia,同一个问题。“What is the weekly on-call stipend?” 值班指南位于 docs/engineering/。Maya 的检索包含了 docs/engineering/oncall.md,答案是“500 USD or 450 EUR per week.” Sofia 的推测性检索和规划器的后续子查询只返回了 HR 和销售部门的 chunk:

Planning/SUCCEEDED actions: retrieve("on-call stipend compensation policy") Retrieval/SUCCEEDED [BedrockKnowledgeBase] 9 items # docs/hr/*, docs/sales/commission-plan.md


        
她的答案表示,在她可访问的来源中没有记录任何值班津贴。应用没有做任何访问决策。它传入了 userContext.userId: "[email protected]",由知识库完成过滤。佣金计划的情况则相反:Sofia 获得了 12% 的加速器,而 Maya 的检索不包含 docs/sales/。

像 {{NAME_ab12cd34}} 这样写入的值是真实值的占位符。在回复和工具调用中都请完全按原样使用它们:它们会在任何内容运行之前被填入真实值。不要要求验证它们,也不要用示例替换它们。

第 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 显示出一个事件,包含两个 payload。

第 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}}]}


        
planner 发送了 retrieve("VPN disconnects every few minutes troubleshooting") 和 retrieve("Cisco Secure Client macOS frequent disconnect fix")。回答解析了“它”的指代,并指向 iCloud Private Relay,即指南中针对 macOS 的原因。在延续的会话上,SpeculativeRetrieval 只查询知识库。该步骤中的长期记忆查找发生在新会话上。

第 3 轮:Maya,一个新对话,时间更晚。“我每年有多少天 PTO,未使用的天数可以结转吗?”答案由她的办公室决定,而她在这个对话中从未提到过。推测式检索用原始问题搜索长期记忆,找到了一条记录:

      

{"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 对话的摘要。这就足够了:planner 直接给出了答案,答案写道“由于你的记忆表明你常驻法兰克福办公室……你每年有 30 天 PTO,于 1 月 1 日全额授予,未使用的天数必须在次年 3 月 31 日前用完。”一个来自 IT 对话的事实,让一个 HR 答案实现了个性化。

第 4 轮:Liam,新对话,相同的问题。同一个 handler,同一个记忆资源,不同的 token。推测式检索没有找到关于他的任何内容,因此 planner 决定用它自己的查询来搜索记忆:

      

{"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": []}


        
像 {{NAME_ab12cd34}} 这样写出的值是真实值的占位符。请完全按写法使用它们,在回复和工具调用中都一样:在任何内容运行之前,它们会被填入真实值。不要要求验证它们,也不要用示例替换它们。

Liam 收到了全部三个办公室的表格,并被要求说出自己在哪一个。应用程序决定规划器可以查看哪里。规划器决定是否查看以及询问什么:只有当规划器认为再进行一次记忆搜索会有帮助时,才会出现 `memoryRetrieve` 操作。使用 Liam 的令牌通过 history 端点读取 Maya 的 sessionId,返回了空列表。

![Maya 的助手回答命中记忆,给出针对法兰克福的 VPN 回复](https://d2908q01vomqb2.cloudfront.net/f1f836cb4ea6efb2a0b1b99f41ad8b103eff4b59/2026/11/13/ML-21969-2.png)

![Liam 的助手回答零条记忆记录,显示通用的三办公室表格](https://d2908q01vomqb2.cloudfront.net/f1f836cb4ea6efb2a0b1b99f41ad8b103eff4b59/2026/11/13/ML-21969-3.png)

图 3:两个用户提出的同一个问题。Maya 的 trace 显示命中记忆并给出针对法兰克福的回答。Liam 的 trace 显示零条记忆记录和通用表格。

长期抽取是异步的,在轮次持久化之后运行。在我们的运行中,第一条记录在第 2 轮之后 81 秒出现,但这一时序并非承诺。请按最终可用性来设计。本次对话中陈述的事实并不保证在下一次对话中可立即检索到。示例在运行第 3 轮之前轮询 ListMemoryRecords。

## 安全与多用户隔离

在本演练中,由应用程序进行身份验证。知识库负责过滤。ACL 感知的检索是过滤,而不是授权。只从带有 email_verified: true 的已验证 ID 令牌中获取电子邮件,使其在池中不可变,并处理电子邮件重用:如果某个地址被重新分配给另一个人,该人将获得旧所有者的文档访问权限。知识库采用故障关闭:没有 ACL 的文档,或 ACL 错误,意味着结果更少,而不是更多。如果结果缺失,请检查电子邮件是否与 ACL 条目匹配。

记忆的身份也来自令牌(步骤 4):actorId 和 namespace 来自已验证的 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 还能看到每次调用是为哪个用户发起的:调用方为 assumed-role/anycompany-assistant-app-role/user-<sub>,且 SourceIdentity=<sub>,会话持有者无法更改。

还有两点。记忆是客户拥有的资源,你账户中的其他系统也可能写入。将其内容视为输入,并通过 policyConfiguration 将 Amazon Bedrock guardrail 附加到请求。并规划数据生命周期。原始事件按 eventExpiryDuration 过期,但抽取的记录不会。因此,用户删除工作流需要涵盖针对该 actor 会话的 DeleteEvent,以及该 actor 命名空间下的 DeleteMemoryRecord。

可观测性与失败行为

像 {{NAME_ab12cd34}} 这样写入的值是真实值的占位符。请在回复和工具调用中完全按原样使用它们:它们会在任何内容运行之前被填入真实值。不要要求验证它们,也不要用示例替换它们。

用关联 ID 记录每一轮的完整 trace。planner 生成的子查询和它的最终结果一样值得审计。AWS/Bedrock/KnowledgeBases 会为 Operation=AgenticRetrieveStream 报告 Invocations、ClientErrors 和 TotalIterationCount。AWS/Bedrock-AgentCore 会为每个 memory 操作报告 Invocations、Latency、Errors 和 UserErrors,并为提取的每种 strategy 报告 InputTokenUsage/OutputTokenUsage。启用 Amazon CloudWatch Transaction Search 后,Amazon Bedrock AgentCore 的能力 AgentCore Observability 会展示一轮对话中端到端的 span。

Memory 操作按设计是尽力而为的。如果 memory 调用失败或被拒绝,请求不会失败。trace 会带上一个 FAILED memory 事件及其失败消息,这一轮在没有该 memory 的情况下继续。答案从 knowledge base 生成。是否要在 UI 中呈现这种降级状态,由你决定。

注意事项

  • 在对话全程使用稳定的 sessionId。API 接受每个请求使用新 ID,但新 ID 会静默地打断连续性,并且每轮产生一条 summary 记录。
  • 使用 namespacePath 访问某个用户的全部长期记录。retrievalConfigs 接受一个条目,最多带五个 metadataFilters。namespace 按前缀匹配,namespacePath 按层级匹配,因此 namespacePath 适合把按用户划分的 ID 放在根之下。提供的 namespace 必须完全解析,像 /anycompany/{actorId} 这样的模板会被拒绝。
  • 预期只会恢复 USER 和 ASSISTANT 的对话事件。其他系统写入的 TOOL 或 OTHER 角色的事件会被跳过。
  • 当应用需要精确控制每个请求携带哪些历史时,继续发送 messages,而不是使用 sessionBinding。例如,你现有的历史存储可能是对话的 system of record,或者你会在发送前编辑或脱敏历史。使用 sessionBinding 时,服务会替你恢复并持久化对话。不能在一个请求中同时使用两者。
  • 一个请求最多可携带五个 knowledge base。当有多个 retriever 时,planner 会依据 knowledge base 的 description 为每个子查询选择路由,所以要仔细撰写它。
  • 为延迟和成本做好规划。session 恢复会增加约 200 毫秒。在我们的运行中,使用托管模型、一个 knowledge base、ACL 和 memory 的完整一轮耗时 4–10 秒。决定这一耗时的是规划迭代,而不是 memory。这些是观测值,不是服务承诺。agentic retrieval 按调用次数加上底层检索计费,调用期间执行的 memory 操作按 AgentCore memory 用量计费。详情请参阅 Amazon Bedrock pricing 和 Amazon Bedrock AgentCore pricing。

清理

在示例中运行 python infra/teardown.py,以删除 knowledge base、S3 桶及其对象、memory 资源(包括对话历史和长期记录)、Cognito 用户池以及 IAM 角色。

结论

Amazon Bedrock Managed Knowledge Base 已经把检索栈作为一项服务提供给你。该栈涵盖摄取、文档 ACL、索引、排序,以及 AgenticRetrieveStream 中把难题变成带引用的答案的规划循环。借助 memoryConfiguration,同一个调用现在会携带对话和用户历史。对于多用户应用,这省去了对话存储、历史回放和提取流水线。剩下的责任只有短短几条。对用户进行身份验证,并从 ID token 中读取两个 claim:把已验证的 email 作为 userContext 传入,以便 knowledge base 过滤文档;把 sub 用作 actorId,对应一个带有以 {actorId} 为根的 namespace 的 memory 资源。在按用户划分的 role session 上使用 IAM 条件键,作为第二道防线,它在整个 agentic 路径中始终有效。

要开始使用,请从 GitHub 仓库部署示例。然后阅读 AgenticRetrieveStream API 参考、Access Control Lists 感知启用,以及 Use AgentCore memory with agentic retrieval。关于检索循环本身,请参阅 Agentic retrieval for Amazon Bedrock Managed Knowledge Base。关于记忆概念,请参阅 Amazon Bedrock AgentCore memory: Building context-aware agents。

关于作者

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by AWS Machine Learning
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗