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:
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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.
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) -
Gemerkte Informationen lesen, schreiben oder generieren:
Agent Platform Memory Bank User Role (
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 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.1Authentifizierung
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:
PROJECT_IDist die Google Cloud Projekt-ID, unter der Sie Agenten entwickeln und bereitstellen.LOCATIONist eine der unterstützten Regionen für Memory Bank.
Multiregionale und globale Endpunkte
Memory Bank unterstützt multiregionale und globale Endpunkte:
- Legen Sie für globale Instanzen den Standort auf
globalfest. - Legen Sie für multiregionale Instanzen den Standort auf
usodereufest.
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.
Rufen Sie in der Google Cloud Console die Seite Memory Bank der Agent Platform auf.
Klicken Sie auf Memory Bank erstellen.
Geben Sie einen Anzeigenamen ein, wählen Sie eine Region aus und geben Sie optional eine Beschreibung ein.
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.
Klicken Sie auf Erstellen. Die Agent Platform erstellt Ihre Memory Bank-Instanz mit den Standardeinstellungen für den Speicher und öffnet den Tab Konfiguration.
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):
- Ö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.
- 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.
- 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:
- Themen für gemerkte Informationen konfigurieren: Legen Sie fest, welche Art von Informationen die Memory Bank als relevant 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: 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 Speicherversionen die Memory Bank bei der Konsolidierung der einzelnen Speicherkandidaten berücksichtigt.
- Anpassungskonfigurationen anwenden: Wenden Sie Anpassungskonfigurationen mit
unstructured_memory_configsauf Ihre Instanz an.
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“.
- Nutzerinformationen (
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 einzelnenus-*-Regionen (z. B. us-central1) verwenden den multiregionalenus-Gemini 3.5-Endpunkt. - Memory Bank-Instanzen in der multiregionalen
eu- oder in den einzelneneu-*-Regionen (z. B. europe-west2) verwenden den multiregionaleneu-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,CreateMemoryundGenerateMemories.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
CreateMemoryerstellt wurden. - GENERATE_CREATED_TTL: Die Dauer der TTL in Sekunden für gemerkte Informationen, die mit
GenerateMemorieserstellt wurden. - GENERATE_UPDATED_TTL: Die Dauer in Sekunden für die TTL für gemerkte Informationen, die mit
GenerateMemoriesaktualisiert wurden. Die neu berechnete Ablaufzeit (jetzt + TTL) überschreibt die vorherige Ablaufzeit der gemerkten Informationen.
- CREATE_TTL: Die Dauer der TTL in Sekunden für gemerkte Informationen, die mit
Nächste Schritte
Kurzanleitung: Memory Bank API
Erste Schritte mit der Memory Bank API zum Verwalten von gemerkten Informationen im Langzeitspeicher.
Schnellstart mit dem Agent Development Kit
ADK-Agenten erstellen, der sich Nutzerpräferenzen merkt