Vertex AI Agent Engine SDK 快速入门

本教程演示了如何使用 Vertex AI Agent Engine SDK 直接对 Vertex AI Agent Engine 会话和记忆库进行 API 调用。如果您不希望智能体框架为您编排调用，或者希望将会话和记忆库与智能体开发套件 (ADK) 以外的智能体框架集成，请使用 Vertex AI Agent Engine SDK。

如需了解使用 ADK 的快速入门，请参阅智能体开发套件快速入门。

本教程使用以下步骤：

使用以下选项创建记忆：
- 使用 Vertex AI Agent Engine 记忆库生成记忆：将对话和事件写入 Vertex AI Agent Engine 会话，作为 Vertex AI Agent Engine 记忆库生成记忆的来源。
- 直接上传记忆：如果您想完全控制持久保存的信息，可以自行撰写记忆，也可以让代理构建记忆。
检索记忆。
清理.

准备工作

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

使用 Vertex AI Agent Engine 会话生成记忆

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

创建具有不透明用户 ID 的会话。除非您在生成记忆时明确提供范围，否则系统会自动将从相应会话中生成的所有记忆的键设置为范围 {"user_id": "USER_ID"}。
```
import vertexai

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

# This assumes that you already have an Agent Engine 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：您创建的 Vertex AI Agent Engine 实例的名称或现有 Vertex AI Agent Engine 实例的名称。该名称应采用以下格式：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 Agent Engine 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>
"""

移除回忆

您可以根据自己希望选择哪些回忆进行移除的方式，通过多种方式从 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}。您可以通过提取记忆来查找记忆名称。

按条件移除

您可以使用基于条件的删除功能来移除一个或多个回忆。系统只会删除与所提供的过滤条件相符的回忆。

operation = client.agent_engines.memories.purge(
    name=agent_engine.api_resource.name,
    filter=FILTER_STRING,
    # 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。如需详细了解如何根据系统字段进行过滤，请参阅此文档。

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

print(operation.response.purge_count)

按语义含义移除

在生成记忆期间，记忆库会根据新提取的信息的内容和现有记忆来决定是创建、更新还是删除记忆。如果新信息与某条记忆相矛盾，或者提取的内容指示记忆库忘记某个主题（在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 项目。

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

使用以下代码示例删除 Vertex AI Agent Engine 实例，这也会删除与该 Vertex AI Agent Engine 实例关联的所有会话或记忆。
```
agent_engine.delete(force=True)
```
删除所有本地创建的文件。

后续步骤

智能体开发套件快速入门。

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

准备工作

使用 Vertex AI Agent Engine 会话生成记忆

上传记忆

检索和使用记忆

移除回忆

按资源名称移除

按条件移除

按语义含义移除

清理

后续步骤

Vertex AI Agent Engine SDK 快速入门