Generare ricordi

Memory Bank ti consente di creare ricordi a lungo termine dalle conversazioni tra l'utente e il tuo agente. Memory Bank consolida e seleziona automaticamente i ricordi per un utente specifico aggiungendo, aggiornando e rimuovendo i ricordi nel tempo. Questa pagina descrive come attivare la generazione dei ricordi e come ottenerli.

Quando attivi la generazione di ricordi, Memory Bank esegue automaticamente le seguenti operazioni:

• Estrazione: estrae informazioni sull'utente dalle sue conversazioni con l'agente.

• Consolidation (Consolidamento): indica se le memorie esistenti con lo stesso ambito devono essere eliminate o aggiornate. Memory Bank verifica che i nuovi ricordi non siano duplicati o contraddittori prima di unirli a quelli esistenti.

Non tutte le interazioni con gli user agent comportano la creazione o l'aggiornamento dei ricordi. Memory Bank conserva solo le informazioni ritenute utili per le interazioni future, che possono includere i seguenti tipi di informazioni:

• Informazioni sull'utente, come preferenze, nomi, relazioni, hobby e date importanti. Ad esempio, "Lavoro in Google", "Preferisco il posto lato corridoio" o "Il mio anniversario di matrimonio è il 31 dicembre".
• Eventi chiave della conversazione e risultati delle attività. Ad esempio, "Ho prenotato biglietti aerei per un viaggio di andata e ritorno tra JFK e SFO. Parto il 1° giugno 2025 e torno il 7 giugno 2025".
• Informazioni che l'utente chiede esplicitamente all'agente di ricordare. Ad esempio, se l'utente dice "Ricorda che uso principalmente Python", Memory Bank genera un ricordo come "Uso principalmente Python".

I ricordi possono essere estratti solo da testo, file incorporati e dati dei file nei contenuti di origine. Tutti gli altri contenuti, incluse chiamate e risposte alle funzioni, vengono ignorati durante la generazione dei ricordi.

I ricordi possono essere estratti da immagini, video e audio forniti dall'utente. Se il contesto fornito dall'input multimodale viene giudicato da Memory Bank significativo per le interazioni future, potrebbe essere creata una memoria testuale che includa le informazioni estratte dall'input. Ad esempio, se l'utente fornisce un'immagine di un golden retriever con il testo "Questo è il mio cane", Memory Bank genera un ricordo come "Il mio cane è un golden retriever".

Configura l'ambiente

Prima di iniziare a generare ricordi, devi configurare l'ambiente e l'istanza di Agent Engine. Questa sezione presuppone che tu abbia configurato un ambiente di sviluppo Python o che tu stia utilizzando un runtime con un ambiente di sviluppo Python (come Colab).

Importare librerie

Installa l'SDK Vertex AI:

  pip install google-cloud-aiplatform>=1.100.0

Configura un client SDK Vertex AI

  import vertexai

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

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto.
• LOCATION: La tua regione. Per il Memory Bank di Vertex AI Agent Engine è supportato solo us-central1.

Configura l'istanza di Agent Engine

Per recuperare i ricordi da Memory Bank, devi prima disporre di un'istanza di Agent Engine. Puoi creare una nuova istanza o ottenerne una esistente. Le nuove istanze sono vuote, a meno che tu non crei o generi ricordi.

agent_engine = client.agent_engines.create()

agent_engine = client.agent_engines.get(name="AGENT_ENGINE_NAME")

Generare ricordi

Puoi attivare la generazione di ricordi utilizzando GenerateMemories alla fine di una sessione o a intervalli regolari all'interno di una sessione. La generazione di ricordi estrae il contesto chiave dalle conversazioni di origine e lo combina con i ricordi esistenti per lo stesso ambito. Ad esempio, puoi creare ricordi a livello di sessione utilizzando un ambito come {"user_id": "123", "session_id": "456"}. I ricordi con lo stesso ambito possono essere consolidati e recuperati insieme.

Quando chiami GenerateMemories, devi fornire la conversazione di origine tramite Agent Engine Sessions o direttamente tramite il formato JSON:

client.agent_engines.generate_memories(
  name=agent_engine.api_resource.name,
  vertex_session_source={
    "session": "SESSION_NAME"
  },
  # Optional when using Agent Engine Sessions. Defaults to {"user_id": session.user_id}.
  scope=SCOPE,
  config={
      "wait_for_completion": True
  }
)

client.agent_engines.generate_memories(
    name=agent_engine.api_resource.name,
    direct_contents_source={
      "events": EVENTS
    },
    scope=SCOPE,
    config={
        "wait_for_completion": True
    }
)

[
  {
    "content": {
      "role": "user",
      "parts": [
        {"text": "I'm work with LLM agents!"}
      ]
    }
  }
]

GenerateMemories restituisce un AgentEngineGenerateMemoriesOperation contenente un elenco di ricordi generati:

AgentEngineGenerateMemoriesOperation(
  name="projects/.../locations/.../reasoningEngines/.../operations/...",
  done=True,
  response=GenerateMemoriesResponse(
    generatedMemories=[
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action=<GenerateMemoriesResponseGeneratedMemoryAction.CREATED: "CREATED">,
      ),
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action=<GenerateMemoriesResponseGeneratedMemoryAction.UPDATED: "UPDATED">,
      ),
      GenerateMemoriesResponseGeneratedMemory(
        memory=Memory(
          "name": "projects/.../locations/.../reasoningEngines/.../memories/..."
        ),
        action=<GenerateMemoriesResponseGeneratedMemoryAction.DELETED: "DELETED">,
      ),
    ]
  )
)

Ogni ricordo generato include l'action eseguita su quel ricordo:

• CREATED: indica che è stato aggiunto un nuovo ricordo, che rappresenta un concetto nuovo non acquisito dai ricordi esistenti.
• UPDATED: indica che un ricordo esistente è stato aggiornato, il che si verifica se il ricordo copriva concetti simili alle informazioni appena estratte. Il fatto della memoria potrebbe essere aggiornato con nuove informazioni o rimanere invariato.
• DELETED: indica che il ricordo esistente è stato eliminato perché le sue informazioni erano in contraddizione con le nuove informazioni estratte dalla conversazione.

Per i ricordi CREATED o UPDATED, puoi utilizzare GetMemories per recuperare l'intero contenuto del ricordo. Il recupero di DELETED ricordi genera un errore 404.

Passaggi successivi

• Recuperare i ricordi generati