人工智能

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

知识增强型应用的用户期望它能记住自己,而不仅仅是搜索得好。他们会提出只有在上一轮对话语境下才说得通的追问。他们期望关于某项政策或流程的回答能反映出自己上个月告诉过应用的信息。而且他们仍然期望每个回答都基于他们有权阅读的文档,并附有引用。无论该应用是客户支持助手、SaaS 产品内的文档聊天,还是基于公司政策的内部助手,期望都是一样的。

满足这一期望并不容易,因为能让搜索更精准的上下文存在于知识库之外。用户的位置、角色或产品层级往往是在几周前一次不相关的对话中提到的。要利用这些信息,应用必须存储每一次对话,从中提取持久事实,判断哪些事实与当前问题相关,并将它们注入请求。当许多用户共用该应用时,上述每一步还必须按用户隔离,每一份文档也是如此。

Amazon Bedrock Managed Knowledge Base 和 Amazon Bedrock AgentCore memory(Amazon Bedrock AgentCore 的一项能力)现在接管了这些步骤:存储每一次对话、从中提取事实,并将相关事实带入搜索。你只需在请求中添加一个 memoryConfiguration 请求,即可让 AgentCore memory 与你的知识库一起作为检索源。 AgenticRetrieveStream 请求,使 AgentCore memory 与你的知识库一起作为检索源。在同一次调用中,服务会恢复对话,规划器会自行判断何时需要关于用户的事实。它从长期记忆中检索该事实,并用它来组合发送给知识库的子查询。生成答案后,服务会将该轮对话保存回记忆。同一请求还携带一个 userContext,因此知识库只返回用户访问控制列表(ACL)允许的文档。该集成是可选的,并且向后兼容。你的应用只保留真正属于自己的部分:对用户进行身份验证,并传递用户的身份。

本文展示如何为共享同一个知识库和同一个记忆资源的众多用户构建这样一个助手。每个用户只能看到自己有权阅读的文档,并且每个用户的记忆保持私密。贯穿全文的示例是 AnyCompany(一家虚构公司)的内部员工助手。员工使用 Amazon Cognito 登录,并就人力资源政策、IT 指南、工程运行手册和销售计划提出问题。我们展示如何从 Cognito ID 令牌中读取用户身份,如何将其传递给 AgenticRetrieveStream 用于文档 ACL 和记忆,如何为众多用户设计记忆命名空间,以及如何读取跟踪记录以查看规划器何时使用了记忆。最后,我们让 AWS Identity and Access Management(IAM)强制执行按用户隔离记忆,即使应用程序代码出错也能保证隔离。如果你从 在 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 仓库.

Architecture of the memory-aware employee assistant: application, AgenticRetrieveStream, Managed Knowledge Base, and AgentCore memory

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

  1. 员工通过 Cognito 登录,并获得一个 ID 令牌,即由用户池签名的 JSON Web Token(JWT)。
  2. 应用程序的 API 会验证该令牌——生产环境中是 Amazon API Gateway JWT 授权方,示例中是一个小型 FastAPI 服务。未经身份验证的请求不会到达处理程序。
  3. 处理程序从已验证的令牌中读取两个声明: sub 成为记忆 actorId 和命名空间,以及 email 成为 userContext.userId客户端请求体仅携带 { question, sessionId? }。随后,处理程序会为该用户代入应用程序的 IAM 角色,并带有会话标签“ userId=<sub>.
  4. 处理程序调用 AgenticRetrieveStream 以知识库作为检索器, userContext,以及一个 memoryConfiguration 绑定到该用户。
  5. 托管知识库会从 AgentCore memory 的短期记忆(STM)中,为以下标识所指定的 actor 和会话恢复对话历史: sessionBinding.
  6. 托管知识库会基于以下条件从知识库中检索,并进行 ACL 过滤: userContext它还可以通过推测性检索或由规划器选择的记忆搜索来获取用户配置的长期记忆。
  7. 托管知识库会流式返回带引用的答案,并将跟踪事件回传给处理程序。处理程序使用关联 ID 记录这些跟踪信息,并将答案和跟踪信息转发到 UI。
  8. 借助 persistenceMode: DEFAULT,服务会将问题和生成的答案保存到会话中。随后,AgentCore memory 会根据配置的策略异步提取长期记录。

A sequence diagram that traces a question from Your Application, through the AgenticRetrieveSystem, Managed knowledge base, and AgentCoreMemory returning responseEvent chunks.

图 2:一次 AgenticRetrieveStream 轮次,带有“ userContext 以及 memoryConfiguration.第一个箭头与最后一个箭头之间的所有内容都是该服务的工作。

托管知识库负责数据摄取、ACL 过滤、索引、排序、规划、检索和生成。借助 memoryConfiguration它还负责会话恢复、记忆搜索和持久化。AgentCore memory 负责存储、保留、加密和提取。你的应用程序负责身份验证、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/<sub> 规划器可以搜索哪些长期记录 IAM 条件

两种不同的声明承担两种不同的职责。知识库通过电子邮件标识用户,因为这是所连接的数据源在其 ACL 中记录的内容。记忆则需要一个 actorId 永不改变且永不复用的标识符。Cognito sub 两者兼而有之。电子邮件地址可以更改,也可以在某人离职后重新分配给新员工,而那个人随后就会继承旧的记忆。你可以使用自己用户存储中的另一个稳定用户 ID 作为 actorId重要的是,它永远不会转移到其他人身上。

前提条件

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

解决方案演练

以下步骤将创建知识库及其数据源、设置记忆资源和 Amazon Cognito、构建请求,并读取跟踪信息以确认结果。

步骤 1:创建带有启用 ACL 数据源的知识库

托管知识库无需向量存储:

按照以下步骤为你的设置配置服务角色: 为托管式 Amazon Bedrock Knowledge Base 创建服务角色,并在其中传入其 ARN, roleArn有关模型访问要求,另请参阅 托管模型和自定义模型的前提条件.

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。完整列表请参见 访问控制列表(ACL)感知功能的启用.

步骤 2:创建记忆资源并设计命名空间

一个记忆资源服务于所有用户。按用户隔离则来自 {actorId} 在命名空间模板中,AgentCore memory 会在提取时从每个事件中解析出该命名空间。有两个选择很重要。

策略这两种策略提取的内容不同。摘要策略会为每段对话生成摘要,因此能捕捉用户在随口提及中提到的事实,例如“我在法兰克福办公室用的是 Mac”。正是这些事实让之后关于(比如)带薪休假的回答实现个性化。用户偏好策略则把明确表达的偏好提取为结构化记录(“偏好不带表格的简短要点式回答”“总是先部署到 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 用户第一次提问时才会成为新的参与者。

步骤 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,以及 CreateEvent 当 persistenceMode 是 DEFAULT. ListSessions 以及 ListMemoryRecords 用于应用程序自身的读取(对话列表和“记忆了解你什么”视图),而不是用于 AgenticRetrieveStream该角色的信任策略允许 sts:AssumeRole, sts:TagSession,以及 sts:SetSourceIdentity 来自后端自身的身份(生产环境中为 AWS Lambda 执行角色或 Amazon Elastic Container Service(Amazon ECS)任务角色)。如果记忆使用客户托管密钥,请添加 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。对于新对话,应用程序会生成一个会话 ID,例如 "conv-" + uuid4().hex,并将其返回给客户端。要继续对话,客户端会将其发回。要查看用户的对话,请调用 ListSessions 用户 actorId:

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 memory 客户端使用。

第 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 美元或 450 欧元”。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,稍后的一个新对话。 “我每年有多少天带薪休假(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 对话的摘要。这就足够了:规划器直接得出了答案,答案中写道:“由于你的记忆表明你常驻法兰克福办公室……你每年享有 30 天带薪休假(PTO),于 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 动作仅在规划器判断再进行一次记忆搜索会有帮助时才会出现。读取 Maya 的 sessionId 通过历史端点并使用 Liam 的令牌,返回了一个空列表。

Maya’s assistant answer with a memory hit, giving a Frankfurt-specific VPN response Liam’s assistant answer with zero memory records, showing the generic three-office table

图 3:两个用户提出的同一个问题。Maya 的追踪记录显示了一次记忆命中以及一个针对法兰克福的答案。Liam 的追踪记录显示零条记忆记录以及通用表格。

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

安全性与多用户隔离

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

身份来自令牌 (第 4 步)对记忆也同样适用: actorId 和命名空间来自经过验证的 sub,绝不来自客户端。

作为纵深防御的 IAM 条件键。 AgentCore memory 暴露 bedrock-agentcore:actorId ,以及 ListEvents, CreateEvent,以及 ListSessions,以及 bedrock-agentcore:namespacePath 在 RetrieveMemoryRecords 以及 ListMemoryRecords代理式检索在请求期间进行的内存调用,会针对调用方身份进行授权。这就是为什么调用方的策略必须授予这些操作权限,以及为什么第 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>,而会话持有者无法更改这一点。

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

可观测性与故障行为

为每一轮记录带有相关性 ID 的完整追踪。规划器的子查询与其最终结果同样值得审计。 AWS/Bedrock/KnowledgeBases 报告 Invocations, ClientErrors,以及 TotalIterationCount ,用于 Operation=AgenticRetrieveStream. AWS/Bedrock-AgentCore 报告 Invocations, Latency, Errors,以及 UserErrors 每次内存操作,以及 InputTokenUsage/OutputTokenUsage 按策略进行提取。启用 Amazon CloudWatch Transaction Search 后,Amazon Bedrock AgentCore 的一项能力 AgentCore Observability 会端到端地展示一轮对话的各个 span。

内存操作在设计上就是尽力而为的。如果内存调用失败或被拒绝,请求不会失败。追踪记录会携带一条 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}-rooted 命名空间。在每用户角色会话上使用 IAM 条件键作为第二道防线,该防线在 agentic 路径中依然有效。

首先,从该 GitHub 仓库部署示例。 GitHub 仓库然后阅读 AgenticRetrieveStream API 参考, 访问控制列表(ACL)感知能力的启用,并且 将 AgentCore memory 与 agentic 检索配合使用。关于检索循环本身,请参阅 Amazon Bedrock Managed Knowledge Base 的 Agentic 检索。有关内存概念,请参阅 Amazon Bedrock AgentCore memory:构建上下文感知型智能体.


关于作者