Vertex AI Agent Engine SDK 快速入门

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

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

本教程使用以下步骤：

  1. 使用以下选项创建回忆：
  2. 检索记忆。
  3. 清理.

准备工作

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

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

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

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

    import vertexai

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

session = client.agent_engines.create_session(
  name=AGENT_ENGINE_NAME,
  user_id="USER_ID"
)

    替换以下内容：

    • PROJECT_ID：您的项目 ID。

    • LOCATION：您的区域。 如需了解 Memory Bank 支持的区域，请参阅支持的区域。

    • 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"} 为键。

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

    import datetime

client.agent_engines.append_session_event(
  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.generate_memories(
  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.generate_memories(
    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.create_memory(
    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.retrieve_memories(
        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.delete_memory(name=MEMORY_NAME)

替换以下内容：

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

清理

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

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

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

    agent_engine.delete(force=True)

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

后续步骤