Erinnerungen abrufen

Mit Memory Bank können Sie gespeicherte Erinnerungen mit verschiedenen Vorgängen abrufen, je nach Ihren Anforderungen. Sie können eine einzelne Erinnerung abrufen, alle Erinnerungen auflisten oder eine bereichsbasierte Suche mit der Ähnlichkeitssuche durchführen.

In diesem Dokument wird erläutert, wie Sie diese Abrufvorgänge mit dem Agent Platform SDK verwenden.

Wenn Sie das Agent Development Kit (ADK) verwenden, kann Ihr Agent diese Aufrufe automatisch für Sie orchestrieren. Weitere Informationen finden Sie unter Schnellstartanleitung mit dem ADK.

Hinweis

Wenn Sie die Schritte auf dieser Seite ausführen möchten, müssen Sie zuerst die Schritte unter Für Memory Bank einrichten ausführen.

Abrufvorgänge

Sie haben folgende Möglichkeiten, generierte Erinnerungen abzurufen:

  • Erinnerung abrufen: Rufen Sie den vollständigen Inhalt einer einzelnen Erinnerung mit dem Agent Platform SDK ab.

  • Erinnerungen abrufen: Rufen Sie mit dem Agent Platform SDK Erinnerungen mithilfe des bereichsbasierten Abrufs von Erinnerungen ab. Rufen Sie Erinnerungen mit der Ähnlichkeitssuche oder alle Erinnerungen im Bereich ab.

  • Erinnerungen auflisten: Listen Sie Erinnerungen mit dem Agent Platform SDK auf.

Erinnerung abrufen

Verwenden Sie GetMemories, um den vollständigen Inhalt einer einzelnen Erinnerung abzurufen:

memory = client.memory_banks.memories.get(
    name="MEMORY_NAME")

Ersetzen Sie Folgendes:

  • MEMORY_NAME: Ein vollständig qualifizierter Name der Erinnerung im Format „projects/.../locations/.../reasoningEngines/.../memories...“.

Erinnerungen mit bereichsbasiertem Abruf abrufen

Mit RetrieveMemories können Sie Erinnerungen für einen bestimmten Bereich abrufen. Es werden nur Erinnerungen zurückgegeben, die genau denselben Bereich (unabhängig von der Reihenfolge) wie die Abrufanfrage haben. Sie können beispielsweise alle Erinnerungen abrufen, die einem bestimmten Nutzer zugeordnet sind , indem Sie {"user_id": "123"} verwenden. Wenn keine Erinnerungen zurückgegeben werden, sind in Memory Bank keine Erinnerungen für den angegebenen Bereich vorhanden.

Der Bereich einer Erinnerung wird beim Generieren oder Erstellen der Erinnerung definiert und ist unveränderlich.

Mit RetrieveMemories können Sie die folgenden Vorgänge für einen bestimmten Bereich ausführen:

Wenn Sie viele Erinnerungen für einen bestimmten Bereich haben, können Sie mit der Ähnlichkeitssuche nur die ähnlichsten Erinnerungen abrufen, indem Sie Parameter für die Ähnlichkeitssuche angeben. Bei der Ähnlichkeitssuche berücksichtigt Memory Bank nur Erinnerungen, die genau denselben Bereich wie die Anfrage haben. Bei der Ähnlichkeitssuche werden die Einbettungsvektoren zwischen den Fakten der Erinnerungen und der Suchanfrage verglichen.

Die zurückgegebenen Erinnerungen werden von der ähnlichsten (kürzester euklidischer Abstand) zur am wenigsten ähnlichen (größter euklidischer Abstand) sortiert:

results = client.memory_banks.memories.retrieve(
    name=memory_bank.name,
    scope=SCOPE,
    similarity_search_params={
        "search_query": "QUERY",
        # Optional. Defaults to 3.
        "top_k": 3
    }
)
# RetrieveMemories returns a pager. You can use `page` to retrieve memories.

results.page

"""
Returns:

[
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is a fact."
      },
      distance=0.5
    ),
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is another fact."
      },
      distance=0.7
    ),
]
"""

Ersetzen Sie Folgendes:

  • QUERY: Die Abfrage, für die die Ähnlichkeitssuche durchgeführt werden soll. Sie können beispielsweise die letzte Nutzerantwort der Unterhaltung als Abfrage verwenden.

  • SCOPE: Ein Wörterbuch, das den Bereich für die Ähnlichkeitssuche darstellt. Beispiel: {"user_id": "123"}. Es werden nur Erinnerungen mit demselben Bereich wie die Anfrage berücksichtigt.

Alle Erinnerungen abrufen

Wenn keine Parameter für die Ähnlichkeitssuche angegeben werden, gibt RetrieveMemories alle Erinnerungen mit dem angegebenen Bereich zurück, unabhängig von ihrer Ähnlichkeit mit der aktuellen Unterhaltung.

results = client.memory_banks.memories.retrieve(
    name=memory_bank.name,
    scope=SCOPE
)
# RetrieveMemories returns a pager. You can use `page` to retrieve up to 100 memories per page.

results.page

"""
Returns:

[
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is a fact."
      }
    ),
    RetrieveMemoriesResponseRetrievedMemory(
      memory=Memory(
        name="projects/.../locations/.../reasoningEngines/.../memories/...",
        ...
        fact="This is another fact."
      }
    ),
]
"""

Ersetzen Sie Folgendes:

  • SCOPE: Ein Wörterbuch, das den Bereich für den Abruf darstellt. Beispiel: {"user_id": "123"}. Es werden nur Erinnerungen mit demselben Bereich wie die Anfrage zurückgegeben.

Erinnerungen auflisten

Verwenden Sie ListMemories, um Erinnerungen aus Ihrer Memory Bank ohne bereichsbasierte Filterung abzurufen. Verwenden Sie für den bereichsbasierten Abruf stattdessen RetrieveMemories. ListMemories wird nicht für den Abruf mit niedriger Latenz empfohlen.

pager = client.memory_banks.memories.list(name=memory_bank.name)
for page in pager:
  print(page)

Erinnerungen filtern

In diesem Abschnitt wird beschrieben, wie Sie Filter verwenden, um einzuschränken, welche Erinnerungen abgerufen werden. Sie können nach folgenden Kriterien filtern:

  • Metadaten mit dem filter_groups Attribut für bereichsbasierten Abruf.

  • Systemfelder mit filter. Systemfelder umfassen topics, create_time, update_time und fact der Erinnerungen.

Sowohl die Filterung nach Metadaten als auch nach Systemfeldern kann in derselben Anfrage verwendet werden.

Nach Metadaten filtern

Beim Erstellen, Aktualisieren oder Generieren von Erinnerungen können Sie den gespeicherten Erinnerungen strukturierte Metadaten hinzufügen:

import datetime

from agentplatform import types

metadata = {
    "my_string_key": types.MemoryMetadataValue(string_value="my_string_value"),
    "my_double_key": types.MemoryMetadataValue(double_value=123.456),
    "my_boolean_key": types.MemoryMetadataValue(bool_value=True),
    "my_timestamp_key": types.MemoryMetadataValue(
        timestamp_value=datetime.datetime(
            2027, 1, 1, 12, 30, 00, tzinfo=datetime.timezone.utc
        )
    ),
}

client.memory_banks.memories.create(
  ...,
  config={"metadata": metadata}
)

client.memory_banks.memories.update(
  ...,
  config={"metadata": metadata}
)

client.memory_banks.memories.generate(
  ...,
  config={"metadata": metadata}
)

Sie können diese Metadaten beim Abrufen von Erinnerungen mit dem Attribut filter_groups filtern. Metadatenfilter werden in disjunktiver Normal form (DNF) definiert, einem logischen Ausdruck von ORs of ANDs.

Die folgende Anfrage ruft beispielsweise Erinnerungen ab, die die Metadaten ({"my_string_key": {"string_value": "my_value"}} UND {"my_double_key": {"double": 1.23}}) ODER {"my_string_key": {"string_value": "other"}} enthalten.

Wörterbuch

results = client.memory_banks.memories.retrieve(
  ...,
  config={
    # Each element of `filter_groups` is combined using OR logic.
    "filter_groups": [
      {
        # Each element of `filters` is combined using AND logic.
        "filters": [
          {
            "key": "my_string_key",
            "value": {"string_value": "my_value"}
          },
          {
            "key": "my_double_key",
            "value": {"double_value": 1.23}
          }
        ]
      },
      {
        "filters": [
          {
            "key": "my_string_key",
            "value": {"string_value": "other"}
          }
        ]
      }
    ]
  }
)

Klassenbasiert

from agentplatform import types

results = client.memory_banks.memories.retrieve(
  ...,
  config=types.RetrieveMemoriesConfig(
    # Each element of `filter_groups` is combined using OR logic.
    filter_groups=[
      types.MemoryConjunctionFilter(
        # Each element of `filters` is combined using AND logic.
        filters=[
          types.MemoryFilter(
            key="my_string_key",
            value=types.MemoryMetadataValue(string_value="my_value")
          ),
          types.MemoryFilter(
            key="my_double_key",
            value=types.MemoryMetadataValue(double_value=1.23)
          )
        ]
      ),
      types.MemoryConjunctionFilter(
        filters=[
          types.MemoryFilter(
            key="my_string_key",
            value=types.MemoryMetadataValue(string_value="other")
          )
        ]
      )
    ]
  )
)

Nach Systemfeldern filtern

Sie können nach Systemfeldern mit dem filter Attribut filtern, das einen Stringwert in EBNF Syntax erwartet. Systemfelder umfassen create_time, update_time, fact, und topics.

Bei der Erstellung eines Filterstrings gelten für die EBNF-Syntax die folgenden Anforderungen:

  • Verwenden Sie AND und OR, um Filter zu kombinieren.
  • Strings sollten doppelte Anführungszeichen " verwenden.
  • Für Datums-/Uhrzeitfelder wie create_time wird entweder ein String in doppelten Anführungszeichen verwendet, der das Datum und die Uhrzeit im ISO 8601-Format darstellt, oder ein numerisches Feld, das die Mikrosekunden seit der Unix-Epoche darstellt.

Mit dem folgenden Filter können beispielsweise Erinnerungen abgerufen werden, bei denen fact den Teilstring „allergies“ enthält und update_time nach dem 1. Januar 2026 liegt.

filter_string = 'fact=~".*allergies.*" AND update_time>="2026-01-01T00:00:00Z"'

client.memory_banks.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

client.memory_banks.memories.list(
  ...,
  config={"filter": filter_string}
)

Nach Themen filtern

Generierte Erinnerungen werden automatisch mit dem relevanten Thema der Erinnerung gekennzeichnet.

Wenn Sie nach verwalteten Themen filtern möchten, verwenden Sie topics.managed_memory_topic als Feldnamen und das erwartete ManagedTopicEnum als Wert, z. B. topics.managed_memory_topic: USER_PREFERENCES.

Wenn Sie nach benutzerdefinierten Themen filtern möchten, verwenden Sie topics.custom_memory_topic_label als Feld namen und das Label des erwarteten Themas als Wert, z. B. topics.custom_memory_topic_label: custom-label.

filter_string = "topics.managed_memory_topic: USER_PREFERENCES " + \
"OR topics.custom_memory_topic_label: custom-label"

client.memory_banks.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

client.memory_banks.memories.list(
  ...,
  config={"filter": filter_string}
)