Agent Platform Memory Bank einrichten

Wenn Sie die Agent Platform Memory Bank verwenden möchten, müssen Sie zuerst eine Gemini Enterprise Agent Platform-Instanz erstellen und konfigurieren. Diese Instanz verwaltet Ihre Erinnerungen und kann in verschiedenen Runtimes in Ihre Agents integriert werden.

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

Jetzt starten

Bevor Sie mit Memory Bank arbeiten können, 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:

Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

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

Erforderliche Rollen 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:

Alle: Agent Platform-Nutzer (roles/aiplatform.user)

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 stellen, der in Google Kubernetes Engine oder Cloud Run bereitgestellt wird, muss Ihr Dienstkonto die erforderlichen Berechtigungen haben. Der Reasoning Engine-Dienst-Agent hat bereits die erforderlichen Berechtigungen zum Lesen und Schreiben von Erinnerungen. Ausgehende Anfragen von Agent Runtime sollten also bereits die Berechtigung für den Zugriff auf 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 verwenden (z. B. Colab).

Installieren Sie das Agent Platform SDK:

pip install google-cloud-aiplatform>=1.111.0

Authentifizierung

Folgen Sie der Anleitung unter Authentifizierung bei Vertex AI.

Agent Platform SDK-Client einrichten

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

Agent Platform SDK

import vertexai

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

Dabei gilt:

PROJECT_ID ist die Google Cloud Projekt-ID, unter der Sie Agents entwickeln und bereitstellen.
LOCATION ist eine der unterstützten Regionen für Memory Bank.

Agent Platform-Instanz erstellen oder aktualisieren

Wenn Sie Memory Bank verwenden möchten, benötigen Sie zuerst eine Agent Platform-Instanz. Wenn Sie noch keine Instanz haben, können Sie sie mit der Standardkonfiguration erstellen:

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)

Wenn Sie die Konfiguration des Verhaltens Ihrer neuen oder vorhandenen Memory Bank-Instanz anpassen möchten, lesen Sie den Abschnitt Agent Platform-Instanz für Memory Bank konfigurieren. Sie können beispielsweise festlegen, welche Informationen Memory Bank als wichtig einstuft und speichern soll.

Ihre Agent Platform-Instanz unterstützt Sitzungen und Memory Bank sofort. Beim Erstellen der Instanz wird kein Agent bereitgestellt. Wenn Sie die Agent Runtime verwenden möchten, müssen Sie den Agenten angeben, der beim Erstellen oder Aktualisieren Ihrer Agent Platform-Instanz bereitgestellt werden soll.

Sobald Sie eine Agent Platform-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.agent_engines.memories.generate(
  # `name` should have the format `projects/.../locations/.../reasoningEngines/...`.
  name=agent_engine.api_resource.name,
  ...
)

Mit der Laufzeit für KI-Agenten verwenden

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

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

AdkApp

Wenn Sie die Vorlage für das Agent Development Kit für die Agent Platform verwenden, nutzt der Agent standardmäßig VertexAiMemoryBankService, wenn er auf der Agent Platform bereitgestellt wird. Das bedeutet, dass die ADK Memory-Tools Erinnerungen aus Memory Bank lesen.

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

Ersetzen Sie Folgendes:

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

Weitere Informationen zur Verwendung von Memory Bank mit dem ADK finden Sie in der Kurzanleitung für das Agent Development Kit.

Benutzerdefinierter KI-Agent

Sie können Memory Bank mit Ihrem benutzerdefinierten Agenten verwenden, der in der Agent Runtime bereitgestellt wird. In diesem Fall sollte Ihr Agent Aufrufe an Memory Bank orchestrieren, um Erinnerungsgenerierungs- und Erinnerungsabruf-Aufrufe 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 Standarddienst-Agent für Ihren Agent in der Agent Runtime verwenden, hat Ihr Agent bereits die Berechtigung, Erinnerungen zu lesen und zu schreiben. Wenn Sie ein Kundenservicekonto verwenden, müssen Sie Ihrem Dienstkonto Berechtigungen zum Lesen und Schreiben von Erinnerungen erteilen. Die erforderlichen Berechtigungen hängen davon ab, welche Vorgänge Ihr KI-Agent ausführen 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 Agent Runtime, ohne einen Agent anzugeben. Wenn Sie keine Konfiguration angeben, wird Memory Bank mit den Standardeinstellungen für die Verwaltung der Generierung und des Abrufs von Erinnerungen erstellt.

agent_engine = client.agent_engines.create()

Wenn Sie die Agent Platform schon einmal verwendet haben, sollte das Erstellen einer neuen Agent Platform-Instanz ohne Laufzeit nur wenige Sekunden dauern. Wenn Sie die Agent Platform 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

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

Aktualisieren

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

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

Ersetzen Sie Folgendes:

RUNTIME_NAME: Der Name der Agent-Laufzeit. Er sollte das Format projects/.../locations/.../reasoningEngines/... haben. Hier finden Sie eine Liste der unterstützten Regionen für Memory Bank.

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, gewähren Sie der Identität des Cloud Run-Dienstes Berechtigungen zum Lesen und Schreiben von Erinnerungen. Die erforderlichen Berechtigungen hängen davon ab, welche Vorgänge Ihr Agent ausführen soll. Wenn Ihr Agent nur Erinnerungen abrufen und generieren soll, reichen aiplatform.memories.generate und aiplatform.memories.retrieve aus.

Agent Platform-Instanz für Memory Bank 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 Einstellungen für Memory Bank für Ihre Instanz konfigurieren:

Konfiguration der Anpassung: Hier wird konfiguriert, wie Erinnerungen aus Quelldaten extrahiert und mit vorhandenen Erinnerungen zusammengeführt werden.
Konfiguration für die Ähnlichkeitssuche: Gibt an, welches Einbettungsmodell Memory Bank für die Ähnlichkeitssuche verwendet. Die Standardeinstellung ist text-embedding-005.
Konfiguration der Generierung: Hier wird konfiguriert, welche LLM-Memory Bank für das Merken von Informationen verwendet wird. Die Standardeinstellung ist gemini-2.5-flash.
TTL-Konfiguration: Hier wird konfiguriert, wie die TTL für erstellte oder aktualisierte gemerkte Informationen automatisch festgelegt wird. Standardmäßig ist keine TTL festgelegt.

Das folgende Beispiel zeigt die Standard-Memory Bank:

Wörterbuch

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
}

Klassenbasiert

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
)

Sie können die Konfiguration der Memory Bank anpassen, wenn Sie Ihre Agent Platform-Instanz erstellen oder aktualisieren. Im folgenden Beispiel wird gezeigt, wie Sie eine Instanz mit einer bestimmten Memory Bank-Konfiguration erstellen oder aktualisieren.

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

Konfiguration der Anpassung des Informationsspeichers in natürlicher Sprache

Wenn Sie anpassen möchten, wie Memory Bank Erinnerungen in natürlicher Sprache extrahiert, konfigurieren Sie das Extraktionsverhalten beim Einrichten Ihrer Instanz. Mit den folgenden Optionen können Sie das Verhalten anpassen:

Themen für den Arbeitsspeicher 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 Erinnerungen in die Memory Bank.
Erinnerungen konfigurieren: Sie können festlegen, ob Erinnerungen in der ersten Person (Standard) oder in der dritten Person generiert werden sollen.
Konsolidierung konfigurieren: Konfigurieren Sie, wie viele Speicherrevisionen Memory Bank bei der Konsolidierung der einzelnen Speicherkandidaten berücksichtigt.

Die Anpassung des Extraktionsverhaltens der Memory Bank lässt sich in zwei Schritten beschreiben: „Sagen“ und „Zeigen“. Mit Memory-Themen wird der Memory Bank mitgeteilt, welche Informationen gespeichert werden sollen. Few-Shots zeigen Memory Bank, welche Art von Informationen zu einem bestimmten Memory führen soll. So kann sie die Muster, Nuancen und Formulierungen lernen, die Sie von ihr erwarten.

Optional können Sie unterschiedliches Verhalten für verschiedene Umfangsebenen 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, das für alle Gruppen von Bereichsschlüsseln gilt, indem Sie das Feld scope_key weglassen. Diese Konfiguration gilt für alle Anfragen, für die keine Konfiguration vorhanden ist, die genau mit den Bereichsschlüsseln für eine andere Anpassungskonfiguration übereinstimmt.

Beispiel: Die user_level_config würde nur für GenerateMemories-Anfragen gelten, bei denen genau der Bereichsschlüssel user_id verwendet wird (d.h. scope={"user_id": "123"} ohne zusätzliche Schlüssel). default_config würde für andere Anfragen gelten:

Wörterbuch


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

Klassenbasiert

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig

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

Speicherthemen konfigurieren

„Memory-Themen“ geben an, welche Informationen Memory Bank als sinnvoll erachtet und daher als generierte Erinnerungen gespeichert werden sollten. Memory Bank unterstützt zwei Arten von Memory-Themen:

Verwaltete Themen: Label und Anleitung 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 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
    )
)
```
Die folgenden verwalteten Themen werden von Memory Bank unterstützt:
- Nutzerinformationen (USER_PERSONAL_INFO): Wichtige Informationen zum Nutzer, z. B. Namen, Beziehungen, Hobbys und wichtige Termine. Beispiele: „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 sitze lieber in der Mitte.“
- Wichtige Unterhaltungsereignisse und Aufgabenergebnisse (KEY_CONVERSATION_DETAILS): Wichtige Meilensteine oder Schlussfolgerungen im Dialog. Beispiel: „Ich habe Flugtickets für einen Hin- und Rückflug zwischen JFK und SFO gebucht. Ich reise am 1. Juni 2025 ab und kehre am 7. Juni 2025 zurück.“
- Explizite Anweisungen zum Merken / Vergessen (EXPLICIT_INSTRUCTIONS): Informationen, die der Nutzer explizit vom Agenten anfordert, sich zu merken oder zu vergessen. Wenn der Nutzer beispielsweise sagt: „Denk daran, dass ich hauptsächlich Python verwende“, generiert Memory Bank einen Eintrag 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 der 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 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."""
  )
)

Wenn Sie benutzerdefinierte Themen verwenden, sollten Sie auch Few-Shot-Beispiele angeben, die zeigen, wie Erinnerungen aus Ihrem Gespräch extrahiert werden sollen.

Sie können eine beliebige Kombination von Erinnerungsthemen verwenden. Sie können beispielsweise eine Teilmenge der verfügbaren Themen für verwalteten Speicher verwenden:

Wörterbuch

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

Klassenbasiert

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

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

Klassenbasiert

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

Few-Shot-Beispiele

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

Wir empfehlen, immer Few-Shots mit benutzerdefinierten Themen zu verwenden, damit die Memory Bank das gewünschte Verhalten lernen kann. Few-Shots sind optional, wenn Sie verwaltete Themen verwenden, da Memory Bank Beispiele für jedes Thema definiert. 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 Kundenmitteilungen 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."
      }
    ]
}

Klassenbasiert

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

Sie können auch Beispiele für Unterhaltungen angeben, die nicht zu generierten Erinnerungen führen sollen, indem Sie eine leere Liste für die erwartete Ausgabe angeben (generated_memories):

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

Klassenbasiert

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=[]
)

Arbeitsspeicherperspektive

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

Wörterbuch

customization_config = {
  "enable_third_person_memories": True
}

Klassenbasiert

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig

customization_config = CustomizationConfig(
    enable_third_person_memories=True
)

Konsolidierung anpassen

Bei der Konsolidierung legt Memory Bank fest, wie neu erworbene Informationen in Ihren vorhandenen Speicher integriert werden. Memory Bank prüft, ob neue Erinnerungen HINZUGEFÜGT, vorhandene Erinnerungen mit zusätzlichem Kontext AKTUALISIERT oder veraltete Erinnerungen 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 Memory Bank neue Informationen nur mit dem letzten Snapshot des Gedächtnisses eines Kandidaten (einer Gedächtnisrevision). 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 jedes „Kandidatenspeichers“ (des spezifischen Datensatzes, der auf eine Aktualisierung geprüft wird) Memory Bank bei der Konsolidierung berücksichtigt.

Wörterbuch

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

Klassenbasiert

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

Wenn Sie revisions_per_candidate_count erhöhen, 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 der Konsolidierung.

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 den auf der Ähnlichkeitssuche basierenden Abruf von Erinnerungen infrage kommen. Wenn diese Konfiguration nicht angegeben wird, 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-001 oder text-multilingual-embedding-002, um die Qualität des Abrufs zu verbessern.

Wörterbuch

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

Klassenbasiert

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

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

Mit der Generierungskonfiguration wird gesteuert, 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.

Memory Bank verwendet gemini-2.5-flash als Standardmodell. Für Regionen, in denen regionale Gemini-Verfügbarkeit nicht gegeben ist, wird der globale Endpunkt verwendet.

Wörterbuch

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

Klassenbasiert

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

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

Ersetzen Sie Folgendes:

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

Konfiguration der Gültigkeitsdauer (TTL)

Mit der TTL-Konfiguration wird gesteuert, wie Memory Bank die Ablaufzeit von Erinnerungen dynamisch festlegen soll. Nach Ablauf der Gültigkeitsdauer können Erinnerungen nicht mehr abgerufen werden und werden gelöscht.

Wenn die Konfiguration nicht angegeben wird, wird die Ablaufzeit für erstellte oder aktualisierte Erinnerungen nicht dynamisch festgelegt. Erinnerungen laufen also nur ab, wenn ihre Ablaufzeit manuell festgelegt wird.

Es gibt zwei Optionen für die TTL-Konfiguration:

Standard-TTL: Die TTL wird auf alle Vorgänge angewendet, bei denen ein Speicher erstellt oder aktualisiert wird, einschließlich UpdateMemory, CreateMemory und GenerateMemories.
Wörterbuch
```
memory_bank_config = {
  "ttl_config": {
      "default_ttl": f"TTLs"
  }
}
```
Klassenbasiert
```
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"
  )
)
```
Ersetzen Sie Folgendes:
- TTL: Die Dauer in Sekunden für die TTL. Bei aktualisierten gemerkten Informationen wird die neu berechnete Ablaufzeit (jetzt + TTL) die vorherige Ablaufzeit der gemerkten Information überschreiben.

Granulare TTL (pro Vorgang): Die TTL wird basierend darauf berechnet, durch welchen Vorgang die Memory 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

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

Klassenbasiert

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

Ersetzen Sie Folgendes:

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

Nächste Schritte

Kurzanleitung

Kurzanleitung für die Memory Bank API

Erste Schritte mit der Memory Bank API zum Verwalten von langfristigen Erinnerungen

Kurzanleitung

Schnellstart mit dem Agent Development Kit

Erste Schritte mit dem Agent Development Kit (ADK)

Agent Platform Memory Bank einrichten Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Jetzt starten

Projekt in Google Cloud einrichten

Erforderliche Rollen abrufen

Bibliotheken installieren

Authentifizierung

Agent Platform SDK-Client einrichten

Agent Platform SDK

Agent Platform-Instanz erstellen oder aktualisieren

Mit der Laufzeit für KI-Agenten verwenden

AdkApp

Benutzerdefinierter KI-Agent

In allen anderen Laufzeiten verwenden

Erstellen

Aktualisieren

Agent Platform-Instanz für Memory Bank konfigurieren

Wörterbuch

Klassenbasiert

Konfiguration der Anpassung des Informationsspeichers in natürlicher Sprache

Wörterbuch

Klassenbasiert

Speicherthemen konfigurieren

Wörterbuch

Klassenbasiert

Wörterbuch

Klassenbasiert

Wörterbuch

Klassenbasiert

Wörterbuch

Klassenbasiert

Few-Shot-Beispiele

Wörterbuch

Klassenbasiert

Wörterbuch

Klassenbasiert

Arbeitsspeicherperspektive

Wörterbuch

Klassenbasiert

Konsolidierung anpassen

Wörterbuch

Klassenbasiert

Konfiguration der Ähnlichkeitssuche

Wörterbuch

Klassenbasiert

Generierungskonfiguration

Wörterbuch

Klassenbasiert

Konfiguration der Gültigkeitsdauer (TTL)

Wörterbuch

Klassenbasiert

Wörterbuch

Klassenbasiert

Nächste Schritte

Kurzanleitung für die Memory Bank API

Schnellstart mit dem Agent Development Kit

Agent Platform Memory Bank einrichten