Kurzanleitung zur Agent Platform Memory Bank API

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 Agenten-Framework Aufrufe für Sie orchestriert, oder wenn Sie Memory Bank in andere Agenten-Frameworks als das Agent Development Kit (ADK) einbinden möchten.

In diesem Dokument wird beschrieben, wie Sie gemerkte Informationen mithilfe von API-Aufrufen erstellen, hochladen, abrufen und entfernen.

Eine Kurzanleitung zur Verwendung des ADK finden Sie unter Kurzanleitung für Memory Bank mit ADK.

Wenn Sie ein Beispiel für die Verwendung von mit dem SDK sehen möchten, führen Sie das Notebook „Erste Schritte mit Memory Bank“ in einer der folgenden Umgebungen aus:

In Colab öffnen | In Colab Enterprise öffnen | In Agent Platform Workbench öffnen | Auf GitHub ansehen

Wenn Sie ein Beispiel für die Verwendung von mit LangGraph sehen möchten, führen Sie das Notebook „Erste Schritte mit – LangGraph“ in einer der folgenden Umgebungen aus:

In Colab öffnen | In Colab Enterprise öffnen | In Agent Platform Workbench öffnen | Auf GitHub ansehen

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

Gemerkte Informationen mit Agent Platform-Sitzungen generieren

Nachdem Sie Agent Platform-Sitzungen eingerichtet haben, können Sie Sitzungen erstellen und Ereignisse an sie anhängen. Anschließend können Sie mit der Memory Bank gemerkte Informationen aus der Unterhaltung des Nutzers mit dem KI-Agenten generieren, damit diese für zukünftige Nutzerinteraktionen verfügbar sind. Weitere Informationen finden Sie unter Erinnerungen generieren und Erinnerungen abrufen.

Hinweis: Sie können den Unterhaltungsverlauf auch direkt in der GenerateMemories-Nutzlast über die direkte Contentquelle angeben.

1. Sitzung mit einer intransparenten Nutzer-ID erstellen. Alle in dieser Sitzung generierten gemerkten Informationen werden automatisch mit dem Bereich {"user_id": "USER_ID"} versehen, sofern Sie beim Generieren von gemerkten Informationen 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. Sehen Sie sich die unterstützten Regionen für Memory Bank an.

   • 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 den Nutzer. Alle in dieser Sitzung generierten gemerkten Informationen werden automatisch mit dem Bereich {"user_id": "USER_ID"} verschlüsselt, sofern Sie beim Generieren von gemerkten Informationen nicht explizit einen Bereich angeben.

2. Laden Sie Ereignisse iterativ in Ihre Sitzung hoch. Ereignisse können alle Interaktionen zwischen Nutzer, Agent und Tools umfassen. Die sortierte Liste der Ereignisse stellt den Unterhaltungsverlauf Ihrer Sitzung dar. Dieser Unterhaltungsverlauf wird als Quellenmaterial verwendet, um gemerkte Informationen für den jeweiligen Nutzer zu generieren.

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

3. Wenn Sie gemerkte Informationen aus Ihrem Unterhaltungsverlauf generieren möchten, lösen Sie eine Anfrage zum Generieren von gemerkten Informationen 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 Wörterbuch, das den Bereich der generierten gemerkten Informationen darstellt, mit maximal 5 Schlüssel/Wert-Paaren und ohne *-Zeichen. Beispiel: {"session_id": "MY_SESSION"} Für die Konsolidierung werden nur gemerkte Informationen mit demselben Bereich berücksichtigt. Wenn nicht angegeben, wird {"user_id": session.user_id} verwendet.

Gemerkte Informationen hochladen

Als Alternative zum Generieren von gemerkten Informationen mithilfe von Rohdialogen können Sie gemerkte Informationen hochladen oder Ihre Agenten sie direkt mit GenerateMemories mit vorab extrahierten Fakten hinzufügen lassen. Anstatt dass die Memory Bank Informationen aus Ihren Inhalten extrahiert, geben Sie die Fakten, die über Ihren Nutzer gespeichert werden sollen, direkt an.

Damit die generierten gemerkten Informationen konsistent sind, 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: Der vorab extrahierte Fakt, der mit vorhandenen gemerkten Informationen zusammengeführt werden soll. Sie können bis zu 5 vorab extrahierte Fakten in einer Liste wie der folgenden angeben:

  {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}
  

• SCOPE: Ein Wörterbuch, das den Umfang der generierten gemerkten Informationen darstellt. Beispiel: {"session_id": "MY_SESSION"}. Für die Konsolidierung werden nur gemerkte Informationen mit demselben Bereich berücksichtigt.

Alternativ können Sie CreateMemory verwenden, um gemerkte Informationen hochzuladen, ohne Memory Bank für die Extraktion oder Konsolidierung von gemerkten Informationen zu verwenden.

Achtung: Mit CreateMemory hochgeladene Memories werden nicht mit vorhandenen Memories zusammengeführt. Es kann also sein, dass Sie für denselben Bereich doppelte Memories haben. Erstellte gemerkte Informationen sind für die Ähnlichkeitssuche verfügbar und können beim Generieren von gemerkten Informationen für zukünftige Anfragen zusammengefasst werden.

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

Gemerkte Informationen abrufen und verwenden

Sie können gemerkte Informationen für Ihren Nutzer abrufen und in Ihre Systemanweisungen aufnehmen, um dem LLM Zugriff auf Ihren personalisierten Kontext zu geben.

Weitere Informationen zum Abrufen von gemerkten Informationen mit einer bereichsbasierten Methode finden Sie unter Gemerkte Informationen 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 gemerkten Informationen 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, je nachdem, wie Sie die zu entfernenden Erinnerungen auswählen möchten.

Nach Ressourcennamen entfernen

Wenn Sie genau wissen, welche gemerkte Information Sie entfernen möchten, können Sie sie anhand ihres 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 der zu löschenden gemerkten Information. 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 des Memory-Eintrags durch Abrufen von Memory-Einträgen ermitteln.

Nach Kriterien entfernen

Sie können ein oder mehrere gemerkte Informationen anhand von Kriterien löschen. Es werden nur gemerkte Informationen gelöscht, die den angegebenen Filtern entsprechen. Sie müssen mindestens filter (auf Systemfelder angewendet) oder filter_groups (auf Metadatenfelder angewendet) angeben.

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. Zu den Systemfeldern gehören create_time, update_time, fact und topics. Weitere Informationen zum Filtern nach Systemfeldern finden Sie im Abschnitt Nach Metadatenfeldern filtern auf der Seite „Gemerkte Informationen abrufen“.
• FILTER_GROUPS: Eine Liste von Wörterbüchern oder Objekten zum Filtern nach Metadaten im gemerkten Informationen. Weitere Informationen zum Filtern nach Metadatenfeldern finden Sie im Abschnitt Nach Systemfeldern filtern auf der Seite „Gemerkte Informationen abrufen“.

Der Vorgang gibt die Anzahl der gelöschten gemerkten Informationen zurück (wenn force=True) oder die Anzahl der gemerkten Informationen, die gelöscht würden, wenn der Vorgang ausgeführt würde (wenn force=False).

print(operation.response.purge_count)

Sie können beispielsweise alle gemerkten Informationen 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

Hinweis: Das erwartete Verhalten kann je nach den von Ihnen konfigurierten Memory-Themen und Few-Shot-Beispielen variieren.

Während der Generierung von gemerkten Informationen entscheidet Memory Bank anhand des Inhalts 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 für gemerkte Informationen).

Mit der folgenden Anfrage würden beispielsweise vorhandene gemerkte Informationen gelöscht, die Informationen zu Ernährungsvorlieben 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, die Sie in dieser Anleitung erstellt haben, so löschen:

1. Verwenden Sie das folgende Codebeispiel, um die Agent Platform Memory Bank und die Agent Runtime auf Gemini Enterprise Agent Platform-Instanzen zu löschen:

   client.memory_banks.delete(name=memory_bank.name, force=True)
   client.runtimes.delete(name=sessions.name, force=True)
   

2. Löschen Sie alle lokal erstellten Dateien.

Nächste Schritte

Kurzanleitung

Schnellstart mit dem Agent Development Kit

Erste Schritte mit dem Agent Development Kit (ADK)