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 Agenten eingebunden werden.

In diesem Dokument wird beschrieben, wie Sie Ihr Google Cloud -Projekt einrichten, die erforderlichen Bibliotheken installieren und eine Memory Bank-Instanz in der Google Cloud Console oder mit dem Agent Platform SDK erstellen oder konfigurieren.

Jetzt starten

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

Projekt in Google Cloud 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 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

  2. Verify that billing is enabled for your Google Cloud 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:

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 die Memory Bank von einem Agenten senden, der in Google Kubernetes Engine (GKE) oder Cloud Run bereitgestellt wurde, muss Ihr Dienstkonto die erforderlichen Berechtigungen zum Lesen, Schreiben oder Generieren von gemerkten Informationen haben. Der Reasoning Engine-Dienst-Agent hat bereits die erforderlichen Berechtigungen zum Lesen, Schreiben und Generieren von gemerkten Informationen. Ausgehende Anfragen von Agent Runtime sollten daher bereits Zugriff auf die Memory Bank haben.

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:

Agent Platform SDK

import agentplatform

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

Dabei gilt:

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.

Informationen zum Koppeln einer multiregionalen Instanz mit einer regionalen ADK-Laufzeit finden Sie unter Multiregionale Memory Bank mit einer regionalen Laufzeit verwenden.

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 in der Google Cloud Console oder mit dem Agent Platform SDK erstellen.

Console

Eigenständige Memory Bank-Instanzen werden in der Google Cloud Console auf der Seite Memory Bank angezeigt. Bereitgestellte Agenten werden auf der Seite Bereitstellungen angezeigt.

  1. Rufen Sie in der Google Cloud Console die Seite Memory Bank der Agent Platform auf.

    Zu Memory Bank

  2. Klicken Sie auf Memory Bank erstellen.

  3. Geben Sie einen Anzeigenamen ein, wählen Sie eine Region aus und geben Sie optional eine Beschreibung ein.

  4. Wählen Sie eine Verschlüsselungsoption aus ( Google-owned and Google-managed encryption key oder einen Cloud Key Management Service-Schlüssel). Sie können die Region oder die Verschlüsselungseinstellungen nach dem Erstellen der Instanz nicht mehr ändern.

  5. Klicken Sie auf Erstellen. Die Agent Platform erstellt Ihre Memory Bank-Instanz mit den Standardeinstellungen für den Speicher und öffnet den Tab Konfiguration.

  6. Optional: Klicken Sie in der Aktionsleiste auf Mit einem Agenten verknüpfen, um Installationsbefehle und Python-Code aufzurufen, die bereits mit Ihrem Projekt, Ihrer Region und Ihrer Memory Bank-ID vorausgefüllt sind. Diese Informationen finden Sie auf den Tabs Mit ADK verwenden (für das Agent Development Kit (ADK)) und Abrufen.

Wenn Sie grundlegende Informationen bearbeiten, Labels bearbeiten oder eine vorhandene eigenständige Instanz aus der Liste Memory Bank löschen möchten, klicken Sie auf das Menü Weitere Aktionen () für die Instanz und wählen Sie Grundlegende Informationen bearbeiten, Labels bearbeiten oder Löschen aus.

Agent Platform SDK

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

# Optionally, print out the Memory Bank resource name. You need the
# resource name to interact with your Memory Bank instance later.
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 festlegen, welche Informationen Memory Bank als sinnvoll erachtet, um sie zu speichern.

Sobald Sie eine Memory Bank-Instanz haben, können Sie den Namen der Instanz verwenden, um gemerkte Informationen 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 in jeder Laufzeit verwendet werden. Sie können Memory Bank aber auch mit Agent Runtime verwenden, um gemerkte Informationen aus Ihrem bereitgestellten Agenten zu lesen und zu schreiben.

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

AdkApp

Wenn Sie die Agent Platform ADK-Vorlage verwenden, nutzt der Agent standardmäßig die VertexAiMemoryBankService, wenn er in der Agent Runtime bereitgestellt wird. Das bedeutet, dass die ADK-Memory-Tools gemerkte Informationen aus der Memory Bank lesen.

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

Ersetzen Sie Folgendes:

  • STAGING_BUCKET: Ihr Cloud Storage-Bucket, der für das Staging Ihrer Agent Runtime verwendet werden soll.

Wenn Sie Memory Bank mit dem ADK ausprobieren möchten, lesen Sie die Kurzanleitung für das ADK. Informationen zum Auswählen von Memory-Tools, Callbacks und Laufzeiten finden Sie unter Memory Bank mit dem ADK verwenden.

Benutzerdefinierter KI-Agent

Sie können Memory Bank mit Ihrem benutzerdefinierten KI-Agenten verwenden, der in Agent Runtime bereitgestellt wird. In diesem Fall sollte Ihr KI-Agent Aufrufe an Memory Bank orchestrieren, um Aufrufe zum Merken von Informationen und zum Abrufen von gemerkten Informationen auszulösen.

Ihre in der 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 Agent ausführen können soll. Wenn Ihr Agent nur gemerkte Informationen abrufen und generieren soll, reichen aiplatform.memories.generate und aiplatform.memories.retrieve aus.

In der Google Cloud Console können Sie die Memory Bank-Einstellungen für einen bereitgestellten Agenten auf der Seite Bereitstellungen aufrufen und bearbeiten. Öffnen Sie dazu den Agenten und klicken Sie auf Dienstkonfiguration > Memory Bank.

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 die 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:

Erstellen

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

Aktualisieren

Wenn Sie die Konfiguration Ihrer Memory Bank ändern möchten, können Sie Ihre Memory Bank-Instanz aktualisieren.

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

Ersetzen Sie Folgendes:

  • MEMORY_BANK_NAME: Der Name der Memory Bank. Er sollte das Format projects/.../locations/.../reasoningEngines/... haben. Sehen Sie sich die unterstützten Regionen für Memory Bank an.

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

Memory Bank-Instanz konfigurieren

Sie können Ihre Memory Bank-Instanz in derGoogle Cloud Console oder mit dem Agent Platform SDK konfigurieren, um anzupassen, wie gemerkte Informationen generiert und verwaltet werden. Wenn Sie keine Konfiguration angeben, verwendet Memory Bank die Standardeinstellungen für jede Konfigurationsoption.

In der Google Cloud Console konfigurieren

So rufen Sie die Memory Bank-Einstellungen in derGoogle Cloud Console auf oder bearbeiten sie (zum Bearbeiten ist aiplatform.reasoningEngines.update erforderlich):

  1. Öffnen Sie die Konfigurationsansicht Ihrer Instanz:
    • Eigenständige Memory Bank-Instanz: Rufen Sie die Seite Memory Bank auf, klicken Sie auf Ihre Instanz und öffnen Sie den Tab Konfiguration.
    • In Agent Runtime bereitgestellter Agent: Rufen Sie die Seite Bereitstellungen auf, klicken Sie auf Ihren Agenten und dann auf Dienstkonfiguration > Memory Bank.
  2. Klicken Sie in einem der folgenden Abschnitte auf Bearbeiten, um die Einstellungen zu aktualisieren, und klicken Sie dann auf Speichern:
    • Details (eigenständige Instanzen): Bearbeiten Sie den Anzeigenamen und die Beschreibung. Region, Verschlüsselung und Labels haben in diesem Bereich Lesezugriff.
    • Generierung: Aktivieren oder deaktivieren Sie die Merken-Extraktion, wählen Sie die Ich- oder die Er-/Sie-Perspektive aus und konfigurieren Sie verwaltete oder benutzerdefinierte Themen für gemerkte Informationen (in der Console werden Überschreibungen auf Bereichsebene schreibgeschützt angezeigt).
    • Abruf: Wählen Sie das Einbettungsmodell für die Ähnlichkeitssuche aus. Sie können das Einbettungsmodell nur ändern, bevor Sie die erste gemerkte Information in der Memory Bank-Instanz speichern.
    • Aufbewahrung: Konfigurieren Sie den Ablauf gemerkter Informationen (TTL) und die Aufbewahrung des Versionsverlaufs gemerkter Informationen.
  3. Optional: Wenn Sie Schemas für strukturierte Speicherprofile auf einer eigenständigen Instanz hinzufügen oder bearbeiten möchten, klicken Sie in der Aktionsleiste (oder im Abschnitt Generierung) auf Schemas. Weitere Informationen finden Sie unter Speicherprofile.

Mit dem Agent Platform SDK konfigurieren

Sie können die folgenden Memory Bank-Einstellungen für Ihre Instanz mit dem Agent Platform SDK 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: 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:

Wörterbuch

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
}

Kursbasiert

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 Speicherbankkonfiguration beim Erstellen oder Aktualisieren Ihrer Instanz anpassen. Im folgenden Beispiel wird gezeigt, wie Sie eine Instanz mit einer bestimmten Speicherbankkonfiguration erstellen.

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

Konfiguration der Anpassung von gemerkten Informationen 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:

Das Anpassen des Extraktionsverhaltens Ihrer Memory Bank erfolgt in zwei Schritten: Erklären und Zeigen. Themen für gemerkte Informationen teilen Memory Bank mit, welche Informationen gespeichert werden sollen. Few-Shots zeigen Memory Bank, welche Art von Informationen zu einer bestimmten gemerkten Information führen soll. So lernt Memory Bank die Muster, Nuancen und Formulierungen, die es verstehen soll.

Optional können Sie für verschiedene Bereichsebenen ein unterschiedliches Verhalten konfigurieren. Themen, die für gemerkte Informationen auf Sitzungsebene relevant sind, sind beispielsweise möglicherweise nicht für gemerkte Informationen auf Nutzerebene (über mehrere Sitzungen hinweg) relevant. Wenn Sie das Verhalten für eine bestimmte Teilmenge von gemerkten Informationen 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 ein Standardverhalten konfigurieren (das für alle Sätze von Bereichsschlüsseln gilt), 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.

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

Wörterbuch


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

Kursbasiert

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

„Memory-Themen“ geben an, welche Informationen von Memory Bank als relevant erachtet und daher als generierte gemerkte Informationen gespeichert werden sollten. Memory Bank unterstützt zwei Arten von 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"
      }
    }
    

    Kursbasiert

    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“.
    • Nutzereinstellungen (USER_PREFERENCES): Angegebene oder implizierte Vorlieben, Abneigungen, bevorzugte Stile oder Muster. Beispiel: „Ich bevorzuge den mittleren Sitz.“
    • Wichtige Gesprächsereignisse und Aufgabenergebnisse (KEY_CONVERSATION_DETAILS): Wichtige Meilensteine oder Schlussfolgerungen im Dialog. Beispiel: „Ich habe Hin- und Rückflugtickets zwischen JFK und SFO gebucht. Ich reise am 1. Juni 2025 ab und kehre am 7. Juni 2025 zurück.“
    • Explizite Anweisungen zum Speichern oder Vergessen (EXPLICIT_INSTRUCTIONS): Informationen, die der Nutzer den Agenten explizit auffordert, zu speichern oder zu vergessen. Wenn der Nutzer beispielsweise sagt „Merk dir, dass ich hauptsächlich Python verwende“, generiert die Memory Bank eine gemerkte Information wie „Ich verwende hauptsächlich Python“.
  • Benutzerdefinierte Themen: Label und Anweisungen werden von Ihnen beim Einrichten 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."""
        }
    }
    

    Kursbasiert

    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.

Mit Anpassung können Sie beliebige Kombinationen von Memory-Themen verwenden. Sie können beispielsweise eine Teilmenge der verfügbaren Themen für gemerkte Informationen verwenden:

Wörterbuch

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

Kursbasiert

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):

Wörterbuch

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

Kursbasiert

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 der Memory Bank das erwartete Verhalten bei der Extraktion von gemerkten Informationen demonstrieren. Sie können beispielsweise eine Beispielunterhaltung und die gemerkten Informationen 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 bei der Verwendung verwalteter Themen optional, da die Memory Bank Beispiele für jedes Thema definiert. Demonstrieren Sie Unterhaltungen, die voraussichtlich nicht zu gemerkten Informationen 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:

Wörterbuch

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

Kursbasiert

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 gemerkten Informationen führen sollen. Geben Sie dazu eine leere Liste für die erwartete Ausgabe (generated_memories) an:

Wörterbuch

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": []
}

Kursbasiert

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 gemerkte Informationen in der ersten Person generiert (z.B. „Ich verwende Memory Bank für die Speicherverwaltung.“). 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“).

Wörterbuch

customization_config = {
  "enable_third_person_memories": True
}

Kursbasiert

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 erfasste 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 sicherzustellen, dass die Erinnerungen von hoher Qualität und bestätigt sind, kann die Memory Bank optional den Verlauf einer Erinnerung analysieren, um langfristige Trends von einmaligen Ausreißern zu unterscheiden.

Standardmäßig vergleicht Memory Bank neue Informationen nur mit dem neuesten Snapshot einer gemerkten Information (einer „Memory-Revision“). Wenn Sie die Tiefe dieser Analyse erhöhen möchten, konfigurieren Sie den Parameter revisions_per_candidate_count. Dieser Parameter definiert, wie viele vorherige Versionen der einzelnen „Kandidaten für gemerkte Informationen“ (der spezifische Datensatz, der für eine Aktualisierung ausgewertet wird) von der Memory Bank bei der Konsolidierung berücksichtigt werden.

Wörterbuch

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

Kursbasiert

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 Sie revisions_per_candidate_count erhöhen, erhalten Sie konsistentere und besser bestätigte Erinnerungen, da die Wiederholung von 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:

Wörterbuch

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

Kursbasiert

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 gemerkten Informationen für die Konsolidierung und für den Abruf von gemerkten Informationen auf Basis der Ähnlichkeitssuche infrage kommen. Wenn diese Konfiguration nicht angegeben ist, verwendet Memory Bank text-embedding-005 als Standardmodell.

Wenn Sie davon ausgehen, 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.

Wörterbuch

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

Kursbasiert

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 Zusammenführens neuer gemerkter Informationen mit vorhandenen gemerkten Informationen.

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.

Wörterbuch

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

Kursbasiert

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 Gültigkeitsdauer sind die gemerkten Informationen nicht mehr abrufbar und werden gelöscht.

Wenn die Konfiguration nicht angegeben ist, wird die Ablaufzeit für erstellte oder aktualisierte gemerkte Informationen nicht dynamisch festgelegt. Die gemerkten 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 gemerkte Informationen erstellt oder aktualisiert werden, einschließlich UpdateMemory, CreateMemory und GenerateMemories.

    Wörterbuch

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

    Kursbasiert

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

    Ersetzen Sie Folgendes:

    • TTL: Die Dauer der TTL in Sekunden. 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 gemerkten Informationen erstellt oder aktualisiert wurden. Wenn sie für einen bestimmten Vorgang nicht festgelegt ist, wird die Ablaufzeit des gemerkten Inhalts 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"
        }
    }
    

    Kursbasiert

    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 der TTL in Sekunden 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 Informationen.

Nächste Schritte

Kurzanleitung

Erste Schritte mit der Memory Bank API zum Verwalten von gemerkten Informationen im Langzeitspeicher.

Kurzanleitung

ADK-Agenten erstellen, der sich Nutzerpräferenzen merkt