Kurzanleitung für die Agent Platform Memory Bank API

Mit der Agent Platform Memory Bank können Sie API-Aufrufe mit dem Agent Platform SDK direkt an Sessions und Memory Bank senden. Verwenden Sie das Agent Platform SDK, wenn Sie nicht möchten, dass ein Agent-Framework Anrufe für Sie orchestriert, oder wenn Sie Sessions und 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-Schnellstart mit ADK.

Hinweis

Wenn Sie dieser Anleitung folgen möchten, sollten Sie zuerst die Schritte unter Für Memory Bank einrichten ausführen.

Erinnerungen mit Agent Platform Sessions erstellen

Nachdem Sie Agent Platform Sessions und Memory Bank eingerichtet haben, können Sie Sitzungen erstellen und Ereignisse daran anhängen. Erinnerungen werden als Fakten aus der Unterhaltung des Nutzers mit dem Agent generiert, damit sie für zukünftige Nutzerinteraktionen verfügbar sind. Weitere Informationen finden Sie unter Erinnerungen generieren und Erinnerungen abrufen.

  1. Erstellen Sie eine Sitzung mit einer undurchsichtigen User-ID. 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 vertexai

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

# This assumes that you already have an Agent Platform instance. If you don't,
# you can create one using `agent_engine = client.agent_engines.create()`.
session = client.agent_engines.sessions.create(
# The name can be fetched using `agent_engine.api_resource.name`.
name="AGENT_ENGINE_NAME",
user_id="USER_ID"
)

    Ersetzen Sie Folgendes:

    • PROJECT_ID: Ihre Projekt-ID.

    • LOCATION: Ihre Region. Hier finden Sie eine Liste der unterstützten Regionen für Memory Bank.

    • AGENT_ENGINE_NAME: Der Name der von Ihnen erstellten Agent Platform-Instanz oder einer vorhandenen Agent Platform-Instanz. Der Name sollte 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 in 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.

  2. Laden Sie Ereignisse iterativ in Ihre Sitzung hoch. 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 die Erstellung von Erinnerungen für den jeweiligen Nutzer verwendet.

    import datetime

client.agent_engines.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 Erinnerungen aus Ihrem Unterhaltungsverlauf generieren möchten, lösen Sie eine Anfrage zur Erinnerungsgenerierung für die Sitzung aus:

    client.agent_engines.memories.generate(
name=agent_engine.api_resource.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 darf maximal 5 Schlüssel/Wert-Paare enthalten und keine *-Zeichen. Beispiel: {"session_id": "MY_SESSION"} Für die Konsolidierung werden nur Erinnerungen mit demselben Umfang berücksichtigt. Wenn nichts angegeben ist, wird {"user_id": session.user_id} verwendet.

Erinnerungen hochladen

Als Alternative zum Generieren von Erinnerungen mit rohem Dialog 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.agent_engines.memories.generate(
    name=agent_engine.api_resource.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.agent_engines.memories.create(
    name=agent_engine.api_resource.name,
    fact="This is a fact.",
    scope={"user_id": "123"}
)

"""
Returns an AgentEngineMemoryOperation containing the created Memory like:

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

Erinnerungen 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 ermöglichen.

Weitere Informationen zum Abrufen von Erinnerungen mit einer bereichsbasierten Methode finden Sie unter Erinnerungen abrufen.

# Retrieve all memories for User ID 123.
retrieved_memories = list(
    client.agent_engines.memories.retrieve(
        name=agent_engine.api_resource.name,
        scope={"user_id": "123"}
    )
)

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

Erinnerungen entfernen

Es gibt mehrere Möglichkeiten, Erinnerungen aus Ihrer Memory Bank-Instanz zu löschen. Die Auswahl der zu entfernenden Erinnerungen hängt davon ab, wie Sie vorgehen möchten.

Entfernen nach Ressourcennamen

Wenn Sie genau wissen, welche Speicherressource Sie entfernen möchten, können Sie einen bestimmten Speicher anhand seines Ressourcennamens löschen:

client.agent_engines.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 Memes. Der Name sollte 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 eine der Optionen filter (für Systemfelder) oder filter_groups (für Metadatenfelder) angeben.

operation = client.agent_engines.memories.purge(
    name=agent_engine.api_resource.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, fact und topics. Weitere Informationen zum Filtern nach Systemfeldern finden Sie auf der Seite „Erinnerungen abrufen“ im Abschnitt Nach Metadatenfeldern filtern.
  • FILTER_GROUPS: Eine Liste von Dictionarys oder Objekten zum Filtern von Arbeitsspeichermetadaten. Weitere Informationen zum Filtern nach Metadatenfeldern finden Sie auf der Seite „Erinnerungen abrufen“ im Abschnitt Nach Systemfeldern filtern.

Der Vorgang gibt eine Anzahl der gelöschten Erinnerungen zurück (bei force=True) oder 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.agent_engines.memories.purge(
    name=agent_engine.api_resource.name,
    filter="scope.user_id=\"123\""
    force=True
)

Entfernen nach semantischer Bedeutung

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 Erinnerung kann gelöscht werden, wenn die neuen Informationen ihr widersprechen oder wenn der extrahierte Inhalt die Funktion „Informationen merken“ anweist, ein Thema zu vergessen (im Fall des EXPLICIT_INSTRUCTIONS-Erinnerungsthemas).

Mit der folgenden Anfrage werden beispielsweise vorhandene Gemerkte Informationen gelöscht, die Informationen zu Ernährungspräferenzen enthalten, sofern sie für die angegebene scope vorhanden sind:

from google import genai

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.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 den Schnellstart verwendet haben.

Andernfalls können Sie die einzelnen Ressourcen löschen, die Sie in dieser Anleitung erstellt haben:

  1. Mit dem folgenden Codebeispiel können Sie die Agent Platform-Instanz löschen. Dadurch werden auch alle Sitzungen oder Erinnerungen gelöscht, die mit der Agent Platform-Instanz verknüpft sind.

    agent_engine.delete(force=True)

  2. Löschen Sie alle lokal erstellten Dateien.

Nächste Schritte

Kurzanleitung

Erste Schritte mit dem Agent Development Kit (ADK)