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 快速入門導覽課程」。

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

使用下列選項建立回憶集：
- 使用 Vertex AI Agent Engine Memory Bank 生成記憶內容：將工作階段和事件寫入 Vertex AI Agent Engine Sessions，做為 Vertex AI Agent Engine Memory Bank 生成記憶內容的來源。
- 直接上傳記憶內容：如要完全掌控保留的資訊，可以自行撰寫記憶內容，或請代理程式建立記憶內容。
擷取記憶體。
清除所用資源。

事前準備

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

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

移除回憶集錦

你可以透過多種方式從記憶體庫執行個體刪除回憶集錦，視要選取哪些回憶集錦而定。

依資源名稱移除

如果您確切知道要移除哪個記憶體資源，可以使用資源名稱刪除特定記憶體：

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}。您可以擷取回憶集錦，找出回憶集錦名稱。

依條件移除

你可以根據條件刪除一或多個回憶集錦。系統只會刪除符合篩選條件的回憶集錦。您必須指定至少一項 filter (套用至系統欄位) 或 filter_groups (套用至中繼資料欄位)。

operation = client.agent_engines.memories.purge(
    name=agent_engine.api_resource.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.agent_engines.memories.purge(
    name=agent_engine.api_resource.name,
    filter="scope.user_id=\"123\""
    force=True
)

依語意移除

生成記憶內容時，記憶庫會根據新擷取的資訊內容和現有記憶內容，決定是否要建立、更新或刪除記憶內容。如果新資訊與記憶內容相衝突，或是擷取的內容指示記憶庫忘記某個主題 (適用於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)
```
刪除所有在本機建立的檔案。

後續步驟

Agent Development Kit 快速入門導覽課程。

Vertex AI Agent Engine SDK 快速入門 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

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

上傳回憶

擷取及使用回憶集錦

移除回憶集錦

依資源名稱移除

依條件移除

依語意移除

清除所用資源

後續步驟

Vertex AI Agent Engine SDK 快速入門