Agent Platform Memory Bank API 快速入门

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

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

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

如需查看将 与 SDK 搭配使用的示例，请在以下任一环境中运行“开始使用 Memory Bank”笔记本：

在 Colab 中打开 | 在 Colab Enterprise 中打开 | 在 Agent Platform Workbench 中打开 | 在 GitHub 上查看

如需查看将 与 LangGraph 搭配使用的示例，请在以下任一环境中运行“ - LangGraph 使用入门”笔记本：

在 Colab 中打开 | 在 Colab Enterprise 中打开 | 在 Agent Platform Workbench 中打开 | 在 GitHub 上查看

准备工作

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

import agentplatform

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

memory_bank = client.memory_banks.create()
sessions = client.runtimes.create()

使用 Agent Platform Sessions 生成记忆

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

注意：您还可以使用直接内容来源在 GenerateMemories 载荷中直接提供对话记录。

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

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

   替换以下内容：

   • PROJECT_ID：您的项目 ID。

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

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

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

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

   import datetime
   
   client.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.memory_banks.memories.generate(
     name=memory_bank.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.memory_banks.memories.generate(
    name=memory_bank.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 上传记忆，而无需使用记忆库进行记忆提取或整合。

注意：使用 CreateMemory 上传的记忆不会与现有记忆整合，因此同一范围内的记忆可能会重复。创建的记忆可用于相似度搜索，并可在生成记忆时进行合并，以供未来请求使用。

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

"""
Returns a MemoryOperation containing the created Memory like:

MemoryOperation(
  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))
  )
)
"""

检索和使用记忆

你可以检索用户的记忆，并将其纳入到系统指令中，以便大语言模型能够访问你的个人使用场景。

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

# Retrieve memories for User ID 123.
retrieved_memories = client.memory_banks.memories.retrieve(
    name=memory_bank.name,
    scope={"user_id": "123"}
).page

您可以使用 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.memory_banks.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.memory_banks.memories.purge(
    name=memory_bank.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.memory_banks.memories.purge(
    name=memory_bank.name,
    filter="scope.user_id=\"123\"",
    force=True
)

按语义移除

注意：预期行为可能会因您配置的记忆主题和少样本示例而异。

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

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

from google import genai

client.memory_banks.memories.generate(
    name=memory_bank.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. 使用以下代码示例删除 Gemini Enterprise Agent Platform 实例上的 Agent Platform 记忆库和 Agent Runtime：

   client.memory_banks.delete(name=memory_bank.name, force=True)
   client.runtimes.delete(name=sessions.name, force=True)
   

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

后续步骤

快速入门

智能体开发套件快速入门

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