Guida rapida all'API Agent Platform Memory Bank

Puoi utilizzare l'SDK Agent Platform per effettuare chiamate API direttamente a Memory Bank. Utilizza l'SDK Agent Platform se non vuoi che un framework di agenti orchestri le chiamate per te o se vuoi integrare Memory Bank con framework di agenti diversi dall'Agent Development Kit (ADK).

Questo documento mostra come creare, caricare, recuperare e rimuovere i ricordi utilizzando le chiamate API.

Per la guida rapida all'utilizzo di ADK, consulta Guida rapida di Memory Bank con ADK.

Per vedere un esempio di utilizzo di con l'SDK, esegui il notebook "Inizia a utilizzare Memory Bank" in uno dei seguenti ambienti:

Apri in Colab | Apri in Colab Enterprise | Apri in Agent Platform Workbench | Visualizza su GitHub

Per visualizzare un esempio di utilizzo di con LangGraph, esegui il notebook "Inizia a utilizzare - LangGraph" in uno dei seguenti ambienti:

Apri in Colab | Apri in Colab Enterprise | Apri in Agent Platform Workbench | Visualizza su GitHub

Prima di iniziare

Per completare i passaggi illustrati in questo tutorial, devi prima seguire i passaggi descritti in Configura per Memory Bank. Prima di iniziare questa guida rapida, assicurati di aver creato un'istanza Memory Bank e un'istanza Sessions, come mostrato nell'esempio seguente:

import agentplatform

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

memory_bank = client.memory_banks.create()
sessions = client.runtimes.create()

Genera ricordi con Agent Platform Sessions

Dopo aver configurato le sessioni della piattaforma dell'agente, puoi creare sessioni e aggiungere eventi. In seguito, puoi utilizzare Memory Bank per generare informazioni salvate dalla conversazione dell'utente con l'agente, in modo che siano disponibili per le interazioni future dell'utente. Per saperne di più, consulta Genera ricordi e Recupera ricordi.

Nota: puoi anche fornire la cronologia delle conversazioni direttamente nel payload GenerateMemories utilizzando l'origine dei contenuti diretti.

1. Crea una sessione con un ID utente opaco. Tutti i ricordi generati da questa sessione vengono automaticamente associati all'ambito {"user_id": "USER_ID"}, a meno che non fornisci esplicitamente un ambito durante la generazione dei ricordi.

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

   Sostituisci quanto segue:

   • PROJECT_ID: il tuo ID progetto.

   • LOCATION: la tua regione. Consulta le regioni supportate per Memory Bank.

   • SESSIONS_NAME: il nome dell'istanza di sessioni che hai creato o di un'istanza di sessioni esistente. Il nome deve essere nel seguente formato: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.

   • USER_ID: un identificatore per l'utente. Tutte le informazioni salvate generate da questa sessione vengono associate automaticamente all'ambito {"user_id": "USER_ID"}, a meno che non fornisci esplicitamente un ambito durante la generazione delle informazioni salvate.

2. Carica in modo iterativo gli eventi nella sessione. Gli eventi possono includere qualsiasi interazione tra l'utente, l'agente e gli strumenti. L'elenco ordinato di eventi rappresenta la cronologia delle conversazioni della sessione. Questa cronologia delle conversazioni viene utilizzata come materiale di partenza per generare i ricordi per quel particolare utente.

   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. Per generare ricordi dalla cronologia delle conversazioni, attiva una richiesta di generazione di ricordi per la sessione:

   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
   )
   

Sostituisci quanto segue:

• (Facoltativo) SCOPE: un dizionario che rappresenta l'ambito dei ricordi generati, con un massimo di 5 coppie chiave-valore e nessun carattere *. Ad esempio: {"session_id": "MY_SESSION"}. Solo i ricordi con lo stesso ambito vengono presi in considerazione per il consolidamento. Se non viene fornito, viene utilizzato {"user_id": session.user_id}.

Carica informazioni salvate

In alternativa alla generazione di memorie utilizzando il dialogo non elaborato, puoi caricare le memorie o chiedere agli agenti di aggiungerle direttamente utilizzando GenerateMemories con fatti pre-estratti. Anziché estrarre informazioni dai tuoi contenuti, Memory Bank riceve direttamente da te i fatti che devono essere memorizzati sull'utente.

Per garantire la coerenza con i ricordi generati, prova a scrivere i fatti pre-estratti nella stessa prospettiva che hai configurato per l'ambito specificato. Per impostazione predefinita, i ricordi vengono generati in prima persona (ad esempio, I am a software engineer).

client.memory_banks.memories.generate(
    name=memory_bank.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

Sostituisci quanto segue:

• FACT: il fatto pre-estratto che deve essere consolidato con i ricordi esistenti. Puoi fornire fino a 5 fatti pre-estratti in un elenco come il seguente:

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

• SCOPE: un dizionario che rappresenta l'ambito dei ricordi generati. Ad esempio, {"session_id": "MY_SESSION"}. Solo i ricordi con lo stesso ambito vengono presi in considerazione per il consolidamento.

In alternativa, puoi utilizzare CreateMemory per caricare i ricordi senza utilizzare Memory Bank per l'estrazione o il consolidamento dei ricordi.

Attenzione: i ricordi caricati utilizzando CreateMemory non verranno consolidati con i ricordi esistenti, quindi potresti ritrovarti con ricordi duplicati per lo stesso ambito. I ricordi creati sono disponibili per la ricerca di somiglianze e possono essere consolidati per richieste future durante la generazione dei ricordi.

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

Recupera e utilizza i ricordi

Puoi recuperare i ricordi dell'utente e includerli nelle istruzioni di sistema per consentire all'LLM di accedere al tuo contesto personalizzato.

Per saperne di più sul recupero dei ricordi utilizzando un metodo basato sull'ambito, consulta Recupera i ricordi.

# Retrieve memories for User ID 123.
retrieved_memories = client.memory_banks.memories.retrieve(
    name=memory_bank.name,
    scope={"user_id": "123"}
).page

Puoi utilizzare jinja per convertire i tuoi ricordi strutturati in un prompt:

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

Rimuovi i ricordi

Esistono diversi modi per eliminare i ricordi dall'istanza di Memory Bank, a seconda di come vuoi selezionare i ricordi da rimuovere.

Rimuovi per nome risorsa

Se sai esattamente quale risorsa di memoria vuoi rimuovere, puoi eliminare una memoria specifica utilizzando il nome della risorsa:

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

Sostituisci quanto segue:

• MEMORY_NAME: il nome della memoria da eliminare. Il nome deve essere nel seguente formato: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}. Puoi trovare il nome della memoria recuperando le memorie.

Rimuovi in base ai criteri

Puoi utilizzare l'eliminazione basata su criteri per rimuovere uno o più ricordi. Verranno eliminati solo i ricordi che corrispondono ai filtri forniti. Devi specificare almeno uno tra filter (applicato ai campi di sistema) o filter_groups (applicato ai campi dei metadati).

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

Sostituisci quanto segue:

• FILTER_STRING: una stringa che utilizza la sintassi EBNF per il filtro in base ai campi di sistema. I campi di sistema includono create_time, update_time, fact e topics. Per saperne di più sul filtro in base ai campi di sistema, consulta la sezione Filtra per campi dei metadati nella pagina Recupera i ricordi.
• FILTER_GROUPS: un elenco di dizionari o oggetti per il filtro rispetto ai metadati della memoria. Per saperne di più sui filtri in base ai campi dei metadati, consulta la sezione Filtra per campi di sistema nella pagina Recupera i ricordi.

L'operazione restituirà un conteggio del numero di ricordi eliminati (se force=True) o che verrebbero eliminati se l'operazione venisse eseguita (se force=False).

print(operation.response.purge_count)

Ad esempio, puoi eliminare tutte le memorie che appartengono a un ambito per user_id "123":

operation = client.memory_banks.memories.purge(
    name=memory_bank.name,
    filter="scope.user_id=\"123\"",
    force=True
)

Rimuovi per significato semantico

Nota: il comportamento previsto può variare a seconda degli argomenti della memoria e degli esempi few-shot che hai configurato.

Durante la generazione dei ricordi, Memory Bank deciderà se creare, aggiornare o eliminare i ricordi in base ai contenuti delle informazioni appena estratte e ai ricordi esistenti. Una memoria può essere eliminata se le nuove informazioni la contraddicono o se i contenuti estratti indicano alla Memory Bank di dimenticare un argomento (nel caso dell'argomento della memoria EXPLICIT_INSTRUCTIONS).

Ad esempio, la seguente richiesta eliminerebbe i ricordi esistenti che contengono informazioni sulle preferenze alimentari, se esistono per il scope specificato:

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={...}
)

Esegui la pulizia

Per eliminare tutte le risorse utilizzate in questo progetto, puoi eliminare il progetto Google Cloud utilizzato per la guida rapida.

In alternativa, puoi eliminare le singole risorse che hai creato in questo tutorial, come segue:

1. Utilizza il seguente esempio di codice per eliminare Agent Platform Memory Bank e Agent Runtime nelle istanze di Gemini Enterprise Agent Platform:

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

2. Elimina tutti i file creati localmente.

Passaggi successivi

Guida rapida

Guida rapida con Agent Development Kit

Inizia a utilizzare l'Agent Development Kit (ADK).