Recuperare i ricordi

Agent Platform Memory Bank ti consente di recuperare i ricordi archiviati utilizzando diverse operazioni a seconda delle tue esigenze. Puoi recuperare un singolo ricordo, elencare e filtrare i ricordi o eseguire un recupero basato sull'ambito con la ricerca di somiglianze.

Questo documento spiega come recuperare e ispezionare i ricordi nella console Google Cloud o con l'SDK Agent Platform.

Se utilizzi l'Agent Development Kit (ADK), l'agente può orchestrare automaticamente queste chiamate per te. Consulta la Guida rapida con ADK.

Prima di iniziare

Per completare i passaggi descritti in questa pagina, devi prima completare i passaggi descritti in Configura per Memory Bank.

Recupera operazioni

Per recuperare i ricordi generati, hai a disposizione le seguenti opzioni:

  • Recupera memoria: recupera i contenuti completi di una singola memoria utilizzando l'SDK Agent Platform.

  • Recupera i ricordi: utilizza l'SDK Agent Platform per recuperare i ricordi utilizzando il recupero della memoria basato sull'ambito. Recupera i ricordi utilizzando la ricerca di somiglianze o tutti i ricordi nell'ambito.

  • Elenca i ricordi: elenca e filtra i ricordi nella consoleGoogle Cloud o con l'SDK Agent Platform.

Recupera un'informazione salvata

Utilizza GetMemories per ottenere i contenuti completi di un singolo ricordo:

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

Sostituisci quanto segue:

  • MEMORY_NAME: un nome di memoria completo nel formato "projects/…/locations/…/reasoningEngines/…/memories…".

Recupera i ricordi utilizzando il recupero basato sull'ambito

Puoi utilizzare RetrieveMemories per recuperare i ricordi per un ambito specifico. Vengono restituite solo le memorie che hanno esattamente lo stesso ambito (indipendentemente dall'ordine) della richiesta di recupero. Ad esempio, puoi recuperare tutti i ricordi che rientrano nell'ambito di un determinato utente utilizzando {"user_id": "123"}. Se non vengono restituiti ricordi, Memory Bank non contiene ricordi per l'ambito fornito.

L'ambito di una memoria viene definito quando viene generata o creata ed è immutabile.

Puoi utilizzare RetrieveMemories per eseguire le seguenti operazioni per un ambito specifico:

Se hai molti ricordi per un determinato ambito, puoi utilizzare la ricerca di somiglianze per recuperare solo i ricordi più simili fornendo i parametri di ricerca di somiglianze. Memory Bank prende in considerazione solo i ricordi che hanno esattamente lo stesso ambito della richiesta quando esegue la ricerca per somiglianza. La ricerca di somiglianze confronta i vettori di embedding tra i fatti dei ricordi e la query di ricerca della richiesta.

I ricordi restituiti sono ordinati dal più simile (distanza euclidea più breve) al meno simile (distanza euclidea più grande):

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

Sostituisci quanto segue:

  • QUERY: la query per cui eseguire la ricerca di similarità. Ad esempio, puoi utilizzare l'ultimo turno dell'utente nella conversazione come query.

  • SCOPE: un dizionario che rappresenta l'ambito della ricerca per somiglianza. Ad esempio, {"user_id": "123"}. Vengono presi in considerazione solo i ricordi con lo stesso ambito della richiesta.

Recupera tutte le informazioni salvate

Se non vengono forniti parametri di ricerca per somiglianza, RetrieveMemories restituisce tutte le memorie con l'ambito fornito, indipendentemente dalla loro somiglianza con la conversazione corrente.

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

Sostituisci quanto segue:

  • SCOPE: un dizionario che rappresenta l'ambito del recupero. Ad esempio, {"user_id": "123"}. Vengono restituiti solo i ricordi con lo stesso ambito della richiesta.

Elenca informazioni salvate

Puoi elencare e ispezionare le memorie nella console Google Cloud o con l'SDK Agent Platform.

Console

Per visualizzare e filtrare i ricordi nella console Google Cloud (richiede aiplatform.memories.list, incluso in roles/aiplatform.memoryViewer e roles/aiplatform.memoryUser):

  1. Apri l'istanza nella console Google Cloud :

    • Istanza di Memory Bank autonoma: vai alla pagina Memory Bank di Agent Platform e fai clic sulla tua istanza.

      Vai alla banca della memoria

    • Agente di cui è stato eseguito il deployment su Agent Runtime: vai alla pagina Deployment di Agent Platform e fai clic sul tuo agente.

      Vai a Deployment

  2. Apri la scheda Ricordi. Per impostazione predefinita, la visualizzazione Non strutturati mostra una tabella di memorie (Ambito, Nome risorsa, Dato, Data di creazione e Data di aggiornamento).

  3. (Facoltativo) Filtra o gestisci i ricordi:

    • Filtra per ambito: digita una coppia key:value (ad esempio user_id:123) nella barra dei filtri o fai clic su un chip di ambito in una riga.
    • Visualizza i profili strutturati: passa a Strutturati e seleziona un ambito completo oppure applica un filtro di ambito in Non strutturati e fai clic su Cerca nelle memorie strutturate. Per maggiori dettagli, consulta Profili di memoria.
    • Modifica, ispeziona le revisioni o elimina: fai clic sul menu Altre azioni () in una riga di memoria e seleziona Modifica, Visualizza revisioni o Elimina.

SDK Agent Platform

Utilizza ListMemories per elencare i ricordi della tua Memory Bank senza filtri basati sullo scope. Per il recupero basato sull'ambito, utilizza invece RetrieveMemories. ListMemories non è consigliato per il recupero a bassa latenza.

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

Filtra i ricordi

Questa sezione descrive come utilizzare i filtri per limitare i ricordi recuperati. Puoi filtrare in base a:

  • Metadati che utilizzano l'attributo filter_groups per il recupero basato sull'ambito.

  • Campi di sistema che utilizzano filter. I campi di sistema includono topics, create_time, update_time e fact dei ricordi.

Il filtro dei metadati e quello dei campi di sistema possono essere utilizzati nella stessa richiesta.

Filtra per metadati

user English:

Quando crei, aggiorni o generi ricordi, puoi applicare metadati strutturati ai ricordi archiviati:

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

Puoi filtrare questi metadati quando recuperi i ricordi utilizzando l'attributo filter_groups. I filtri dei metadati sono definiti in forma normale disgiuntiva (DNF), che è un'espressione logica di OR di AND.

Ad esempio, la seguente richiesta recupererà i ricordi che includono i metadati ({"my_string_key": {"string_value": "my_value"}} AND {"my_double_key": {"double": 1.23}}) OR {"my_string_key": {"string_value": "other"}}.

Dizionario

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

Basato su classi

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

Filtra per campi di sistema

Puoi filtrare in base ai campi di sistema utilizzando l'attributo filter, che prevede un valore stringa che utilizza la sintassi EBNF. I campi di sistema includono create_time, update_time, fact e topics.

La sintassi EBNF prevede i seguenti requisiti per la creazione di una stringa di filtro:

  • Per combinare i filtri, utilizza AND e OR.
  • La stringa deve utilizzare virgolette doppie ".
  • I campi Datetime (come create_time) utilizzano una stringa tra virgolette doppie che rappresenta la data e l'ora ISO 8601 o un campo numerico che rappresenta i microsecondi dall'epoca di Unix.

Ad esempio, il seguente filtro può essere utilizzato per recuperare i ricordi in cui fact include la sottostringa "allergie" e update_time era successivo al 1° gennaio 2026.

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

Filtra per argomenti

I ricordi generati vengono etichettati automaticamente con l'argomento del ricordo pertinente.

Per filtrare in base agli argomenti gestiti, utilizza topics.managed_memory_topic come nome del campo e il valore ManagedTopicEnum previsto, ad esempio topics.managed_memory_topic: USER_PREFERENCES.

Per filtrare in base ad argomenti personalizzati, utilizza topics.custom_memory_topic_label come nome del campo e l'etichetta dell'argomento previsto come valore, ad esempio 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}
)