Agent Platform Memory Bank API 快速入门

您可以使用 Agent Platform SDK 直接对记忆库进行 API 调用。如果您不希望智能体框架为您编排调用，或者您想将记忆库与智能体开发套件 (ADK) 以外的智能体框架集成，请使用 Agent Platform SDK。

本文档介绍了如何使用 API 调用创建、上传、检索和移除记忆。

如需查看使用 ADK 的快速入门，请参阅记忆库快速入门（使用 ADK）。

准备工作

如需完成本教程中演示的步骤，您必须先按照设置记忆库中的步骤操作。在开始本快速入门之前，请确保您已创建 Memory Bank 实例和 Sessions 实例，如以下示例所示：

import vertexai

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION"
)

memory_bank = client.agent_engines.create()
sessions = client.agent_engines.create()

使用 Agent Platform Sessions 生成回忆

设置代理平台会话后，您可以创建会话并向其中追加事件。然后，您可以使用记忆库根据用户与智能体的对话生成记忆，以便在未来的用户互动中使用这些记忆。如需了解详情，请参阅生成记忆和提取记忆。

1. 创建具有不透明用户 ID 的会话。除非您在生成回忆时明确提供范围，否则根据此会话生成的所有回忆都会自动以范围 {"user_id": "USER_ID"} 为键。

   import vertexai
   
   client = vertexai.Client(
     project="PROJECT_ID",
     location="LOCATION"
   )
   
   session = client.agent_engines.sessions.create(
     # The name can be fetched using `sessions.api_resource.name`.
     name="SESSIONS_NAME",
     user_id="USER_ID"
   )
   

   替换以下内容：

   • PROJECT_ID：您的项目 ID。

   • LOCATION：您的区域。 请参阅记忆库的支持的区域。

   • SESSIONS_NAME：您创建的 Sessions 实例的名称或现有 Sessions 实例的名称。该名称应采用以下格式：projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}。

   • USER_ID：您的用户的标识符。除非您在生成记忆时明确提供范围，否则从相应会话中生成的所有记忆都会自动以范围 {"user_id": "USER_ID"} 为键。

2. 以迭代方式将事件上传至会话。事件可以包括用户、代理和工具之间的任何互动。有序的事件列表表示会话的对话历史记录。此对话历史记录会用作为相应用户生成记忆的源材料。

   import datetime
   
   client.agent_engines.sessions.events.append(
     name=session.response.name,
     author="user",  # Required by Sessions.
     invocation_id="1",  # Required by Sessions.
     timestamp=datetime.datetime.now(tz=datetime.timezone.utc),  # Required by Sessions.
     config={
       "content": {
         "role": "user",
         "parts": [{"text": "hello"}]
       }
     }
   )
   

3. 如需根据对话记录生成记忆，请为相应会话触发记忆生成请求：

   client.agent_engines.memories.generate(
     name=memory_bank.api_resource.name,
     vertex_session_source={
       # `session` should have the format "projects/.../locations/.../reasoningEngines/.../sessions/...".
       "session": session.response.name
     },
     # Optional when using Sessions. Defaults to {"user_id": session.user_id}.
     scope=SCOPE
   )
   

替换以下内容：

• （可选）SCOPE：一个字典，用于表示生成的记忆的范围，最多包含 5 个键值对，且不包含 * 字符。例如 {"session_id": "MY_SESSION"}。只有范围相同的记忆才会考虑进行整合。如果未提供，则使用 {"user_id": session.user_id}。

上传记忆

除了使用原始对话生成记忆之外，您还可以上传记忆，或者让代理使用 GenerateMemories 直接添加记忆，并预先提取事实。您无需让记忆库从您的内容中提取信息，而是直接提供应存储的有关用户的事实。

为确保与生成的记忆保持一致，请尝试以您为给定范围配置的相同视角来撰写预提取的事实。默认情况下，记忆是以第一人称视角生成的（例如 I am a software engineer）。

client.agent_engines.memories.generate(
    name=memory_bank.api_resource.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

替换以下内容：

• FACT：应与现有记忆整合的预提取事实。您最多可以在列表中提供 5 个预提取的事实，如下所示：

  {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}
  

• SCOPE：一个字典，用于表示生成的记忆的范围。例如 {"session_id": "MY_SESSION"}。只有范围相同的记忆才会考虑进行整合。

或者，您也可以使用 CreateMemory 上传记忆，而无需使用记忆库进行记忆提取或整合。

memory = client.agent_engines.memories.create(
    name=memory_bank.api_resource.name,
    fact="This is a fact.",
    scope={"user_id": "123"}
)

"""
Returns an AgentEngineMemoryOperation containing the created Memory like:

AgentEngineMemoryOperation(
  done=True,
  metadata={
    "@type': 'type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateMemoryOperationMetadata",
    "genericMetadata": {
      "createTime": '2025-06-26T01:15:29.027360Z',
      "updateTime": '2025-06-26T01:15:29.027360Z'
    }
  },
  name="projects/.../locations/us-central1/reasoningEngines/.../memories/.../operations/...",
  response=Memory(
    create_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC)),
    fact="This is a fact.",
    name="projects/.../locations/us-central1/reasoningEngines/.../memories/...",
    scope={
      "user_id": "123"
    },
    update_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC))
  )
)
"""

检索和使用记忆

您可以检索用户的记忆，并将其纳入到系统指令中，以便 LLM 访问您的个性化上下文。

如需详细了解如何使用基于范围的方法检索记忆，请参阅提取记忆。

# Retrieve all memories for User ID 123.
retrieved_memories = list(
    client.agent_engines.memories.retrieve(
        name=memory_bank.api_resource.name,
        scope={"user_id": "123"}
    )
)

您可以使用 jinja 将结构化的记忆转换为提示：

from jinja2 import Template

template = Template("""
<MEMORIES>
Here is some information about the user:
{% for retrieved_memory in data %}* {{ retrieved_memory.memory.fact }}
{% endfor %}</MEMORIES>
""")

prompt = template.render(data=retrieved_memories)

"""
Output:

<MEMORIES>
Here is some information about the user:
* This is a fact
</MEMORIES>
"""

移除回忆

您可以采用多种方式从 Memory Bank 实例中删除回忆，具体取决于您希望如何选择要移除的回忆。

按资源名称移除

如果您确切地知道要移除哪个内存资源，可以使用其资源名称删除特定内存：

client.agent_engines.memories.delete(
    name=MEMORY_NAME,
    config={
        # Set to false (default) if you want to delete the memory asynchronously.
        "wait_for_completion": True
    }
)

替换以下内容：

• MEMORY_NAME：要删除的记忆的名称。该名称应采用以下格式：projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}。您可以通过提取记忆来查找记忆名称。

按条件移除

您可以使用基于条件的删除功能来移除一个或多个记忆。系统只会删除与所提供的过滤条件相符的回忆。您必须至少指定 filter（应用于系统字段）或 filter_groups（应用于元数据字段）中的一个。

operation = client.agent_engines.memories.purge(
    name=memory_bank.api_resource.name,
    # Specify at least one of `filter` or `filter_groups`.
    filter="FILTER_STRING",
    filter_groups=FILTER_GROUPS,
    # Set to false (default) if you want to stage but not execute the purge operation.
    force=True,
    config={
        # Set to false (default) if you want to purge memories asynchronously.
        "wait_for_completion": True
    }
)

替换以下内容：

• FILTER_STRING：一个字符串，使用 EBNF 语法针对系统字段进行过滤。系统字段包括 create_time、update_time、fact 和 topics。如需详细了解如何根据系统字段进行过滤，请参阅“提取回忆”页面上的按元数据字段过滤部分。
• FILTER_GROUPS：用于过滤内存元数据的一系列字典或对象。如需详细了解如何根据元数据字段进行过滤，请参阅“提取回忆”页面上的按系统字段过滤部分。

该操作将返回已清除的内存数量（如果为 force=True）或如果执行该操作将清除的内存数量（如果为 force=False）。

print(operation.response.purge_count)

例如，您可以清除属于 user_id“123”范围的所有记忆：

operation = client.agent_engines.memories.purge(
    name=memory_bank.api_resource.name,
    filter="scope.user_id=\"123\""
    force=True
)

按语义含义移除

在记忆生成期间，记忆库会根据新提取的信息的内容和现有记忆来决定是创建、更新还是删除记忆。如果新信息与某条记忆相矛盾，或者提取的内容指示记忆库忘记某个主题（在 EXPLICIT_INSTRUCTIONS 记忆主题的情况下），则该记忆可能会被删除。

例如，以下请求会删除包含饮食偏好相关信息的现有回忆（如果指定 scope 存在此类回忆）：

from google import genai

client.agent_engines.memories.generate(
    name=memory_bank.api_resource.name,
    direct_contents_source={
      "events": [{
        "content": genai.types.Content(
          role="user",
          parts=[
            genai.types.Part.from_text(text="Forget my dietary preferences.")
          ]
        )
      }]
    },
    scope={...}
)

清理

如需清理此项目中使用的所有资源，您可以删除用于本快速入门的 Google Cloud项目。

否则，您可以按如下所示逐个删除在本教程中创建的资源：

1. 使用以下代码示例删除 Agent Platform 实例，这也会删除与该 Agent Platform 实例关联的所有会话或记忆。

   agent_engine.delete(force=True)
   

2. 删除所有本地创建的文件。

后续步骤