Mit dem Agent Platform SDK können Sie API-Aufrufe direkt an Memory Bank senden. Verwenden Sie das Agent Platform SDK, wenn Sie nicht möchten, dass ein Agent-Framework Aufrufe für Sie orchestriert, oder wenn Sie Memory Bank in andere Agent-Frameworks als das Agent Development Kit (ADK) einbinden möchten.
In diesem Dokument wird beschrieben, wie Sie Erinnerungen mithilfe von API-Aufrufen erstellen, hochladen, abrufen und entfernen.
Eine Kurzanleitung zur Verwendung des ADK finden Sie unter Memory Bank-Kurzanleitung mit ADK.
Hinweis
Wenn Sie dieser Anleitung folgen möchten, sollten Sie zuerst die Schritte unter Für Memory Bank einrichten ausführen. Bevor Sie mit dieser Kurzanleitung beginnen, müssen Sie eine Memory Bank-Instanz und eine Sessions-Instanz erstellen, wie im folgenden Beispiel gezeigt:
import agentplatform
client = agentplatform.Client(
project="PROJECT_ID",
location="LOCATION"
)
memory_bank = client.memory_banks.create()
sessions = client.runtimes.create()
Erinnerungen mit Agent Platform Sessions generieren
Nachdem Sie Agent Platform Sessions eingerichtet haben, können Sie Sitzungen erstellen und Ereignisse anhängen. Anschließend können Sie die Memory Bank verwenden, um gemerkte Informationen aus der Unterhaltung des Nutzers mit dem Agent zu generieren, damit sie für zukünftige Nutzerinteraktionen verfügbar sind. Weitere Informationen finden Sie unter Erinnerungen generieren und Erinnerungen abrufen.
Sitzung mit einer undurchsichtigen Nutzer-ID erstellen Alle Erinnerungen, die aus dieser Sitzung generiert werden, werden automatisch mit dem Bereich
{"user_id": "USER_ID"}verschlüsselt, sofern Sie beim Generieren von Erinnerungen nicht explizit einen Bereich angeben.import agentplatform client = agentplatform.Client( project="PROJECT_ID", location="LOCATION" ) session = client.sessions.create( # The name can be fetched using `sessions.name`. name="SESSIONS_NAME", user_id="USER_ID" )Ersetzen Sie Folgendes:
PROJECT_ID: Ihre Projekt-ID.
LOCATION: Ihre Region. Unterstützte Regionen für Memory Bank
SESSIONS_NAME: Der Name der von Ihnen erstellten Sessions-Instanz oder einer vorhandenen Sessions-Instanz. Der Name muss das folgende Format haben:
projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.USER_ID: Eine Kennung für Ihren Nutzer. Alle Erinnerungen, die aus dieser Sitzung generiert werden, werden automatisch mit dem Bereich
{"user_id": "USER_ID"}verschlüsselt, sofern Sie beim Generieren von Erinnerungen nicht explizit einen Bereich angeben.
Ereignisse iterativ in Ihre Sitzung hochladen Ereignisse können alle Interaktionen zwischen Ihrem Nutzer, dem Agent und den Tools umfassen. Die geordnete Liste der Ereignisse stellt den Unterhaltungsverlauf Ihrer Sitzung dar. Dieser Unterhaltungsverlauf wird als Quellmaterial für das Generieren von Erinnerungen für den jeweiligen Nutzer verwendet.
import datetime client.sessions.events.append( name=session.response.name, author="user", # Required by Sessions. invocation_id="1", # Required by Sessions. timestamp=datetime.datetime.now(tz=datetime.timezone.utc), # Required by Sessions. config={ "content": { "role": "user", "parts": [{"text": "hello"}] } } )Wenn Sie Erinnerungen aus Ihrem Unterhaltungsverlauf generieren möchten, lösen Sie eine Anfrage zum Generieren von Erinnerungen für die Sitzung aus:
client.memory_banks.memories.generate( name=memory_bank.name, vertex_session_source={ # `session` should have the format "projects/.../locations/.../reasoningEngines/.../sessions/...". "session": session.response.name }, # Optional when using Sessions. Defaults to {"user_id": session.user_id}. scope=SCOPE )
Ersetzen Sie Folgendes:
- Optional: SCOPE: Ein Dictionary, das den Umfang der generierten Erinnerungen darstellt. Es enthält maximal 5 Schlüssel/Wert-Paare und keine
*-Zeichen. Beispiel:{"session_id": "MY_SESSION"}Für die Konsolidierung werden nur Erinnerungen mit demselben Umfang berücksichtigt. Wenn nicht angegeben, wird{"user_id": session.user_id}verwendet.
Gemerkte Informationen hochladen
Als Alternative zum Generieren von Erinnerungen aus Rohdialogen können Sie Erinnerungen hochladen oder Ihre Agents sie direkt mit GenerateMemories mit vorab extrahierten Fakten hinzufügen lassen.
Anstatt dass Memory Bank Informationen aus Ihren Inhalten extrahiert, stellen Sie die Fakten, die über Ihren Nutzer gespeichert werden sollen, direkt bereit.
Um die Konsistenz mit generierten Erinnerungen zu gewährleisten, sollten Sie vorab extrahierte Fakten aus derselben Perspektive schreiben, die Sie für den jeweiligen Bereich konfiguriert haben. Standardmäßig werden Erinnerungen in der Ich-Perspektive generiert, z. B. I
am a software engineer.
client.memory_banks.memories.generate(
name=memory_bank.name,
direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
scope=SCOPE
)
Ersetzen Sie Folgendes:
FACT: Die vorab extrahierte Information, die mit vorhandenen Erinnerungen zusammengeführt werden soll. Sie können bis zu fünf vorab extrahierte Fakten in einer Liste wie der folgenden angeben:
{"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}SCOPE: Ein Dictionary, das den Umfang der generierten Erinnerungen darstellt. Beispiel:
{"session_id": "MY_SESSION"}. Für die Konsolidierung werden nur Erinnerungen mit demselben Umfang berücksichtigt.
Alternativ können Sie CreateMemory verwenden, um Erinnerungen hochzuladen, ohne Memory Bank für das Extrahieren oder Konsolidieren von Erinnerungen zu nutzen.
memory = client.memory_banks.memories.create(
name=memory_bank.name,
fact="This is a fact.",
scope={"user_id": "123"}
)
"""
Returns a MemoryOperation containing the created Memory like:
MemoryOperation(
done=True,
metadata={
"@type': 'type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateMemoryOperationMetadata",
"genericMetadata": {
"createTime": '2025-06-26T01:15:29.027360Z',
"updateTime": '2025-06-26T01:15:29.027360Z'
}
},
name="projects/.../locations/us-central1/reasoningEngines/.../memories/.../operations/...",
response=Memory(
create_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC)),
fact="This is a fact.",
name="projects/.../locations/us-central1/reasoningEngines/.../memories/...",
scope={
"user_id": "123"
},
update_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC))
)
)
"""
Gemerktes abrufen und verwenden
Sie können Erinnerungen für Ihren Nutzer abrufen und in Ihre Systemanweisungen einfügen, um dem LLM Zugriff auf Ihren personalisierten Kontext zu gewähren.
Weitere Informationen zum Abrufen von Erinnerungen mit einer bereichsbasierten Methode finden Sie unter Erinnerungen abrufen.
# Retrieve memories for User ID 123.
retrieved_memories = client.memory_banks.memories.retrieve(
name=memory_bank.name,
scope={"user_id": "123"}
).page
Mit jinja können Sie Ihre strukturierten Erinnerungen in einen Prompt umwandeln:
from jinja2 import Template
template = Template("""
<MEMORIES>
Here is some information about the user:
{% for retrieved_memory in data %}* {{ retrieved_memory.memory.fact }}
{% endfor %}</MEMORIES>
""")
prompt = template.render(data=retrieved_memories)
"""
Output:
<MEMORIES>
Here is some information about the user:
* This is a fact
</MEMORIES>
"""
Gemerkte Informationen entfernen
Es gibt mehrere Möglichkeiten, Erinnerungen aus Ihrer Memory Bank-Instanz zu löschen.
Entfernen nach Ressourcenname
Wenn Sie genau wissen, welche Speicherressource Sie entfernen möchten, können Sie einen bestimmten Speicher anhand seines Ressourcennamens löschen:
client.memory_banks.memories.delete(
name=MEMORY_NAME,
config={
# Set to false (default) if you want to delete the memory asynchronously.
"wait_for_completion": True
}
)
Ersetzen Sie Folgendes:
- MEMORY_NAME: Der Name des zu löschenden Memories. Der Name muss das folgende Format haben:
projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}. Sie können den Namen der Erinnerung abrufen.
Nach Kriterien entfernen
Mit dem kriterienbasierten Löschen können Sie eine oder mehrere Erinnerungen entfernen. Es werden nur Erinnerungen gelöscht, die den angegebenen Filtern entsprechen. Sie müssen mindestens einen der folgenden Werte angeben: filter (für Systemfelder) oder filter_groups (für Metadatenfelder).
operation = client.memory_banks.memories.purge(
name=memory_bank.name,
# Specify at least one of `filter` or `filter_groups`.
filter="FILTER_STRING",
filter_groups=FILTER_GROUPS,
# Set to false (default) if you want to stage but not execute the purge operation.
force=True,
config={
# Set to false (default) if you want to purge memories asynchronously.
"wait_for_completion": True
}
)
Ersetzen Sie Folgendes:
- FILTER_STRING: Ein String mit EBNF-Syntax zum Filtern nach Systemfeldern. Systemfelder umfassen
create_time,update_time,factundtopics. Weitere Informationen zum Filtern nach Systemfeldern finden Sie auf der Seite „Erinnerungen abrufen“ im Abschnitt Nach Metadatenfeldern filtern. - FILTER_GROUPS: Eine Liste von Dictionaries oder Objekten zum Filtern von Metadaten für Erinnerungen. Weitere Informationen zum Filtern nach Metadatenfeldern finden Sie auf der Seite „Erinnerungen abrufen“ im Abschnitt Nach Systemfeldern filtern.
Der Vorgang gibt die Anzahl der gelöschten Erinnerungen zurück (bei force=True) oder die Anzahl der Erinnerungen, die gelöscht würden, wenn der Vorgang ausgeführt würde (bei force=False).
print(operation.response.purge_count)
Sie können beispielsweise alle Erinnerungen löschen, die zu einem Bereich für user_id „123“ gehören:
operation = client.memory_banks.memories.purge(
name=memory_bank.name,
filter="scope.user_id=\"123\"",
force=True
)
Nach semantischer Bedeutung entfernen
Während des Merkens von Informationen entscheidet Memory Bank anhand der Inhalte der neu extrahierten Informationen und der vorhandenen gemerkten Informationen, ob gemerkte Informationen erstellt, aktualisiert oder gelöscht werden sollen. Eine gemerkte Information kann gelöscht werden, wenn die neuen Informationen ihr widersprechen oder wenn der extrahierte Inhalt die Memory Bank anweist, ein Thema zu vergessen (im Fall des EXPLICIT_INSTRUCTIONS-Themas).
Mit der folgenden Anfrage werden beispielsweise vorhandene Erinnerungen gelöscht, die Informationen zu Ernährungspräferenzen enthalten, sofern sie für die angegebene scope vorhanden sind:
from google import genai
client.memory_banks.memories.generate(
name=memory_bank.name,
direct_contents_source={
"events": [{
"content": genai.types.Content(
role="user",
parts=[
genai.types.Part.from_text(text="Forget my dietary preferences.")
]
)
}]
},
scope={...}
)
Bereinigen
Wenn Sie alle in diesem Projekt verwendeten Ressourcen bereinigen möchten, können Sie das Google Cloud-Projekt löschen, das Sie für die Kurzanleitung verwendet haben.
Andernfalls können Sie die einzelnen Ressourcen löschen, die Sie in dieser Anleitung erstellt haben. Gehen Sie dazu so vor:
Mit dem folgenden Codebeispiel können Sie die Agent Platform Memory Bank und die Agent-Laufzeit in Gemini Enterprise Agent Platform-Instanzen löschen:
client.memory_banks.delete(name=memory_bank.name, force=True) client.runtimes.delete(name=sessions.name, force=True)Löschen Sie alle lokal erstellten Dateien.
Nächste Schritte
Schnellstart mit dem Agent Development Kit
Erste Schritte mit dem Agent Development Kit (ADK)