Kurzanleitung für die Agent Platform Memory Bank API

Mit der Agent Platform Memory Bank können Sie API-Aufrufe direkt an Sitzungen und Memory Bank senden. Dazu verwenden Sie das Agent Platform SDK. Verwenden Sie das Agent Platform SDK, wenn Sie nicht möchten, dass ein Agent-Framework Aufrufe für Sie orchestriert, oder wenn Sie Sitzungen und Memory Bank in andere Agent-Frameworks als das Agent Development Kit (ADK) einbinden möchten.

In diesem Dokument wird beschrieben, wie Sie Erinnerungen mit API-Aufrufen erstellen, hochladen, abrufen und entfernen.

Eine Kurzanleitung zur Verwendung des ADK finden Sie unter Kurzanleitung für Memory Bank 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-Sitzungen generieren

Nachdem Sie Agent Platform-Sitzungen und Memory Bank eingerichtet haben, können Sie Sitzungen erstellen und Ereignisse 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 nicht transparenten Nutzer-ID. Alle Erinnerungen, die aus dieser Sitzung generiert werden, werden automatisch mit dem Bereich {"user_id": "USER_ID"} verschlüsselt, es sei denn, Sie geben beim Generieren von Erinnerungen explizit einen Bereich an.

    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. Informationen zu den 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 muss das folgende Format haben: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.

    • USER_ID: Eine ID für Ihren Nutzer. Alle Erinnerungen, die aus dieser Sitzung generiert werden werden automatisch mit dem Bereich {"user_id": "USER_ID"} verschlüsselt, es sei denn, Sie geben beim Generieren von Erinnerungen explizit einen Bereich an.

  2. Laden Sie Ereignisse iterativ in Ihre Sitzung hoch. Ereignisse können alle Interaktionen zwischen Ihrem Nutzer, Agent und 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 diesen bestimmten 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 Wörterbuch, das den Bereich der generierten Erinnerungen darstellt, mit maximal 5 Schlüssel/Wert-Paaren und ohne * Zeichen. Beispiel: {"session_id": "MY_SESSION"}. Für die Konsolidierung werden nur Erinnerungen mit demselben Bereich berücksichtigt. Wenn kein Wert angegeben ist, {"user_id": session.user_id} verwendet.

Erinnerungen hochladen

Alternativ zum Generieren von Erinnerungen mit unstrukturierten Dialogen können Sie Erinnerungen hochladen oder Ihre Agenten können sie direkt mit GenerateMemories und vorab extrahierten Fakten hinzufügen. Anstatt dass Memory Bank Informationen aus Ihren Inhalten extrahiert, geben Sie die Fakten, die über Ihren Nutzer gespeichert werden sollen, direkt an.

Um die Konsistenz mit generierten Erinnerungen zu gewährleisten, sollten Sie vorab extrahierte Fakten in 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: Der vorab extrahierte Fakt, der mit vorhandenen Erinnerungen konsolidiert 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 Bereich der generierten Erinnerungen darstellt. Beispiel: {"session_id": "MY_SESSION"}. Für die Konsolidierung werden nur Erinnerungen mit demselben Bereich berücksichtigt.

Alternativ können Sie mit CreateMemory Erinnerungen hochladen, ohne Memory Bank für die Erinnerungsextraktion oder -konsolidierung zu verwenden.

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 gewähren.

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

Sie können jinja verwenden, um Ihre strukturierten Erinnerungen in einen Prompt umzuwandeln:


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 sie auswählen möchten.

Nach Ressourcennamen entfernen

Wenn Sie genau wissen, welche Erinnerungsressource Sie entfernen möchten, können Sie eine bestimmte Erinnerung anhand ihres 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 der zu löschenden Erinnerung. 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, indem Sie Erinnerungen abrufen.

Nach Kriterien entfernen

Sie können eine kriterienbasierte Löschung verwenden, um eine oder mehrere Erinnerungen zu entfernen. Es werden nur Erinnerungen gelöscht, die den angegebenen Filtern entsprechen. Sie müssen mindestens einen der folgenden Werte angeben: filter (angewendet auf Systemfelder) oder filter_groups (angewendet auf Metadatenfelder).

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 im Abschnitt Nach Metadatenfeldern filtern auf der Seite Erinnerungen abrufen.
  • FILTER_GROUPS: Eine Liste von Wörterbüchern oder Objekten zum Filtern nach Erinnerungsmetadaten. Weitere Informationen zum Filtern nach Metadatenfeldern finden Sie im Abschnitt Nach Systemfeldern filtern auf der Seite Erinnerungen abrufen.

Der Vorgang gibt eine Anzahl der gelöschten Erinnerungen zurück (wenn force=True) oder der Erinnerungen, 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 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
)

Nach semantischer Bedeutung entfernen

Beim Merken von 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 Erinnerung kann gelöscht werden, wenn die neuen Informationen ihr widersprechen oder wenn der extrahierte Inhalt Memory Bank anweist, ein Thema zu vergessen (im Fall des EXPLICIT_INSTRUCTIONS Erinnerungs themas).

Mit der folgenden Anfrage werden beispielsweise vorhandene Erinnerungen gelöscht, die Informationen zu Ernährungspräferenzen enthalten, sofern sie für den angegebenen 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 Projekt Google Cloud 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:

  1. Mit dem folgenden Codebeispiel löschen Sie die Agent Platform-Instanz. 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)