Agent Platform Memory Bank API 快速入門導覽課程

透過 Agent Platform Memory Bank，您可以使用 Agent Platform SDK，直接對工作階段和 Memory Bank 進行 API 呼叫。如果您不希望代理程式架構為您協調呼叫，或是想將 Sessions 和 Memory Bank 與 Agent Development Kit (ADK) 以外的代理程式架構整合，請使用 Agent Platform SDK。

本文說明如何使用 API 呼叫建立、上傳、擷取及移除回憶集錦。

如要瞭解如何使用 ADK 快速入門，請參閱「使用 ADK 快速入門記憶體庫」。

事前準備

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

使用 Agent Platform 工作階段生成回憶集錦

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

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

    import vertexai

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

# This assumes that you already have an Agent Platform 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：您的區域。如需支援 Memory Bank 的區域，請參閱這篇文章。

    • AGENT_ENGINE_NAME：您建立的 Agent Platform 執行個體名稱，或現有的 Agent Platform 執行個體。名稱應採用以下格式：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 Sessions. Defaults to {"user_id": session.user_id}.
scope=SCOPE
)

更改下列內容：

  • (選用) SCOPE：代表生成回憶範圍的字典，最多 5 個鍵值組，且不含 * 字元。例如：{"session_id": "MY_SESSION"}。只有範圍相同的記憶體才會合併。如未提供，系統會使用 {"user_id": session.user_id}。

上傳回憶

除了使用原始對話生成記憶內容，您也可以上傳記憶內容，或讓代理程式使用 GenerateMemories 直接新增記憶內容，並預先擷取事實。您可直接提供應儲存的使用者相關事實，而非讓 Memory Bank 從內容中擷取資訊。

為確保與生成的記憶內容一致，請嘗試以為指定範圍設定的相同角度，撰寫預先擷取的資訊。根據預設，記憶內容會以第一人稱角度生成 (例如 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 Bank 進行回憶內容擷取或整合。

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}。您可以擷取記憶體來找出記憶體名稱。

依條件移除

您可以根據條件刪除一或多個回憶集錦。系統只會刪除符合所提供篩選條件的回憶集錦。您必須指定至少一個 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
)

依語意移除

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

或者，您也可以按照下列步驟，刪除在本教學課程中建立的個別資源：

  1. 使用下列程式碼範例刪除 Agent Platform 執行個體，這也會一併刪除與該執行個體相關聯的所有工作階段或記憶體。

    agent_engine.delete(force=True)

  2. 刪除所有在本機建立的檔案。

後續步驟

快速入門

開始使用 Agent Development Kit (ADK)。