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 da 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 a Memory Bank con ADK.

Prima di iniziare

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

import vertexai

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

memory_bank = client.agent_engines.create()
sessions = client.agent_engines.create()

Generare ricordi con le sessioni di Agent Platform

Dopo aver configurato le sessioni di Agent Platform, puoi creare sessioni e aggiungere eventi. Poi, puoi utilizzare Memory Bank per generare ricordi dalla conversazione dell'utente con l'agente in modo che siano disponibili per le interazioni future dell'utente. Per ulteriori informazioni, consulta Generare ricordi e Recuperare ricordi.

  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 vertexai

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

session = client.agent_engines.sessions.create(
# The name can be fetched using `sessions.api_resource.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 Sessions che hai creato o di un' istanza di Sessions 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. 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.

  2. Carica gli eventi in modo iterativo 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 origine per generare ricordi per un determinato utente.

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

    client.agent_engines.memories.generate(
  name=memory_bank.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
)

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"}. Per il consolidamento vengono presi in considerazione solo i ricordi con lo stesso ambito. Se non viene fornito, {"user_id": session.user_id} viene utilizzato.

Caricare i ricordi

In alternativa alla generazione di ricordi utilizzando il dialogo non elaborato, puoi caricare i ricordi o fare in modo che i tuoi agenti li aggiungano direttamente utilizzando GenerateMemories con fatti preestratti. Anziché estrarre le informazioni dai contenuti, Memory Bank fornisce direttamente i fatti che devono essere archiviati sull'utente.

Per garantire la coerenza con i ricordi generati, prova a scrivere i fatti preestratti 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.agent_engines.memories.generate(
    name=memory_bank.api_resource.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

Sostituisci quanto segue:

  • FACT: il fatto preestratto che deve essere consolidato con i ricordi esistenti. Puoi fornire fino a 5 fatti preestratti 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"}. Per il consolidamento vengono presi in considerazione solo i ricordi con lo stesso ambito.

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

memory = client.agent_engines.memories.create(
    name=memory_bank.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))
  )
)
"""

Recuperare e utilizzare i ricordi

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

Per ulteriori informazioni sul recupero dei ricordi utilizzando un metodo basato sull'ambito, consulta Recuperare ricordi.

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

Puoi utilizzare jinja per convertire i 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>
"""

Rimuovere i ricordi

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

Rimuovere in base al nome della risorsa

Se sai esattamente quale risorsa di memoria vuoi rimuovere, puoi eliminare un ricordo specifico utilizzando il relativo nome della risorsa:

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

Sostituisci quanto segue:

Rimuovere 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 al meno uno tra filter (applicato ai campi di sistema) o filter_groups (applicato ai campi di metadati).

operation = client.agent_engines.memories.purge(
    name=memory_bank.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
    }
)

Sostituisci quanto segue:

  • FILTER_STRING: una stringa che utilizza EBNF per il filtraggio in base ai campi di sistema. I campi di sistema includono create_time, , fact, e topics.update_time Per ulteriori informazioni sul filtraggio in base ai campi di sistema, consulta la sezione Filtrare in base ai campi di metadati nella pagina Recuperare ricordi.
  • FILTER_GROUPS: un elenco di dizionari o oggetti per il filtraggio in base ai metadati dei ricordi. Per ulteriori informazioni sul filtraggio in base ai campi di metadati, consulta la sezione Filtrare in base ai campi di sistema nella pagina Recuperare ricordi.

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

print(operation.response.purge_count)

Ad esempio, puoi eliminare tutti i ricordi che appartengono a un ambito per user_id "123":

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

Rimuovere in base al significato semantico

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. Un ricordo può essere eliminato se le nuove informazioni lo contraddicono o se i contenuti estratti indicano a Memory Bank di dimenticare un argomento (nel caso dell'argomento del EXPLICIT_INSTRUCTIONSricordo topic).

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

from google import genai

client.agent_engines.memories.generate(
    name=memory_bank.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={...}
)

Esegui la pulizia

Per eliminare tutte le risorse utilizzate in questo progetto, puoi eliminare il Google Cloud progetto 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 l'istanza di Agent Platform, che elimina anche tutte le sessioni o i ricordi associati all'istanza di Agent Platform.

    agent_engine.delete(force=True)

  2. Elimina tutti i file creati localmente.

Passaggi successivi

Guida rapida

Inizia a utilizzare Agent Development Kit (ADK).