Vertex AI Agent Engine SDK 快速入門

本教學課程示範如何使用 Vertex AI Agent Engine SDK，直接對 Vertex AI Agent Engine Sessions 和 Memory Bank 發出 API 呼叫。如果您不希望代理程式架構為您協調呼叫，或是想將 Sessions 和 Memory Bank 與 Agent Development Kit (ADK) 以外的代理程式架構整合，請使用 Vertex AI Agent Engine SDK。

如需使用 ADK 的快速入門導覽課程，請參閱「Agent Development Kit 快速入門導覽課程」。

本教學課程會使用下列步驟：

  1. 使用下列選項建立回憶集錦：
  2. 擷取記憶體。
  3. 清除所用資源。

事前準備

如要完成本教學課程中示範的步驟，請先按照「設定 Memory Bank」中的步驟操作。

使用 Vertex AI Agent Engine 工作階段生成記憶體

設定 Vertex AI Agent Engine 工作階段和記憶體後，即可建立工作階段並附加事件。記憶內容是根據使用者與代理程式的對話生成的事實，可供日後的使用者互動使用。詳情請參閱「產生回憶集錦」和「擷取回憶集錦」。

  1. 使用不透明的使用者 ID 建立工作階段。除非您在生成記憶體時明確提供範圍，否則系統會自動以範圍 {"user_id": "USER_ID"} 為這個工作階段生成的任何記憶體加上索引鍵。

    import vertexai

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION"
)
# For Express Mode users, initialize the Vertex AI Client as follows:
# client = vertexai.Client(
#   api_key="API_KEY",
# )

# 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：使用者的 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=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>
"""

刪除回憶集錦

您可以使用資源名稱刪除特定記憶體：

client.agent_engines.memories.delete(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. 刪除所有在本機建立的檔案。

後續步驟