Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Agent Platform Memory Bank API 快速入门

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

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

如需了解使用 ADK 的快速入门，请参阅使用 ADK的记忆库快速入门。

准备工作

如需完成本教程中演示的步骤，您必须先按照设置记忆库中的步骤操作。

使用 Agent Platform 会话生成记忆

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

使用不透明的用户 ID 创建会话。除非您在生成记忆时明确提供范围，否则从该会话生成的任何记忆都会自动按范围 {"user_id": "USER_ID"} 进行键控。
```
import vertexai

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

# This assumes that you already have an Agent Platform instance. If you don't,
# you can create one using `agent_engine = client.agent_engines.create()`.
session = client.agent_engines.sessions.create(
# The name can be fetched using `agent_engine.api_resource.name`.
name="AGENT_ENGINE_NAME",
user_id="USER_ID"
)
```
替换以下内容：
- PROJECT_ID：您的项目 ID。
- LOCATION：您的区域。请参阅记忆库支持的区域。
- AGENT_ENGINE_NAME：您创建的 Agent Platform 实例的名称或现有 Agent Platform 实例的名称。名称应采用以下格式：projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}。
- USER_ID：您的用户的标识符。除非您在生成记忆时明确提供范围，否则从该会话生成的任何记忆都会自动按范围 {"user_id": "USER_ID"} 进行键控。

以迭代方式将事件上传到会话。事件可以包括用户、智能体和工具之间的任何互动。事件的有序列表表示会话的对话历史记录。此对话历史记录用作生成特定用户的记忆的源材料。

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"}]
  }
}
)

如需根据对话历史记录生成记忆，请为会话触发记忆生成请求：

client.agent_engines.memories.generate(
name=agent_engine.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=agent_engine.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=agent_engine.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=agent_engine.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>
"""

移除记忆

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

按资源名称移除

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

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=agent_engine.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_timefact 和 topics。如需详细了解如何针对系统字段进行过滤，请参阅提取记忆页面上的Filter by metadata fields 部分。
FILTER_GROUPS：用于针对记忆元数据进行过滤的字典或对象列表。如需详细了解如何针对元数据字段进行过滤，请参阅提取记忆页面上的按系统字段过滤部分。

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

print(operation.response.purge_count)

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

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

按语义移除

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

例如，如果给定 scope 存在包含饮食偏好信息的现有记忆，则以下请求会删除这些记忆：

from google import genai

client.agent_engines.memories.generate(
    name=agent_engine.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 用于本快速入门的项目。

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

使用以下代码示例删除 Agent Platform 实例，该操作还会删除与 Agent Platform 实例关联的任何会话或记忆。
```
agent_engine.delete(force=True)
```
删除所有本地创建的文件。

后续步骤

快速入门

智能体开发套件快速入门

开始使用智能体开发套件 (ADK)。

Agent Platform Memory Bank API 快速入门 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

使用 Agent Platform 会话生成记忆

上传记忆

检索和使用记忆

移除记忆

按资源名称移除

按条件移除

按语义移除

清理

后续步骤

智能体开发套件快速入门

Agent Platform Memory Bank API 快速入门