Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

設定 Agent Platform Memory Bank

如要使用 Agent Platform Memory Bank，請先建立及設定 Gemini Enterprise Agent Platform 執行個體。這個執行個體會管理記憶內容，並可與各種執行階段的代理程式整合。

本文說明如何設定 Google Cloud 專案、安裝必要程式庫，以及建立或更新執行個體，並使用主題和 TTL 等自訂設定。

開始使用

使用 Memory Bank 前，請務必先設定環境。

設定 Google Cloud 專案

每項專案都有專案編號或專案 ID 這兩項識別資訊。PROJECT_NUMBER 是系統在您建立專案時自動產生的，而 PROJECT_ID 則是由您或專案建立者所建立。如要設定專案，請按照下列步驟操作：

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

取得必要角色

如要取得使用 Memory Bank 所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

所有使用者： Agent Platform 使用者 (roles/aiplatform.user)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

如果您是從部署在 Google Kubernetes Engine 或 Cloud Run 的代理程式，向 Memory Bank 發出要求，請確認服務帳戶具備必要權限。Reasoning Engine Service Agent 已具備讀取和寫入記憶內容的必要權限，因此 Agent Runtime 的外送要求應已具備存取 Memory Bank 的權限。

安裝程式庫

本節假設您已設定 Python 開發環境，或使用具備 Python 開發環境的執行階段 (例如 Colab)。

安裝 Agent Platform SDK：

pip install google-cloud-aiplatform>=1.111.0

驗證

請按照「向 Vertex AI 進行驗證」一文中的指示操作。

設定 Agent Platform SDK 用戶端

執行下列程式碼，設定 Agent Platform SDK 用戶端：

Agent Platform SDK

import vertexai

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

其中

PROJECT_ID 是您 Google Cloud 開發及部署代理程式的專案 ID，
LOCATION 是 Memory Bank支援的地區之一。

建立或更新 Agent Platform 執行個體

如要開始使用 Memory Bank，請先建立 Agent Platform 執行個體。如果沒有執行個體，可以使用預設設定建立：

agent_engine = client.agent_engines.create()

# Optionally, print out the Agent Platform resource name. You will need the
# resource name to interact with your Agent Platform instance later on.
print(agent_engine.api_resource.name)

如要自訂新或現有 Memory Bank 執行個體行為的設定，請參閱「為 Memory Bank 設定 Agent Platform 執行個體」。舉例來說，您可以指定 Memory Bank 認為有意義而要保留的資訊。

您的 Agent Platform 執行個體支援工作階段和 Memory Bank，建立執行個體時，系統不會部署任何代理程式。如要使用 Agent Runtime，您必須在建立或更新 Agent Platform 執行個體時，提供要部署的代理程式。

建立 Agent Platform 執行個體後，您可以使用執行個體名稱讀取或寫入記憶體。例如：

# Generate memories using your Memory Bank instance.
client.agent_engines.memories.generate(
  # `name` should have the format `projects/.../locations/.../reasoningEngines/...`.
  name=agent_engine.api_resource.name,
  ...
)

搭配 Agent Runtime 使用

雖然記憶體庫可在任何執行階段中使用，但您也可以搭配代理程式執行階段使用記憶體庫，從已部署的代理程式讀取及寫入記憶體。

如要在 Agent Platform 上部署含有 Memory Bank 的代理程式，請先設定 Agent Runtime 的環境。接著，準備將代理程式部署至 Agent Runtime，並整合記憶體。部署的代理程式應視需要呼叫，讀取和寫入記憶內容。

AdkApp

如果您使用 Agent Platform Agent Development Kit 範本，代理程式預設會使用 VertexAiMemoryBankService 部署至 Agent Platform。這表示 ADK 記憶體工具會從記憶庫讀取記憶。

from google.adk.agents import Agent
from vertexai.preview.reasoning_engines import AdkApp

# Develop an agent using the ADK template.
agent = Agent(...)

adk_app = AdkApp(
      agent=adk_agent,
      ...
)

# Deploy the agent to Agent Runtime.
agent_engine = client.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
            # Optional.
            **context_spec
      }
)

# Update an existing Agent Runtime to add or modify the Runtime.
agent_engine = client.agent_engines.update(
      name=agent_engine.api_resource.name,
      agent=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
            # Optional.
            **context_spec
      }
)

更改下列內容：

STAGING_BUCKET：用於暫存 Agent Runtime 的 Cloud Storage bucket。

如要進一步瞭解如何搭配 ADK 使用 Memory Bank，請參閱「使用 Agent Development Kit 快速入門」。

自訂服務專員

您可以搭配在 Agent Runtime 上部署的自訂代理使用 Memory Bank。在這種情況下，代理應協調對 Memory Bank 的呼叫，以觸發記憶體生成和記憶體擷取呼叫。

部署至 Agent Runtime 的應用程式可以讀取環境變數 GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION、GOOGLE_CLOUD_AGENT_ENGINE_ID，從環境推斷 Agent Runtime 名稱：

project = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION")
agent_engine_id = os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID")

agent_engine_name = f"projects/{project}/locations/{location}/reasoningEngines/{agent_engine_id}"

如果您在 Agent Runtime 上使用預設服務代理人，代理人已具備讀取和寫入記憶體的權限。如果您使用客戶服務帳戶，請授予服務帳戶讀取及寫入回憶集的權限。所需權限取決於代理程式應能執行的作業。如果只希望代理程式擷取及生成記憶內容，aiplatform.memories.generate 和 aiplatform.memories.retrieve 就足夠了。

在所有其他執行階段中使用

如要在其他環境 (例如 Cloud Run 或 Colab) 中使用 Memory Bank，請建立 Agent Runtime，但不要提供代理程式。如果您未提供設定，系統會使用預設設定建立 Memory Bank，以管理記憶體生成和擷取作業。

agent_engine = client.agent_engines.create()

如果您曾使用 Agent Platform，建立沒有執行階段的新 Agent Platform 執行個體，應該只需要幾秒鐘。如果您是第一次使用 Agent Platform，可能需要較長的時間 (1 到 2 分鐘)。

如要設定行為，請提供 Memory Bank 設定：

建立

agent_engine = client.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_config": ...
    }
  }
)

更新

如要變更 Memory Bank 設定，可以更新 Agent Platform 執行個體。

agent_engine = client.agent_engines.update(
  # You can access the name using `agent_engine.api_resource.name` for an AgentEngine object.
  name="AGENT_ENGINE_NAME",
  config={
    "context_spec": {
      "memory_bank_config": ...
    }
  }
)

更改下列內容：

RUNTIME_NAME：Agent Runtime 的名稱，格式應為 projects/.../locations/.../reasoningEngines/...。請參閱 Memory Bank 支援的區域。

只要環境有權讀取及寫入記憶內容，您就能使用 Memory Bank。舉例來說，如要在 Cloud Run 中使用 Memory Bank，請授予 Cloud Run 服務身分讀取及寫入記憶內容的權限。所需權限取決於代理程式應能執行的作業。如果只希望代理程式擷取及生成記憶內容，aiplatform.memories.generate 和 aiplatform.memories.retrieve 就已足夠。

設定 Agent Platform 執行個體，以便使用 Memory Bank

您可以設定 Memory Bank，自訂記憶體的產生和管理方式。如未提供設定，Memory Bank 會使用各類型設定的預設設定。

您可以為執行個體設定下列記憶體庫設定：

自訂設定：設定如何從來源資料擷取記憶內容，並與現有記憶內容合併。
相似度搜尋設定：指定 Memory Bank 用於相似度搜尋的嵌入模型。預設為 text-embedding-005。
生成設定：設定記憶體生成作業使用的 LLM 記憶體庫。預設為 gemini-2.5-flash。
存留時間設定：設定系統如何自動為建立或更新的記憶設定存留時間。預設為沒有存留時間。

以下範例顯示預設的 Memory Bank：

字典

memory_bank_config = {
  "generation_config": {
    # `gemini-2.5-flash` will be used to extract and consolidate memories.
    # Note: The global endpoint will be used for regions that don't have a
    # regional endpoint available.
    "model": "projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"
  },
  "similarity_search_config": {
    # `text-embedding-005` will be used for similarity search, including
    # during consolidation. Consolidation uses similarity search to find
    # candidate memories that may be updated with new information.
    "embedding_model": "projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/text-embedding-005"
  },
  "ttl_config": {
    # Default TTL for memory revisions is 365 days.
    "memory_revision_default_ttl": f"{365 * 24 * 60 * 60}s"
  },
  "customization_configs": [
    {
      # Extract user information, preferences, key conversation details,
      # and information that the user explicitly asked to be remembered.
      "memory_topics": [
        {"managed_memory_topic": "USER_PERSONAL_INFO"},
        {"managed_memory_topic": "USER_PREFERENCES"},
        {"managed_memory_topic": "KEY_CONVERSATION_DETAILS"},
        {"managed_memory_topic": "EXPLICIT_INSTRUCTIONS"}
      ],
      "consolidation_config": {
        # Only use the latest memory revision of each candidate memory during
        # consolidation.
        "revisions_per_candidate_count": 1
      },
      # Only use the pre-defined set of examples.
      "generate_memories_examples": [],
      # Generate memories in the first person.
      "enable_third_person_memories": False
    }
  ],
  # Memory revisions will be persisted. This can be overridden on a request-level.
  "disable_memory_revisions": False
}

以類別為準

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
from vertexai.types import ManagedTopicEnum
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigGenerationConfig as GenerationConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig as SimilaritySearchConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfig as TtlConfig

memory_bank_config = MemoryBankConfig(
  generation_config=GenerationConfig(
    # `gemini-2.5-flash` will be used to extract and consolidate memories.
    # Note: The global endpoint will be used for regions that don't have a
    # regional endpoint available.
    model="projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"
  ),
  similarity_search_config=SimilaritySearchConfig(
    # `text-embedding-005` will be used for similarity search, including
    # during consolidation. Consolidation uses similarity search to find
    # candidate memories that may be updated with new information.
    embedding_model="projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/text-embedding-005"
  ),
  ttl_config=TtlConfig(
    # Default TTL for memory revisions is 365 days.
    memory_revision_default_ttl=f"{365 * 24 * 60 * 60}s"
  ),
  customization_configs=[
    CustomizationConfig(
      # Extract personal information, preferences, key conversation details,
      # and information that the user explicitly asked to be remembered.
      memory_topics=[
        MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
            managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)),
        MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
            managed_topic_enum=ManagedTopicEnum.USER_PREFERENCES)),
        MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
            managed_topic_enum=ManagedTopicEnum.KEY_CONVERSATION_DETAILS)),
        MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
            managed_topic_enum=ManagedTopicEnum.EXPLICIT_INSTRUCTIONS))
      ],
      # Only use the pre-defined set of examples.
      generate_memories_examples=[],
      consolidation_config=ConsolidationConfig(
        # Only use the latest memory revision of each candidate memory during
        # consolidation.
        revisions_per_candidate_count=1
      ),
      # Generate memories in the first person.
      enable_third_person_memories=False,
    )
  ],
  # Memory revisions will be persisted. This can be overridden on a request-level.
  disable_memory_revisions=False
)

建立或更新 Agent Platform 執行個體時，您可以調整 Memory Bank 設定。以下範例說明如何建立或更新執行個體，並使用特定 Memory Bank 設定。

client.agent_engines.create(
      ...,
      config={
            "context_spec": {
                  "memory_bank_config": memory_bank_config
            }
      }
)

# Alternatively, update an existing Agent Platform instance's Memory Bank config.
agent_engine = client.agent_engines.update(
      name=agent_engine.api_resource.name,
      config={
          "context_spec": {
                "memory_bank_config": memory_bank_config
          }
      }
)

自然語言記憶體自訂設定

如要自訂 Memory Bank 擷取自然語言記憶的方式，請在設定執行個體時設定擷取行為。使用下列選項自訂行為：

設定記憶體主題：定義 Memory Bank 應視為有意義並保留的資訊類型。只有符合其中一個記憶體主題的資訊，才會由 Memory Bank 保留。
提供少量樣本：向 Memory Bank 示範記憶內容擷取的預期行為。
設定回憶集錦的視角：設定回憶集錦要以第一人稱 (預設) 或第三人稱生成。
設定合併：設定 Memory Bank 在合併每個記憶體候選項目時，要考量多少記憶體修訂版本。

您可以透過兩個步驟，自訂 Memory Bank 的資訊擷取行為：告知和展示。記憶體主題會告知 Memory Bank 要保留哪些資訊。少量樣本會展示 Memory Bank 哪些資訊應產生特定記憶，協助模型學習您期望的模式、細微差異和措辭。

您可以視需要為不同範圍層級設定不同行為。舉例來說，對工作階段層級記憶內容有意義的主題，可能對使用者層級記憶內容 (跨多個工作階段) 來說沒有意義。如要為特定記憶內容子集設定行為，請設定自訂設定的範圍鍵。只有包含這些範圍鍵的 GenerateMemories 要求，才會使用該設定。您也可以省略 scope_key 欄位，設定預設行為 (適用於所有範圍鍵組合)。如果要求沒有與其他自訂設定的範圍鍵完全相符的設定，就會套用這項設定。

舉例來說，user_level_config 只會套用至完全使用範圍鍵 user_id 的 GenerateMemories 要求 (即 scope={"user_id": "123"}，沒有其他鍵)。default_config 會套用至其他要求：

字典


user_level_config = {
  "scope_keys": ["user_id"],
  "memory_topics": [...],
  "generate_memories_examples": [...]
}

default_config = {
  "memory_topics": [...],
  "generate_memories_examples": [...]
}

memory_bank_config = {
  "customization_configs": [
    user_level_config,
    default_config
  ]
}

以類別為準

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig

user_level_config = CustomizationConfig(
  scope_keys=["user_id"],
  memory_topics=[...],
  generate_memories_examples=[...]
)

設定記憶體主題

「記憶主題」會識別出 Memory Bank 認為有意義的資訊，並將其保留為生成的記憶內容。Memory Bank 支援兩種記憶主題：

受管理的主題：標籤和指示由記憶庫定義。您只需要提供受管理主題的名稱。例如，假設使用者要求系統將文字從英文翻譯成法文
字典
memory_topic = { "managed_memory_topic": { "managed_topic_enum": "USER_PERSONAL_INFO" } }
以類別為準
from vertexai.types import ManagedTopicEnum from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic memory_topic = MemoryTopic( managed_memory_topic=ManagedMemoryTopic( managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO ) )
記憶庫支援下列受管理的主題：
- 使用者資訊 (USER_PERSONAL_INFO)：與使用者相關的重要資訊，例如姓名、關係、興趣和重要日期。舉例來說，「我在 Google 工作」或「我的結婚週年紀念日是 12 月 31 日」。
- 使用者偏好 (USER_PREFERENCES)：明確或隱含的喜好、不喜好、偏好的風格或模式。例如「我比較喜歡中間的座位」。
- 重要對話事件和工作結果 (KEY_CONVERSATION_DETAILS)：對話中的重要里程碑或結論。舉例來說，「我預訂了從 JFK 往返 SFO 的機票，我將於 2025 年 6 月 1 日出發，並於 2025 年 6 月 7 日返回。
- 明確的記憶 / 忘記指令 (EXPLICIT_INSTRUCTIONS)：使用者明確要求代理程式記憶或忘記的資訊。舉例來說，如果使用者說「請記住我主要使用 Python」，記憶庫就會產生「我主要使用 Python」這類記憶。

自訂主題：設定 Memory Bank 執行個體時，您可以自行定義標籤和說明。這些值會用於 Memory Bank 擷取步驟的提示。例如，假設使用者要求系統將文字從英文翻譯成法文

字典

memory_topic = {
  "custom_memory_topic": {
    "label": "business_feedback",
    "description": """Specific user feedback about their experience at
    the coffee shop. This includes opinions on drinks, food, pastries, ambiance,
    staff friendliness, service speed, cleanliness, and any suggestions for
    improvement."""
    }
}

以類別為準

from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic

memory_topic = MemoryTopic(
  custom_memory_topic=CustomMemoryTopic(
    label="business_feedback",
    description="""Specific user feedback about their experience at
    the coffee shop. This includes opinions on drinks, food, pastries, ambiance,
    staff friendliness, service speed, cleanliness, and any suggestions for
    improvement."""
  )
)

使用自訂主題時，建議一併提供少量樣本，說明如何從對話中擷取記憶內容。

自訂時，您可以任意組合記憶體主題。舉例來說，您可以使用可用受管理記憶體主題的子集：

字典

customization_config = {
  "memory_topics": [
    { "managed_memory_topic": { "managed_topic_enum": "USER_PERSONAL_INFO" } },
    { "managed_memory_topic": { "managed_topic_enum": "USER_PREFERENCES" } }
  ]
}

以類別為準

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
from vertexai.types import ManagedTopicEnum

customization_config = CustomizationConfig(
  memory_topics=[
      MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
              managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)
      ),
      MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
              managed_topic_enum=ManagedTopicEnum.USER_PREFERENCES)
      ),
  ]
)

您也可以同時使用受管理和自訂主題 (或只使用自訂主題)：

字典

customization_config = {
  "memory_topics": [
    { "managed_memory_topic": { "managed_topic_enum": "USER_PERSONAL_INFO" } },
    {
      "custom_memory_topic": {
        "label": "business_feedback",
        "description": """Specific user feedback about their experience at
the coffee shop. This includes opinions on drinks, food, pastries, ambiance,
staff friendliness, service speed, cleanliness, and any suggestions for
improvement."""
        }
    }
  ]
}

以類別為準

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
from vertexai.types import ManagedTopicEnum

customization_config = CustomizationConfig(
  memory_topics=[
      MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
              managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)
      ),
      MemoryTopic(
          custom_memory_topic=CustomMemoryTopic(
              label="business_feedback",
              description="""Specific user feedback about their experience at
the coffee shop. This includes opinions on drinks, food, pastries, ambiance,
staff friendliness, service speed, cleanliness, and any suggestions for
improvement."""
          )
    )
  ]
)

少量樣本

您可以透過少量樣本，向記憶體庫示範預期的記憶體擷取行為。舉例來說，您可以提供輸入對話範例，以及預期從該對話中擷取的記憶內容。

建議您一律搭配自訂主題使用少量樣本，讓 Memory Bank 瞭解預期行為。使用受管理主題時，Memory Bank 會為每個主題定義範例，因此少量樣本為選用項目。如要示範不應產生記憶內容的對話，請提供空白的 generated_memories 清單。

舉例來說，您可以提供少樣本範例，說明如何從顧客訊息中擷取有關貴商家的意見回饋：

字典

example = {
    "conversationSource": {
      "events": [
        {
          "content": {
            "role": "model",
            "parts": [{ "text": "Welcome back to The Daily Grind! We'd love to hear your feedback on your visit." }] }
        },
        {
          "content": {
            "role": "user",
            "parts": [{ "text": "Hey. The drip coffee was a bit lukewarm today, which was a bummer. Also, the music was way too loud, I could barely hear my friend." }] }
        }
      ]
    },
    "generatedMemories": [
      {
        "fact": "The user reported that the drip coffee was lukewarm."
      },
      {
        "fact": "The user felt the music in the shop was too loud."
      }
    ]
}

以類別為準

from google.genai.types import Content, Part
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent as ConversationSourceEvent
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory as ExampleGeneratedMemory

example = GenerateMemoriesExample(
    conversation_source=ConversationSource(
        events=[
            ConversationSourceEvent(
                content=Content(
                    role="model",
                    parts=[Part(text="Welcome back to The Daily Grind! We'd love to hear your feedback on your visit.")]
                )
            ),
            ConversationSourceEvent(
                content=Content(
                    role="user",
                    parts=[Part(text= "Hey. The drip coffee was a bit lukewarm today, which was a bummer. Also, the music was way too loud, I could barely hear my friend.")]
                )
            )
        ]
    ),
    generated_memories=[
        ExampleGeneratedMemory(
            fact="The user reported that the drip coffee was lukewarm."
        ),
        ExampleGeneratedMemory(
            fact="The user felt the music in the shop was too loud."
        )
    ]
)

您也可以提供不應生成任何回憶內容的對話範例，方法是為預期輸出內容提供空白清單 (generated_memories)：

字典

example = {
    "conversationSource": {
        "events": [
          {
              "content": {
                  "role": "model",
                  "parts": [{ "text": "Good morning! What can I get for you at The Daily Grind?" }] }
          },
          {
              "content": {
                  "role": "user",
                  "parts": [{ "text": "Thanks for the coffee." }] }
          }
        ]
    },
    "generatedMemories": []
}

以類別為準

from google.genai.types import Content, Part
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent as ConversationSourceEvent

example = GenerateMemoriesExample(
    conversation_source=ConversationSource(
        events=[
            ConversationSourceEvent(
                content=Content(
                    role="model",
                    parts=[Part(text="Welcome back to The Daily Grind! We'd love to hear your feedback on your visit.")]
                )
            ),
            ConversationSourceEvent(
                content=Content(
                    role="user",
                    parts=[Part(text= "Thanks for the coffee!")]
                )
            )
        ]
    ),
    generated_memories=[]
)

記憶體觀點

根據預設，記憶會以第一人稱生成 (例如「我使用 Memory Bank 管理記憶」)。您可以使用 enable_third_person_memories 參數，將 Memory Bank 設定為以第三人稱生成 (例如「使用者使用 Memory Bank 管理記憶」)。

字典

customization_config = {
  "enable_third_person_memories": True
}

以類別為準

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig

customization_config = CustomizationConfig(
    enable_third_person_memories=True
)

摘要自訂

在整合期間，Memory Bank 會決定如何將新取得的資訊整合到現有的記憶體集中。Memory Bank 會評估是否要新增記憶、更新現有記憶以提供額外背景資訊，或是刪除過時的記憶。

為確保記憶體內容品質優良且經過驗證，Memory Bank 可選擇性分析記憶體記錄，區分長期趨勢和一次性離群值。

根據預設，記憶體庫只會比較新資訊與候選記憶體的最新快照 (即「記憶體修訂版本」)。如要深入分析，請設定 revisions_per_candidate_count 參數。這個參數會定義記憶體庫在合併期間，會考量每個「候選記憶體」(正在評估更新的特定記錄) 的多少個先前修訂版本。

字典

customization_config = {
  "consolidation_customization": {
    "revisions_per_candidate_count": 10
  }
}

以類別為準

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig

customization_config = CustomizationConfig(
    consolidation_customization=ConsolidationConfig(
      revisions_per_candidate_count=10
    )
)

增加 revisions_per_candidate_count 可讓系統考量擷取資訊的重複次數，進而產生更一致且經過驗證的記憶內容。不過，數量越多，在合併程序中消耗的符記就越多。

相似度搜尋設定

相似度搜尋設定可控管執行個體用於相似度搜尋的嵌入模型。相似度搜尋用於識別哪些記憶體應成為合併候選項目，以及用於以相似度搜尋為基礎的記憶體擷取。如未提供這項設定，Memory Bank 會使用 text-embedding-005 做為預設模型。

如果預期使用者對話會使用非英文語言，請使用支援多種語言的模型，例如 gemini-embedding-001 或 text-multilingual-embedding-002，以提升檢索品質。

字典

memory_bank_config = {
    "similarity_search_config": {
        "embedding_model": "EMBEDDING_MODEL",
    }
}

以類別為準

from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig as SimilaritySearchConfig

memory_bank_config = MemoryBankConfig(
    similarity_search_config=SimilaritySearchConfig(
        embedding_model="EMBEDDING_MODEL"
    )
)

更改下列內容：

EMBEDDING_MODEL：用於相似性搜尋的 Google 文字嵌入模型，格式為 projects/{project}/locations/{location}/publishers/google/models/{model}。

生成設定

生成設定會控管用於生成記憶的大型語言模型，包括擷取記憶和合併新記憶與現有記憶。

Memory Bank 預設使用 gemini-2.5-flash 模型。如果所在區域不支援區域性 Gemini，系統會使用全域端點。

字典

memory_bank_config = {
  "generation_config": {
    "model": "LLM_MODEL",
  }
}

以類別為準

from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigGenerationConfig as GenerationConfig

memory_bank_config = MemoryBankConfig(
  generation_config=GenerationConfig(
    model="LLM_MODEL"
  )
)

更改下列內容：

LLM_MODEL：用於擷取和整合記憶內容的 Google LLM 模型，格式為 projects/{project}/locations/{location}/publishers/google/models/{model}。

存留時間 (TTL) 設定

TTL 設定可控管 Memory Bank 應如何動態設定記憶體的到期時間。到期後，記憶體將無法擷取並會遭到刪除。

如果未提供設定，系統就不會為建立或更新的回憶內容動態設定到期時間，因此回憶內容不會過期，除非手動設定到期時間。

TTL 設定有兩種方式：

預設存留時間：存留時間會套用至所有建立或更新記憶的作業，包括 UpdateMemory、CreateMemory 和 GenerateMemories。

字典

memory_bank_config = {
  "ttl_config": {
      "default_ttl": f"TTLs"
  }
}

以類別為準

from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfig as TtlConfig

memory_bank_config = MemoryBankConfig(
  ttl_config=TtlConfig(
      default_ttl=f"TTLs"
  )
)

更改下列內容：

TTL：存留時間長度 (以秒為單位)。更新記憶後，系統會根據新的計算結果 (目前時間 + 存留時間) 覆寫記憶的先前到期時間。

精細 (以作業為單位) 存留時間：系統會根據建立或更新記憶體的作業計算存留時間。如果未針對特定作業設定，作業就不會更新記憶體的到期時間。

字典

memory_bank_config = {
  "ttl_config": {
      "granular_ttl": {
          "create_ttl": f"CREATE_TTLs",
          "generate_created_ttl": f"GENERATE_CREATED_TTLs",
          "generate_updated_ttl": f"GENERATE_UPDATED_TTLs"
      }
  }
}

以類別為準

from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfig as TtlConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfigGranularTtlConfig as GranularTtlConfig

memory_bank_config = MemoryBankConfig(
  ttl_config=TtlConfig(
      granular_ttl_config=GranularTtlConfig(
          create_ttl=f"CREATE_TTLs",
          generate_created_ttl=f"GENERATE_CREATED_TTLs",
          generate_updated_ttl=f"GENERATE_UPDATED_TTLs",
      )
  )
)

更改下列內容：

CREATE_TTL：使用 CreateMemory 建立的記憶存留時間 (以秒為單位)。
GENERATE_CREATED_TTL：使用 GenerateMemories 建立的記憶存留時間 (以秒為單位)。
GENERATE_UPDATED_TTL：使用 GenerateMemories 更新記憶時，記憶的存留時間 (以秒為單位)。新計算的到期時間 (目前時間 + 存留時間) 會覆寫記憶的先前到期時間。

後續步驟

快速入門

Memory Bank API 快速入門導覽課程

開始使用 Memory Bank API 管理長期記憶。

快速入門

Agent Development Kit 快速入門

開始使用 Agent Development Kit (ADK)。

設定 Agent Platform Memory Bank 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

開始使用

設定 Google Cloud 專案

取得必要角色

安裝程式庫

驗證

設定 Agent Platform SDK 用戶端

Agent Platform SDK

建立或更新 Agent Platform 執行個體

搭配 Agent Runtime 使用

AdkApp

自訂服務專員

在所有其他執行階段中使用

建立

更新

設定 Agent Platform 執行個體，以便使用 Memory Bank

字典

以類別為準

自然語言記憶體自訂設定

字典

以類別為準

設定記憶體主題

字典

以類別為準

字典

以類別為準

字典

以類別為準

字典

以類別為準

少量樣本

字典

以類別為準

字典

以類別為準

記憶體觀點

字典

以類別為準

摘要自訂

字典

以類別為準

相似度搜尋設定

字典

以類別為準

生成設定

字典

以類別為準

存留時間 (TTL) 設定

字典

以類別為準

字典

以類別為準

後續步驟

Memory Bank API 快速入門導覽課程

Agent Development Kit 快速入門

設定 Agent Platform Memory Bank