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

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

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

如要參閱使用 ADK 的快速入門導覽課程，請參閱「使用 ADK 的 Memory Bank 快速入門導覽課程」。

如要查看如何搭配 SDK 使用 的範例，請在下列其中一個環境中執行「開始使用 Memory Bank」筆記本：

在 Colab 中開啟 | 在 Colab Enterprise 中開啟 | 在 Agent Platform Workbench 中開啟 | 在 GitHub 中查看

如要查看使用 和 LangGraph 的範例，請在下列其中一個環境中執行「Get started with - LangGraph」筆記本：

在 Colab 中開啟 | 在 Colab Enterprise 中開啟 | 在 Agent Platform Workbench 中開啟 | 在 GitHub 中查看

事前準備

如要完成本教學課程中示範的步驟，請先按照「設定 Memory Bank」中的步驟操作。開始本快速入門導覽課程前，請先確認您已建立 Memory Bank 執行個體和 Sessions 執行個體，如下列範例所示：

import agentplatform

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

memory_bank = client.memory_banks.create()
sessions = client.runtimes.create()

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

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

注意： 你也可以使用直接內容來源，直接在 GenerateMemories 酬載中提供對話記錄。

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

   import agentplatform
   
   client = agentplatform.Client(
     project="PROJECT_ID",
     location="LOCATION"
   )
   
   session = client.sessions.create(
     # The name can be fetched using `sessions.name`.
     name="SESSIONS_NAME",
     user_id="USER_ID"
   )
   

   更改下列內容：

   • PROJECT_ID：專案 ID。

   • LOCATION：您的區域。如要查看 Memory Bank 支援的區域，請參閱這篇文章。

   • SESSIONS_NAME：您建立的 Sessions 執行個體名稱，或現有的 Sessions 執行個體。名稱應採用下列格式：projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}。

   • USER_ID：使用者的 ID。除非您在生成記憶時明確提供範圍，否則系統會自動以範圍 {"user_id": "USER_ID"} 為索引鍵，生成這項工作階段的記憶。

2. 將事件以疊代方式上傳至工作階段。事件可以包含使用者、代理程式和工具之間的任何互動。依序排列的事件清單代表工作階段的對話記錄。系統會使用這些對話記錄做為來源資料，為特定使用者生成記憶內容。

   import datetime
   
   client.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.memory_banks.memories.generate(
     name=memory_bank.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.memory_banks.memories.generate(
    name=memory_bank.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 進行回憶擷取或合併。

注意： 使用 CreateMemory 上傳的回憶集錦不會與現有回憶集錦合併，因此您可能會看到相同範圍的重複回憶集錦。建立的記憶可供相似度搜尋，並在生成記憶時合併，以供日後要求使用。

memory = client.memory_banks.memories.create(
    name=memory_bank.name,
    fact="This is a fact.",
    scope={"user_id": "123"}
)

"""
Returns a MemoryOperation containing the created Memory like:

MemoryOperation(
  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 memories for User ID 123.
retrieved_memories = client.memory_banks.memories.retrieve(
    name=memory_bank.name,
    scope={"user_id": "123"}
).page

您可以使用 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.memory_banks.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.memory_banks.memories.purge(
    name=memory_bank.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.memory_banks.memories.purge(
    name=memory_bank.name,
    filter="scope.user_id=\"123\"",
    force=True
)

依語意移除

注意： 預期行為可能因您設定的記憶體主題和少量樣本而異。

記憶生成時，Memory Bank 會根據新擷取的資訊內容和現有記憶，決定是否要建立、更新或刪除記憶。如果新資訊與記憶內容相抵觸，或是擷取的內容指示記憶庫忘記某個主題 (適用於EXPLICIT_INSTRUCTIONS記憶主題)，系統可能會刪除記憶內容。

舉例來說，如果指定 scope 有包含飲食偏好資訊的現有記憶內容，下列要求會將其刪除：

from google import genai

client.memory_banks.memories.generate(
    name=memory_bank.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. 使用下列程式碼範例，刪除 Gemini Enterprise Agent Platform 執行個體上的 Agent Platform Memory Bank 和 Agent Runtime：

   client.memory_banks.delete(name=memory_bank.name, force=True)
   client.runtimes.delete(name=sessions.name, force=True)
   

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

後續步驟

快速入門導覽課程

Agent Development Kit 快速入門

開始使用 Agent Development Kit (ADK)。