Memory Bank einrichten

Wenn Sie die Agent Platform Memory Bank verwenden möchten, müssen Sie zuerst eine Memory Bank-Instanz erstellen und konfigurieren. Diese Instanz verwaltet Ihre gemerkten Informationen und kann in verschiedenen Laufzeiten in Ihre KI-Agenten eingebunden werden.

In diesem Dokument wird beschrieben, wie Sie Ihr Cloud de Confiance by S3NS -Projekt einrichten, die erforderlichen Bibliotheken installieren und eine Instanz mit benutzerdefinierten Konfigurationen wie Themen und TTL erstellen oder aktualisieren.

Jetzt starten

Bevor Sie mit der Memory Bank arbeiten, müssen Sie Ihre Umgebung einrichten.

Projekt in Cloud de Confiance einrichten

Jedes Projekt kann auf zwei Arten identifiziert werden: über die Projektnummer oder die Projekt-ID. Die PROJECT_NUMBER wird beim Erstellen des Projekts automatisch erstellt, während die PROJECT_ID von Ihnen oder dem Ersteller des Projekts erstellt wird. So richten Sie ein Projekt ein:

1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance 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

2. Verify that billing is enabled for your Cloud de Confiance project.

3. Enable the Agent Platform API, if it is not already enabled.

   Roles required to enable APIs

   To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

   Enable the API

Erforderliche Berechtigungen abrufen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zur Verwendung von Memory Bank benötigen:

• Memory Bank-Instanz erstellen oder aktualisieren: Agent Platform User (roles/aiplatform.user)
• Erinnerungen lesen, schreiben oder erstellen: Memory Bank-Nutzer (roles/aiplatform.memoryUser)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Wenn Sie Anfragen an Memory Bank von einem Agent senden, der in Google Kubernetes Engine (GKE) oder Cloud Run bereitgestellt wird, muss Ihr Dienstkonto die erforderlichen Berechtigungen zum Lesen, Schreiben oder Generieren von Erinnerungen haben. Der Reasoning Engine-Dienst-Agent hat bereits die erforderlichen Berechtigungen zum Lesen, Schreiben und Generieren von Erinnerungen. Ausgehende Anfragen von Agent Runtime sollten also bereits die Berechtigung haben, auf Memory Bank zuzugreifen.

Bibliotheken installieren

In diesem Abschnitt wird davon ausgegangen, dass Sie eine Python-Entwicklungsumgebung eingerichtet haben oder eine Laufzeit mit einer Python-Entwicklungsumgebung (z. B. Colaboratory) verwenden.

Installieren Sie das Agent Platform SDK:

pip install google-cloud-agentplatform>=2.0.1

Authentifizierung

Folgen Sie der Anleitung unter Bei der Gemini Enterprise Agent Platform authentifizieren.

Agent Platform SDK-Client einrichten

Führen Sie den folgenden Code aus, um einen Agent Platform SDK-Client einzurichten:

import agentplatform

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

Multiregionale und globale Endpunkte

Memory Bank unterstützt multiregionale und globale Endpunkte:

• Legen Sie für globale Instanzen den Standort auf global fest.
• Legen Sie für multiregionale Instanzen den Standort auf us oder eu fest.

Memory Bank-Instanz erstellen oder aktualisieren

Wenn Sie Memory Bank verwenden möchten, benötigen Sie zuerst eine Memory Bank-Instanz. Wenn Sie noch keine Instanz haben, können Sie eine mit der Standardkonfiguration und einem Anzeigenamen Ihrer Wahl erstellen.

# create the resource
memory_bank = client.memory_banks.create(
    config={
        "display_name": "My Memory Bank",
    }
)

# Optionally, print out the Memory Bank resource name. You will need the
# resource name to interact with your Memory Bank instance later on.
print(memory_bank.name)

Wenn Sie die Konfiguration des Verhaltens Ihrer neuen oder vorhandenen Memory Bank-Instanz anpassen möchten, lesen Sie den Abschnitt Memory Bank-Instanz konfigurieren. Sie können beispielsweise angeben, welche Informationen Memory Bank als sinnvoll erachten soll, um sie zu speichern.

Sobald Sie eine Memory Bank-Instanz haben, können Sie den Namen der Instanz verwenden, um Erinnerungen zu lesen oder zu schreiben. Beispiel:

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

Mit Agent Runtime verwenden

Memory Bank kann zwar in jeder Laufzeit verwendet werden, Sie können Memory Bank aber auch mit der Agent Runtime verwenden, um Erinnerungen aus Ihrem bereitgestellten Agent zu lesen und in ihn zu schreiben.

Wenn Sie einen Agenten mit integrierter Memory Bank in Agent Runtime bereitstellen möchten, müssen Sie zuerst Ihre Umgebung für Agent Runtime einrichten. Bereiten Sie dann Ihren Agenten für die Bereitstellung in der Agent Runtime mit Speicherintegration vor. Ihr bereitgestellter Agent sollte Aufrufe zum Lesen und Schreiben von gespeicherten Informationen nach Bedarf ausführen.

from google.adk.agents import Agent
from agentplatform.frameworks import AdkApp

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

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

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

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

Ihre in Agent Runtime bereitgestellte Anwendung kann die Umgebungsvariablen GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION und GOOGLE_CLOUD_AGENT_ENGINE_ID lesen,um den Namen der Agent Runtime aus der Umgebung abzuleiten:

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}"

Wenn Sie den Standard-Dienst-Agenten für Ihren Agenten in der Agent Runtime verwenden, hat Ihr Agent bereits die Berechtigung, gemerkte Informationen zu lesen und zu schreiben. Wenn Sie ein Kundendienstkonto verwenden, müssen Sie Ihrem Dienstkonto Berechtigungen zum Lesen und Schreiben von gemerkten Informationen erteilen. Die erforderlichen Berechtigungen hängen davon ab, welche Vorgänge Ihr KI-Agent ausführen können soll. Wenn Ihr Agent nur Erinnerungen abrufen und generieren soll, reichen aiplatform.memories.generate und aiplatform.memories.retrieve aus.

In allen anderen Laufzeiten verwenden

Wenn Sie Memory Bank in einer anderen Umgebung wie Cloud Run oder Colab verwenden möchten, erstellen Sie eine Memory Bank. Wenn Sie keine Konfiguration angeben, wird Memory Bank mit den Standardeinstellungen für die Verwaltung der Speichergenerierung und des Speicherabrufs erstellt.

memory_bank = client.memory_banks.create()

Wenn Sie Memory Bank bereits verwendet haben, sollte das Erstellen einer neuen Memory Bank-Instanz nur wenige Sekunden dauern. Wenn Sie die Memory Bank zum ersten Mal verwenden, kann es länger dauern (1–2 Minuten).

Wenn Sie das Verhalten konfigurieren möchten, geben Sie eine Memory Bank-Konfiguration an:

memory_bank = client.memory_banks.create(
  managed_semantic_memory_config={
    "generation_config": ...,
    "unstructured_memory_configs": [...],
    "structured_memory_configs": [...],
    "similarity_search_config": ...,
    "ttl_config": ...,
    "disable_memory_revisions": False,
  }
)

memory_bank = client.runtimes.update(
  # You can access the name using `memory_bank.name` for a MemoryBank object.
  name="MEMORY_BANK_NAME",
  config={
    "context_spec": {
      "memory_bank_config": {
        "generation_config": ...,
        "customization_configs": [...],
        "structured_memory_configs": [...],
        "similarity_search_config": ...,
        "ttl_config": ...,
        "disable_memory_revisions": False,
      }
    }
  }
)

Sie können Memory Bank in jeder Umgebung verwenden, die die Berechtigung zum Lesen und Schreiben von Erinnerungen hat. Wenn Sie Memory Bank beispielsweise mit Cloud Run verwenden möchten, erteilen Sie der Cloud Run-Dienstidentität Berechtigungen zum Lesen und Schreiben von Memorys. Die erforderlichen Berechtigungen hängen davon ab, welche Vorgänge Ihr Agent ausführen können soll. Wenn Ihr Agent nur Erinnerungen abrufen und generieren soll, reichen aiplatform.memories.generate und aiplatform.memories.retrieve aus.

Memory Bank-Instanz konfigurieren

Sie können Ihre Memory Bank konfigurieren, um anzupassen, wie Erinnerungen generiert und verwaltet werden. Wenn Sie die Konfiguration nicht angeben, verwendet Memory Bank die Standardeinstellungen für jeden Konfigurationstyp.

Sie können die folgenden Memory Bank-Einstellungen für Ihre Instanz konfigurieren:

• Anpassungskonfiguration (unstructured_memory_configs): Konfiguriert, wie gemerkte Informationen aus Quelldaten extrahiert und mit vorhandenen gemerkten Informationen zusammengeführt werden.
• Konfiguration der Ähnlichkeitssuche: Gibt an, welches Einbettungsmodell die Memory Bank für die Ähnlichkeitssuche verwendet. Die Standardeinstellung ist text-embedding-005.
• Generierungskonfiguration: Konfiguriert, welches LLM Memory Bank für die Generierung von Erinnerungen verwendet. Die Standardeinstellung ist gemini-3.5-flash.
• TTL-Konfiguration: Hier wird konfiguriert, wie die TTL für erstellte oder aktualisierte gemerkte Informationen automatisch festgelegt wird. Die Standardeinstellung ist „Keine TTL“.

Das folgende Beispiel zeigt die Standard-Memory Bank:

managed_semantic_memory_config = {
  "generation_config": {
    # `gemini-3.5-flash` will be used to extract and consolidate memories.
    "model": "projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/gemini-3.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"
  },
  "unstructured_memory_configs": [
    {
      # Extract user information, preferences, key conversation details,
      # and information that the user explicitly asked to be remembered.
      "memory_topics": [
        {"managed_memory_topic": {"managed_topic_enum": "USER_PERSONAL_INFO"}},
        {"managed_memory_topic": {"managed_topic_enum": "USER_PREFERENCES"}},
        {"managed_memory_topic": {"managed_topic_enum": "KEY_CONVERSATION_DETAILS"}},
        {"managed_memory_topic": {"managed_topic_enum": "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 agentplatform.types import ManagedSemanticMemoryConfig
from agentplatform.types import ManagedSemanticMemoryConfigGenerationConfig as GenerationConfig
from agentplatform.types import ManagedSemanticMemoryConfigSimilaritySearchConfig as SimilaritySearchConfig
from agentplatform.types import ManagedSemanticMemoryConfigTtlConfig as TtlConfig
from agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig
from agentplatform.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

managed_semantic_memory_config = ManagedSemanticMemoryConfig(
  generation_config=GenerationConfig(
    # `gemini-3.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-3.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"
  ),
  unstructured_memory_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
)

Sie können die Memory Bank-Konfiguration beim Erstellen oder Aktualisieren Ihrer Instanz anpassen. Im folgenden Beispiel wird gezeigt, wie eine Instanz mit einer bestimmten Memory Bank-Konfiguration erstellt wird.

memory_bank = client.memory_banks.create(
    managed_semantic_memory_config=managed_semantic_memory_config
)

Konfiguration der Anpassung des Informationsspeichers in natürlicher Sprache

Wenn Sie anpassen möchten, wie Memory Bank gemerkte Informationen in natürlicher Sprache extrahiert, konfigurieren Sie das Extraktionsverhalten beim Einrichten Ihrer Instanz. Verwenden Sie die folgenden Optionen, um das Verhalten anzupassen:

• Memory-Themen konfigurieren: Legen Sie fest, welche Art von Informationen Memory Bank als sinnvoll für die Speicherung erachten soll. Nur Informationen, die zu einem dieser Themen passen, werden von Memory Bank gespeichert.
• Few-Shot-Beispiele bereitstellen: Zeigen Sie das erwartete Verhalten für die Extraktion von Informationen in die Memory Bank.
• Perspektive für Erinnerungen konfigurieren: Legen Sie fest, ob Erinnerungen in der ersten Person (Standard) oder in der dritten Person generiert werden sollen.
• Konsolidierung konfigurieren: Konfigurieren Sie, wie viele Speicherversionen die Memory Bank bei der Konsolidierung der einzelnen Speicherkandidaten berücksichtigt.
• Anwenden von Anpassungskonfigurationen: Wenden Sie Anpassungskonfigurationen mit unstructured_memory_configs auf Ihre Instanz an.

Das Anpassen des Extraktionsverhaltens Ihrer Memory Bank erfolgt in zwei Schritten: Erklären und Zeigen. Mit Memory-Themen wird Memory Bank mitgeteilt, welche Informationen beibehalten werden sollen. Mit wenigen Beispielen zeigen Sie Memory Bank, welche Art von Informationen zu einem bestimmten Memory führen soll. So kann das Tool die Muster, Nuancen und Formulierungen lernen, die Sie von ihm erwarten.

Optional können Sie für verschiedene Bereichsebenen ein anderes Verhalten konfigurieren. Die Themen, die für Erinnerungen auf Sitzungsebene relevant sind, sind möglicherweise nicht für Erinnerungen auf Nutzerebene (über mehrere Sitzungen hinweg) relevant. Wenn Sie das Verhalten für eine bestimmte Teilmenge von Erinnerungen konfigurieren möchten, legen Sie die Bereichsschlüssel der Anpassungskonfiguration fest. Nur GenerateMemories-Anfragen, die diese Bereichsschlüssel enthalten, verwenden diese Konfiguration. Sie können auch das Standardverhalten konfigurieren (gilt für alle Sätze von Bereichsschlüsseln), indem Sie das Feld scope_key weglassen. Diese Konfiguration gilt für alle Anfragen, die keine Konfiguration haben, die genau mit den Bereichsschlüsseln einer anderen Anpassungskonfiguration übereinstimmt.

Die user_level_config würde beispielsweise nur für GenerateMemories-Anfragen gelten, die genau den Bereichsschlüssel user_id verwenden (d.h. scope={"user_id": "123"} ohne zusätzliche Schlüssel). default_config würde für andere Anfragen gelten:

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

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

managed_semantic_memory_config = {
  "unstructured_memory_configs": [
    user_level_config,
    default_config
  ]
}

from agentplatform.types import ManagedSemanticMemoryConfig
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig

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

default_config = CustomizationConfig(
  memory_topics=[...],
  generate_memories_examples=[...]
)

managed_semantic_memory_config = ManagedSemanticMemoryConfig(
  unstructured_memory_configs=[
    user_level_config,
    default_config,
  ]
)

Themen der gemerkten Informationen konfigurieren

„Themen für gemerkte Informationen“ geben an, welche Informationen von Memory Bank als relevant eingestuft und daher als generierte gemerkte Informationen gespeichert werden sollten. Memory Bank unterstützt zwei Arten von Memory-Themen:

• Verwaltete Themen: Label und Anweisungen werden von Memory Bank definiert. Sie müssen nur den Namen des verwalteten Themas angeben. Beispiel:

  Wörterbuch

  memory_topic = {
    "managed_memory_topic": {
      "managed_topic_enum": "USER_PERSONAL_INFO"
    }
  }
  

  Klassenbasiert

  from agentplatform.types import ManagedTopicEnum
  from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
  from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
  
  memory_topic = MemoryTopic(
      managed_memory_topic=ManagedMemoryTopic(
          managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO
      )
  )
  

  Die folgenden verwalteten Themen werden von der Memory Bank unterstützt:

  • Nutzerinformationen (USER_PERSONAL_INFO): Wichtige Informationen über den Nutzer, z. B. Namen, Beziehungen, Hobbys und wichtige Termine. Beispiel: „Ich arbeite bei Google“ oder „Mein Hochzeitstag ist am 31. Dezember“.
  • Nutzerpräferenzen (USER_PREFERENCES): Angegebene oder implizierte Vorlieben, Abneigungen, bevorzugte Stile oder Muster. Beispiel: „Ich bevorzuge den mittleren Sitz.“
  • Wichtige Unterhaltungsereignisse und Aufgabenergebnisse (KEY_CONVERSATION_DETAILS): Wichtige Meilensteine oder Schlussfolgerungen im Dialog. Beispiel: „Ich habe Hin- und Rückflugtickets zwischen JFK und SFO gebucht. Ich fahre am 1. Juni 2025 los und komme am 7. Juni 2025 zurück.“
  • Explizite Anweisungen zum Speichern / Vergessen (EXPLICIT_INSTRUCTIONS): Informationen, die der Nutzer explizit vom Agenten speichern oder vergessen lassen möchte. Wenn der Nutzer beispielsweise sagt: „Merk dir, dass ich hauptsächlich Python verwende“, generiert Memory Bank eine Erinnerung wie „Ich verwende hauptsächlich Python“.

• Benutzerdefinierte Themen: Label und Anleitung werden von Ihnen bei der Einrichtung Ihrer Memory Bank-Instanz definiert. Sie werden im Prompt für den Extraktionsschritt von Memory Bank verwendet. Beispiel:

  Wörterbuch

  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."""
      }
  }
  

  Klassenbasiert

  from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
  from agentplatform.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."""
    )
  )
  

  Wenn Sie benutzerdefinierte Themen verwenden, sollten Sie auch Few-Shot-Beispiele angeben, die zeigen, wie gemerkte Informationen aus Ihrer Unterhaltung extrahiert werden sollen.

Bei der Anpassung können Sie eine beliebige Kombination von Themen für die Merkfunktion verwenden. Sie können beispielsweise eine Teilmenge der verfügbaren Themen für den verwalteten Speicher verwenden:

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

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

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)
      ),
  ]
)

Sie können auch eine Kombination aus verwalteten und benutzerdefinierten Themen verwenden (oder nur benutzerdefinierte Themen):

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 agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

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."""
          )
    )
  ]
)

Few-Shot-Beispiele

Mit Few-Shot-Beispielen können Sie Memory Bank das erwartete Verhalten beim Extrahieren von Informationen aus dem Speicher demonstrieren. Sie können beispielsweise eine Beispielunterhaltung und die Erinnerungen angeben, die aus dieser Unterhaltung extrahiert werden sollen.

Wir empfehlen, für benutzerdefinierte Themen immer Few-Shots zu verwenden, damit die Memory Bank das beabsichtigte Verhalten erlernen kann. Few-Shots sind optional, wenn Sie verwaltete Themen verwenden, da in Memory Bank Beispiele für jedes Thema definiert sind. Demonstrieren Sie Unterhaltungen, die voraussichtlich nicht zu Erinnerungen führen, indem Sie eine leere generated_memories-Liste angeben.

Sie können beispielsweise Few-Shot-Beispiele bereitstellen, die zeigen, wie Sie Feedback zu Ihrem Unternehmen aus Kundennachrichten extrahieren:

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 agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent as ConversationSourceEvent
from agentplatform.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."
        )
    ]
)

Sie können auch Beispiele für Unterhaltungen angeben, die nicht zu generierten gemerkten Informationen führen sollen. Geben Sie dazu eine leere Liste für die erwartete Ausgabe (generated_memories) an:

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 agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from agentplatform.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=[]
)

Perspektive der gemerkten Informationen

Standardmäßig werden Erinnerungen in der ersten Person generiert (z.B. „Ich verwende Memory Bank zur Verwaltung von Erinnerungen.“). Mit dem Parameter enable_third_person_memories können Sie Memory Bank so konfigurieren, dass die Ausgabe in der dritten Person erfolgt (z. B. „Der Nutzer verwendet Memory Bank für die Speicherverwaltung“).

customization_config = {
  "enable_third_person_memories": True
}

from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig

customization_config = CustomizationConfig(
    enable_third_person_memories=True
)

Anpassung der Konsolidierung

Während der Konsolidierung bestimmt die Memory Bank, wie neu erworbene Informationen in Ihren vorhandenen Speicher integriert werden. Die Memory Bank prüft, ob neue gemerkte Informationen HINZUGEFÜGT, vorhandene gemerkte Informationen mit zusätzlichem Kontext AKTUALISIERT oder veraltete gemerkte Informationen GELÖSCHT werden sollen.

Um hochwertige, bestätigte Erinnerungen zu gewährleisten, kann Memory Bank optional den Verlauf einer Erinnerung analysieren, um langfristige Trends von einmaligen Ausreißern zu unterscheiden.

Standardmäßig vergleicht die Memory Bank neue Informationen nur mit dem neuesten Snapshot einer Kandidaten-Erinnerung (einer „Memory-Revision“). Wenn Sie die Tiefe dieser Analyse erhöhen möchten, konfigurieren Sie den Parameter revisions_per_candidate_count. Mit diesem Parameter wird festgelegt, wie viele vorherige Überarbeitungen der einzelnen „Kandidatenspeicher“ (der spezifische Datensatz, der auf eine Aktualisierung hin überprüft wird) Memory Bank bei der Konsolidierung berücksichtigt.

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

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

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

Wenn revisions_per_candidate_count erhöht wird, werden die Erinnerungen konsistenter und fundierter, da die Wiederholung der aufgenommenen Informationen berücksichtigt wird. Eine höhere Anzahl erhöht jedoch den Tokenverbrauch während des Konsolidierungsprozesses.

Anpassungskonfigurationen anwenden

Wenn Sie Anpassungskonfigurationen auf Ihre Memory Bank-Instanz anwenden möchten, geben Sie sie in der Liste unstructured_memory_configs Ihrer managed_semantic_memory_config an:

managed_semantic_memory_config = {
  "unstructured_memory_configs": [customization_config],
  # Include other configurations (similarity search, generation, TTL)...
}

from agentplatform.types import ManagedSemanticMemoryConfig

managed_semantic_memory_config = ManagedSemanticMemoryConfig(
  unstructured_memory_configs=[customization_config],
  # Include other configurations (similarity search, generation, TTL)...
)

Konfiguration der Ähnlichkeitssuche

Mit der Konfiguration für die Ähnlichkeitssuche wird gesteuert, welches Einbettungsmodell von Ihrer Instanz für die Ähnlichkeitssuche verwendet wird. Die Ähnlichkeitssuche wird verwendet, um zu ermitteln, welche Erinnerungen für die Konsolidierung und für den Abruf von Erinnerungen auf Basis der Ähnlichkeitssuche infrage kommen. Wenn diese Konfiguration nicht angegeben ist, verwendet Memory Bank text-embedding-005 als Standardmodell.

Wenn Sie erwarten, dass Nutzerunterhaltungen in anderen Sprachen als Englisch stattfinden, verwenden Sie ein Modell, das mehrere Sprachen unterstützt, z. B. gemini-embedding-2, gemini-embedding-001 oder text-multilingual-embedding-002, um die Abrufqualität zu verbessern.

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

from agentplatform.types import ManagedSemanticMemoryConfigSimilaritySearchConfig as SimilaritySearchConfig

similarity_search_config = SimilaritySearchConfig(
    embedding_model="EMBEDDING_MODEL"
)

Ersetzen Sie Folgendes:

• EMBEDDING_MODEL: Das Google-Texteinbettungsmodell, das für die Ähnlichkeitssuche verwendet werden soll, im Format projects/{project}/locations/{location}/publishers/google/models/{model}.

Generierungskonfiguration

Die Generierungskonfiguration steuert, welches LLM zum Generieren von gemerkten Informationen verwendet wird, einschließlich des Extrahierens von gemerkten Informationen und des Konsolidierens neuer gemerkter Informationen mit vorhandenen.

Ab dem 29. Juni 2026 verwendet Memory Bank gemini-3.5-flash als Standardmodell. Instanzen, die vor diesem Datum erstellt wurden, verwenden gemini-2.5-flash.

Für neue Memory Bank-Instanzen, die das Standardmodell verwenden:

• Memory Bank-Instanzen in der multiregionalen us- oder in den einzelnen us-*-Regionen (z. B. us-central1) verwenden den multiregionalen us-Gemini 3.5-Endpunkt.
• Memory Bank-Instanzen in der multiregionalen eu- oder in den einzelnen eu-*-Regionen (z. B. europe-west2) verwenden den multiregionalen eu-Gemini 3.5-Endpunkt.
• In allen anderen Memory Bank-Regionen wird der globale Gemini 3.5-Endpunkt verwendet.

Für Memory Bank-Instanzen, die vor dem 29. Juni 2026 mit dem Standardmodell erstellt wurden, verwendet Memory Bank den Gemini-Endpunkt global für Regionen, in denen kein regionaler Gemini 2.5-Endpunkt verfügbar ist.

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

from agentplatform.types import ManagedSemanticMemoryConfigGenerationConfig as GenerationConfig

generation_config = GenerationConfig(
  model="LLM_MODEL"
)

Ersetzen Sie Folgendes:

• LLM_MODEL: Das Google-LLM, das zum Extrahieren und Konsolidieren von gemerkten Informationen verwendet werden soll, im Format projects/{project}/locations/{location}/publishers/google/models/{model}.

Konfiguration der Gültigkeitsdauer (TTL)

Die TTL-Konfiguration steuert, wie die Memory Bank die Ablaufzeit von gemerkten Informationen dynamisch festlegen soll. Nach Ablauf der Ablaufzeit können gemerkte Informationen nicht mehr abgerufen werden und werden gelöscht.

Wenn die Konfiguration nicht angegeben ist, wird die Ablaufzeit für erstellte oder aktualisierte gemerkte Informationen nicht dynamisch festgelegt. Gemerkte Informationen laufen dann nur ab, wenn ihre Ablaufzeit manuell festgelegt wird.

Für die TTL-Konfiguration gibt es zwei Optionen:

• Standard-TTL: Die TTL wird auf alle Vorgänge angewendet, bei denen eine gemerkte Information erstellt oder aktualisiert wird, einschließlich UpdateMemory, CreateMemory und GenerateMemories.

  Wörterbuch

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

  Klassenbasiert

  from agentplatform.types import ManagedSemanticMemoryConfigTtlConfig as TtlConfig
  
  ttl_config = TtlConfig(
      default_ttl=f"TTLs"
  )
  

  Ersetzen Sie Folgendes:

  • TTL: Die Dauer in Sekunden für die TTL. Bei aktualisierten gemerkten Informationen überschreibt die neu berechnete Ablaufzeit (jetzt + TTL) die vorherige Ablaufzeit der gemerkten Informationen.

• Granulare (vorgangsspezifische) TTL: Die TTL wird basierend auf dem Vorgang berechnet, mit dem die gemerkte Information erstellt oder aktualisiert wurde. Wenn sie für einen bestimmten Vorgang nicht festgelegt ist, wird die Ablaufzeit des Speichers durch den Vorgang nicht aktualisiert.

  Wörterbuch

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

  Klassenbasiert

  from agentplatform.types import ManagedSemanticMemoryConfigTtlConfig as TtlConfig
  from agentplatform.types import ManagedSemanticMemoryConfigTtlConfigGranularTtlConfig as GranularTtlConfig
  
  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",
      )
  )
  

  Ersetzen Sie Folgendes:

  • CREATE_TTL: Die Dauer der TTL in Sekunden für gemerkte Informationen, die mit CreateMemory erstellt wurden.
  • GENERATE_CREATED_TTL: Die Dauer in Sekunden für die TTL für gemerkte Informationen, die mit GenerateMemories erstellt wurden.
  • GENERATE_UPDATED_TTL: Die Dauer in Sekunden für die TTL für gemerkte Informationen, die mit GenerateMemories aktualisiert wurden. Die neu berechnete Ablaufzeit (jetzt + TTL) überschreibt die vorherige Ablaufzeit der gemerkten Information.

Nächste Schritte