Vertex AI Agent Engine SDK 快速入門

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

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

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

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

事前準備

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

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

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

  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：您的區域。請參閱支援記憶體庫的區域。

    • 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.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. 刪除所有在本機建立的檔案。

後續步驟