Configurare Memory Bank di Agent Platform

Per utilizzare Memory Bank di Agent Platform, devi prima creare e configurare un'istanza di Gemini Enterprise Agent Platform. Questa istanza gestisce i tuoi ricordi e può essere integrata con i tuoi agenti in vari runtime.

Questo documento spiega come configurare il tuo progetto Google Cloud , installare le librerie richieste e creare o aggiornare un'istanza con configurazioni personalizzate come argomenti e TTL.

Inizia

Prima di utilizzare Memory Bank, devi configurare l'ambiente.

Configura il progetto Google Cloud

Ogni progetto può essere identificato in due modi: tramite il numero del progetto o l'ID progetto. PROJECT_NUMBER viene creato automaticamente quando crei il progetto, mentre PROJECT_ID viene creato da te o da chiunque abbia creato il progetto. Per configurare un progetto:

  1. Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Agent Platform API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

    8.

Ottenere i ruoli richiesti

Per ottenere le autorizzazioni necessarie per utilizzare Memory Bank, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Se effettui richieste a Memory Bank da un agente di cui è stato eseguito il deployment su Google Kubernetes Engine o Cloud Run, assicurati che il tuo account di servizio disponga delle autorizzazioni necessarie. L'agente di servizio Reasoning Engine dispone già delle autorizzazioni necessarie per leggere e scrivere ricordi, pertanto le richieste in uscita da Agent Runtime dovrebbero già disporre dell'autorizzazione di accesso a Memory Bank.

Installare le librerie

Questa sezione presuppone che tu abbia configurato un ambiente di sviluppo Python o che utilizzi un runtime con un ambiente di sviluppo Python (come Colab).

Installa l'SDK Agent Platform:

pip install google-cloud-aiplatform>=1.111.0

Autenticazione

Segui le istruzioni riportate in Autenticazione in Vertex AI.

Configura un client SDK Agent Platform

Esegui il seguente codice per configurare un client SDK Agent Platform:

SDK Agent Platform 

import vertexai

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

dove

Crea o aggiorna un'istanza di Agent Platform

Per iniziare a utilizzare Memory Bank, devi prima disporre di un'istanza di Agent Platform. Se non hai ancora un'istanza, puoi crearla utilizzando la configurazione predefinita:

agent_engine = client.agent_engines.create()

# Optionally, print out the Agent Platform resource name. You will need the
# resource name to interact with your Agent Platform instance later on.
print(agent_engine.api_resource.name)

Se vuoi personalizzare la configurazione del comportamento della tua istanza di Memory Bank nuova o esistente, consulta Configurare l'istanza di Agent Platform per Memory Bank. Ad esempio, puoi specificare quali informazioni Memory Bank considera significative da conservare.

La tua istanza di Agent Platform supporta Sessioni e Memory Bank preconfigurato. Nessun agente viene deployment quando crei l'istanza. Per utilizzare Agent Runtime, devi fornire l'agente da eseguire il deployment quando crei o aggiorni l'istanza di Agent Platform.

Una volta creata un'istanza di Agent Platform, puoi utilizzare il nome dell'istanza per leggere o scrivere ricordi. Ad esempio:

# Generate memories using your Memory Bank instance.
client.agent_engines.memories.generate(
  # `name` should have the format `projects/.../locations/.../reasoningEngines/...`.
  name=agent_engine.api_resource.name,
  ...
)

Utilizzo con Agent Runtime

Sebbene Memory Bank possa essere utilizzato in qualsiasi runtime, puoi anche utilizzarlo con Agent Runtime per leggere e scrivere ricordi dall'agente di cui hai eseguito il deployment.

Per eseguire il deployment di un agente con Memory Bank su Agent Platform, innanzitutto configura l'ambiente per Agent Runtime. Poi, prepara l'agente per il deployment su Agent Runtime con l'integrazione della memoria. L'agente di cui è stato eseguito il deployment deve effettuare chiamate per leggere e scrivere ricordi in base alle necessità.

AdkApp

Se utilizzi il modello Agent Development Kit di Agent Platform, l'agente utilizza VertexAiMemoryBankService per impostazione predefinita quando viene eseguito il deployment su Agent Platform. Ciò significa che gli strumenti di memoria dell'ADK leggono le memorie dalla banca di memoria.

from google.adk.agents import Agent
from vertexai.preview.reasoning_engines import AdkApp

# Develop an agent using the ADK template.
agent = Agent(...)

adk_app = AdkApp(
      agent=adk_agent,
      ...
)

# Deploy the agent to Agent Runtime.
agent_engine = client.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
            # Optional.
            **context_spec
      }
)

# Update an existing Agent Runtime to add or modify the Runtime.
agent_engine = client.agent_engines.update(
      name=agent_engine.api_resource.name,
      agent=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
            # Optional.
            **context_spec
      }
)

Sostituisci quanto segue:

  • STAGING_BUCKET: il bucket Cloud Storage da utilizzare per lo staging di Agent Runtime.

Per saperne di più sull'utilizzo di Memory Bank con ADK, consulta la guida rapida di Agent Development Kit.

Agente personalizzato

Puoi utilizzare Memory Bank con il tuo agente personalizzato di cui è stato eseguito il deployment in Agent Runtime. In questo caso, l'agente deve orchestrare le chiamate a Memory Bank per attivare il salvataggio di informazioni e le chiamate per il recupero dei ricordi.

L'applicazione di cui è stato eseguito il deployment in Agent Runtime può leggere le variabili di ambiente GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION,GOOGLE_CLOUD_AGENT_ENGINE_ID per dedurre il nome di Agent Runtime dall'ambiente:

project = os.environ.get("GOOGLE_CLOUD_PROJECT")
location = os.environ.get("GOOGLE_CLOUD_LOCATION")
agent_engine_id = os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID")

agent_engine_name = f"projects/{project}/locations/{location}/reasoningEngines/{agent_engine_id}"

Se utilizzi l'agente di servizio predefinito per l'agente in Agent Runtime, l'agente dispone già dell'autorizzazione di lettura e scrittura delle memorie. Se utilizzi un account di servizio clienti, devi concedere le autorizzazioni al tuo service account per leggere e scrivere i ricordi. Le autorizzazioni richieste dipendono dalle operazioni che l'agente deve essere in grado di eseguire. Se vuoi che il tuo agente recuperi e generi solo ricordi, aiplatform.memories.generate e aiplatform.memories.retrieve sono sufficienti.

Utilizzare in tutti gli altri runtime

Se vuoi utilizzare Memory Bank in un ambiente diverso, ad esempio Cloud Run o Colab, crea un runtime dell'agente senza fornire un agente. Se non fornisci una configurazione, Memory Bank viene creato con le impostazioni predefinite per la gestione del salvataggio di informazioni e del recupero della memoria.

agent_engine = client.agent_engines.create()

Se hai già utilizzato Agent Platform, la creazione di una nuova istanza di Agent Platform senza un runtime dovrebbe richiedere solo pochi secondi. Se è la prima volta che utilizzi la piattaforma per agenti, l'operazione potrebbe richiedere più tempo (1-2 minuti).

Se vuoi configurare il comportamento, fornisci una configurazione Memory Bank:

Crea

agent_engine = client.agent_engines.create(
  config={
    "context_spec": {
      "memory_bank_config": ...
    }
  }
)

Aggiorna

Se vuoi modificare la configurazione di Memory Bank, puoi aggiornare l'istanza di Agent Platform.

agent_engine = client.agent_engines.update(
  # You can access the name using `agent_engine.api_resource.name` for an AgentEngine object.
  name="AGENT_ENGINE_NAME",
  config={
    "context_spec": {
      "memory_bank_config": ...
    }
  }
)

Sostituisci quanto segue:

  • RUNTIME_NAME: il nome di Agent Runtime. Deve essere nel formato projects/.../locations/.../reasoningEngines/.... Vedi le regioni supportate per Memory Bank.

Puoi utilizzare Memory Bank in qualsiasi ambiente con l'autorizzazione a leggere e scrivere ricordi. Ad esempio, per utilizzare Memory Bank con Cloud Run, concedi le autorizzazioni all'identità del servizio Cloud Run per leggere e scrivere i ricordi. Le autorizzazioni richieste dipendono dalle operazioni che l'agente deve essere in grado di eseguire. Se vuoi che il tuo agente recuperi e generi solo ricordi, aiplatform.memories.generate e aiplatform.memories.retrieve sono sufficienti.

Configura l'istanza Agent Platform per Memory Bank

Puoi configurare la tua Memory Bank per personalizzare la modalità di generazione e gestione dei ricordi. Se non fornisci la configurazione, Memory Bank utilizza le impostazioni predefinite per ogni tipo di configurazione.

Puoi configurare le seguenti impostazioni di Memory Bank per la tua istanza:

Il seguente esempio mostra il Memory Bank predefinito:

Dizionario

memory_bank_config = {
  "generation_config": {
    # `gemini-2.5-flash` will be used to extract and consolidate memories.
    # Note: The global endpoint will be used for regions that don't have a
    # regional endpoint available.
    "model": "projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"
  },
  "similarity_search_config": {
    # `text-embedding-005` will be used for similarity search, including
    # during consolidation. Consolidation uses similarity search to find
    # candidate memories that may be updated with new information.
    "embedding_model": "projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/text-embedding-005"
  },
  "ttl_config": {
    # Default TTL for memory revisions is 365 days.
    "memory_revision_default_ttl": f"{365 * 24 * 60 * 60}s"
  },
  "customization_configs": [
    {
      # Extract user information, preferences, key conversation details,
      # and information that the user explicitly asked to be remembered.
      "memory_topics": [
        {"managed_memory_topic": "USER_PERSONAL_INFO"},
        {"managed_memory_topic": "USER_PREFERENCES"},
        {"managed_memory_topic": "KEY_CONVERSATION_DETAILS"},
        {"managed_memory_topic": "EXPLICIT_INSTRUCTIONS"}
      ],
      "consolidation_config": {
        # Only use the latest memory revision of each candidate memory during
        # consolidation.
        "revisions_per_candidate_count": 1
      },
      # Only use the pre-defined set of examples.
      "generate_memories_examples": [],
      # Generate memories in the first person.
      "enable_third_person_memories": False
    }
  ],
  # Memory revisions will be persisted. This can be overridden on a request-level.
  "disable_memory_revisions": False
}

Basato sulla classe

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
from vertexai.types import ManagedTopicEnum
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigGenerationConfig as GenerationConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig as SimilaritySearchConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfig as TtlConfig

memory_bank_config = MemoryBankConfig(
  generation_config=GenerationConfig(
    # `gemini-2.5-flash` will be used to extract and consolidate memories.
    # Note: The global endpoint will be used for regions that don't have a
    # regional endpoint available.
    model="projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"
  ),
  similarity_search_config=SimilaritySearchConfig(
    # `text-embedding-005` will be used for similarity search, including
    # during consolidation. Consolidation uses similarity search to find
    # candidate memories that may be updated with new information.
    embedding_model="projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/text-embedding-005"
  ),
  ttl_config=TtlConfig(
    # Default TTL for memory revisions is 365 days.
    memory_revision_default_ttl=f"{365 * 24 * 60 * 60}s"
  ),
  customization_configs=[
    CustomizationConfig(
      # Extract personal information, preferences, key conversation details,
      # and information that the user explicitly asked to be remembered.
      memory_topics=[
        MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
            managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)),
        MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
            managed_topic_enum=ManagedTopicEnum.USER_PREFERENCES)),
        MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
            managed_topic_enum=ManagedTopicEnum.KEY_CONVERSATION_DETAILS)),
        MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
            managed_topic_enum=ManagedTopicEnum.EXPLICIT_INSTRUCTIONS))
      ],
      # Only use the pre-defined set of examples.
      generate_memories_examples=[],
      consolidation_config=ConsolidationConfig(
        # Only use the latest memory revision of each candidate memory during
        # consolidation.
        revisions_per_candidate_count=1
      ),
      # Generate memories in the first person.
      enable_third_person_memories=False,
    )
  ],
  # Memory revisions will be persisted. This can be overridden on a request-level.
  disable_memory_revisions=False
)

Puoi modificare la configurazione di Memory Bank quando crei o aggiorni l'istanza di Agent Platform. Il seguente esempio mostra come creare o aggiornare un'istanza con una configurazione specifica di Memory Bank.

client.agent_engines.create(
      ...,
      config={
            "context_spec": {
                  "memory_bank_config": memory_bank_config
            }
      }
)

# Alternatively, update an existing Agent Platform instance's Memory Bank config.
agent_engine = client.agent_engines.update(
      name=agent_engine.api_resource.name,
      config={
          "context_spec": {
                "memory_bank_config": memory_bank_config
          }
      }
)

Configurazione della personalizzazione della memoria in linguaggio naturale

Per personalizzare il modo in cui Memory Bank estrae i ricordi in linguaggio naturale, configura il comportamento di estrazione quando configuri l'istanza. Utilizza le seguenti opzioni per personalizzare il comportamento:

Puoi pensare di personalizzare il comportamento di estrazione del Memory Bank in due passaggi: dire e mostrare. Gli argomenti della Memoria indicano alla Memory Bank quali informazioni conservare. Gli esempi mostrano a Memory Bank il tipo di informazioni che devono generare un ricordo specifico, aiutandolo a imparare i pattern, le sfumature e le frasi che ti aspetti che comprenda.

Se vuoi, puoi configurare un comportamento diverso per i diversi livelli di ambito. Ad esempio, gli argomenti significativi per i ricordi a livello di sessione potrebbero non essere significativi per i ricordi a livello di utente (in più sessioni). Per configurare il comportamento per un determinato sottoinsieme di ricordi, imposta le chiavi di ambito della configurazione della personalizzazione. Solo le richieste GenerateMemories che includono queste chiavi di ambito utilizzeranno questa configurazione. Puoi anche configurare il comportamento predefinito (che si applica a tutti i set di chiavi di ambito) omettendo il campo scope_key. Questa configurazione verrà applicata a tutte le richieste che non hanno una configurazione che corrisponda esattamente alle chiavi di ambito per un'altra configurazione di personalizzazione.

Ad esempio, user_level_config si applicherebbe solo alle richieste GenerateMemories che utilizzano esattamente la chiave di ambito user_id (ovvero scope={"user_id": "123"} senza chiavi aggiuntive). default_config si applicherebbe ad altre richieste:

Dizionario 


user_level_config = {
  "scope_keys": ["user_id"],
  "memory_topics": [...],
  "generate_memories_examples": [...]
}

default_config = {
  "memory_topics": [...],
  "generate_memories_examples": [...]
}

memory_bank_config = {
  "customization_configs": [
    user_level_config,
    default_config
  ]
}

Basato sulla classe 

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig

user_level_config = CustomizationConfig(
  scope_keys=["user_id"],
  memory_topics=[...],
  generate_memories_examples=[...]
)

Configurazione degli argomenti di memoria

Gli "argomenti dei ricordi" identificano le informazioni che Memory Bank considera significative e che devono quindi essere conservate come ricordi generati. Memory Bank supporta due tipi di argomenti di memoria:

  • Argomenti gestiti: l'etichetta e le istruzioni sono definite da Memory Bank. Devi solo fornire il nome dell'argomento gestito. Ad esempio,

    Dizionario

    memory_topic = {
  "managed_memory_topic": {
    "managed_topic_enum": "USER_PERSONAL_INFO"
  }
}

    Basato sulla classe

    from vertexai.types import ManagedTopicEnum
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic

memory_topic = MemoryTopic(
    managed_memory_topic=ManagedMemoryTopic(
        managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO
    )
)

    I seguenti argomenti gestiti sono supportati da Memory Bank:

    • Informazioni utente (USER_PERSONAL_INFO): informazioni significative sull'utente, come nomi, relazioni, hobby e date importanti. Ad esempio, "Lavoro in Google" o "Il mio anniversario di matrimonio è il 31 dicembre".
    • Preferenze degli utenti (USER_PREFERENCES): Mi piace, Non mi piace, stili o motivi preferiti dichiarati o impliciti. Ad esempio, "Preferisco il posto centrale".
    • Eventi chiave della conversazione e risultati delle attività (KEY_CONVERSATION_DETAILS): traguardi o conclusioni importanti all'interno del dialogo. 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."
    • Istruzioni esplicite per ricordare / dimenticare (EXPLICIT_INSTRUCTIONS): informazioni che l'utente chiede esplicitamente all'agente di ricordare o dimenticare. Ad esempio, se l'utente dice "Ricorda che uso principalmente Python", Memory Bank genera un ricordo come "Uso principalmente Python".

  • Argomenti personalizzati: l'etichetta e le istruzioni vengono definite da te durante la configurazione dell'istanza di Memory Bank. Verranno utilizzati nel prompt per il passaggio di estrazione di Memory Bank. Ad esempio,

    Dizionario

    memory_topic = {
  "custom_memory_topic": {
    "label": "business_feedback",
    "description": """Specific user feedback about their experience at
    the coffee shop. This includes opinions on drinks, food, pastries, ambiance,
    staff friendliness, service speed, cleanliness, and any suggestions for
    improvement."""
    }
}

    Basato sulla classe

    from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic

memory_topic = MemoryTopic(
  custom_memory_topic=CustomMemoryTopic(
    label="business_feedback",
    description="""Specific user feedback about their experience at
    the coffee shop. This includes opinions on drinks, food, pastries, ambiance,
    staff friendliness, service speed, cleanliness, and any suggestions for
    improvement."""
  )
)

    Quando utilizzi argomenti personalizzati, ti consigliamo di fornire anche esempi few-shot che mostrino come estrarre i ricordi dalla conversazione.

Con la personalizzazione, puoi utilizzare qualsiasi combinazione di argomenti dei ricordi. Ad esempio, puoi utilizzare un sottoinsieme degli argomenti di memoria gestita disponibili:

Dizionario

customization_config = {
  "memory_topics": [
    { "managed_memory_topic": { "managed_topic_enum": "USER_PERSONAL_INFO" } },
    { "managed_memory_topic": { "managed_topic_enum": "USER_PREFERENCES" } }
  ]
}

Basato sulla classe

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
from vertexai.types import ManagedTopicEnum

customization_config = CustomizationConfig(
  memory_topics=[
      MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
              managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)
      ),
      MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
              managed_topic_enum=ManagedTopicEnum.USER_PREFERENCES)
      ),
  ]
)

Puoi anche utilizzare una combinazione di argomenti gestiti e personalizzati (o solo argomenti personalizzati):

Dizionario

customization_config = {
  "memory_topics": [
    { "managed_memory_topic": { "managed_topic_enum": "USER_PERSONAL_INFO" } },
    {
      "custom_memory_topic": {
        "label": "business_feedback",
        "description": """Specific user feedback about their experience at
the coffee shop. This includes opinions on drinks, food, pastries, ambiance,
staff friendliness, service speed, cleanliness, and any suggestions for
improvement."""
        }
    }
  ]
}

Basato sulla classe

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic
from vertexai.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
from vertexai.types import ManagedTopicEnum

customization_config = CustomizationConfig(
  memory_topics=[
      MemoryTopic(
          managed_memory_topic=ManagedMemoryTopic(
              managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO)
      ),
      MemoryTopic(
          custom_memory_topic=CustomMemoryTopic(
              label="business_feedback",
              description="""Specific user feedback about their experience at
the coffee shop. This includes opinions on drinks, food, pastries, ambiance,
staff friendliness, service speed, cleanliness, and any suggestions for
improvement."""
          )
    )
  ]
)

Esempi few-shot

Gli esempi few-shot ti consentono di dimostrare il comportamento di estrazione dei ricordi previsto a Memory Bank. Ad esempio, puoi fornire una conversazione di input di esempio e i ricordi che dovrebbero essere estratti da questa conversazione.

Ti consigliamo di utilizzare sempre pochi esempi con argomenti personalizzati in modo che Memory Bank possa apprendere il comportamento previsto. I few-shot sono facoltativi quando si utilizzano argomenti gestiti, poiché Memory Bank definisce esempi per ogni argomento. Mostra le conversazioni che non dovrebbero generare ricordi fornendo un elenco generated_memories vuoto.

Ad esempio, puoi fornire esempi few-shot che mostrano come estrarre feedback sulla tua attività dai messaggi dei clienti:

Dizionario

example = {
    "conversationSource": {
      "events": [
        {
          "content": {
            "role": "model",
            "parts": [{ "text": "Welcome back to The Daily Grind! We'd love to hear your feedback on your visit." }] }
        },
        {
          "content": {
            "role": "user",
            "parts": [{ "text": "Hey. The drip coffee was a bit lukewarm today, which was a bummer. Also, the music was way too loud, I could barely hear my friend." }] }
        }
      ]
    },
    "generatedMemories": [
      {
        "fact": "The user reported that the drip coffee was lukewarm."
      },
      {
        "fact": "The user felt the music in the shop was too loud."
      }
    ]
}

Basato sulla classe

from google.genai.types import Content, Part
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent as ConversationSourceEvent
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory as ExampleGeneratedMemory

example = GenerateMemoriesExample(
    conversation_source=ConversationSource(
        events=[
            ConversationSourceEvent(
                content=Content(
                    role="model",
                    parts=[Part(text="Welcome back to The Daily Grind! We'd love to hear your feedback on your visit.")]
                )
            ),
            ConversationSourceEvent(
                content=Content(
                    role="user",
                    parts=[Part(text= "Hey. The drip coffee was a bit lukewarm today, which was a bummer. Also, the music was way too loud, I could barely hear my friend.")]
                )
            )
        ]
    ),
    generated_memories=[
        ExampleGeneratedMemory(
            fact="The user reported that the drip coffee was lukewarm."
        ),
        ExampleGeneratedMemory(
            fact="The user felt the music in the shop was too loud."
        )
    ]
)

Puoi anche fornire esempi di conversazioni che non devono generare ricordi fornendo un elenco vuoto per l'output previsto (generated_memories):

Dizionario

example = {
    "conversationSource": {
        "events": [
          {
              "content": {
                  "role": "model",
                  "parts": [{ "text": "Good morning! What can I get for you at The Daily Grind?" }] }
          },
          {
              "content": {
                  "role": "user",
                  "parts": [{ "text": "Thanks for the coffee." }] }
          }
        ]
    },
    "generatedMemories": []
}

Basato sulla classe

from google.genai.types import Content, Part
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from vertexai.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent as ConversationSourceEvent

example = GenerateMemoriesExample(
    conversation_source=ConversationSource(
        events=[
            ConversationSourceEvent(
                content=Content(
                    role="model",
                    parts=[Part(text="Welcome back to The Daily Grind! We'd love to hear your feedback on your visit.")]
                )
            ),
            ConversationSourceEvent(
                content=Content(
                    role="user",
                    parts=[Part(text= "Thanks for the coffee!")]
                )
            )
        ]
    ),
    generated_memories=[]
)

Prospettiva della memoria

Per impostazione predefinita, i ricordi vengono generati in prima persona (ad es. "Utilizzo Memory Bank per la gestione della memoria"). Puoi configurare Memory Bank per generare contenuti in terza persona (ad es. "L'utente utilizza Memory Bank per la gestione della memoria") utilizzando il parametro enable_third_person_memories.

Dizionario

customization_config = {
  "enable_third_person_memories": True
}

Basato sulla classe

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig

customization_config = CustomizationConfig(
    enable_third_person_memories=True
)

Personalizzazione del consolidamento

Durante il consolidamento, Memory Bank determina come integrare le informazioni appena acquisite nel set di ricordi esistente. Memory Bank valuta se AGGIUNGERE nuovi ricordi, AGGIORNARE quelli esistenti con un contesto aggiuntivo o ELIMINARE quelli obsoleti.

Per garantire ricordi di alta qualità e confermati, Memory Bank può analizzare facoltativamente la cronologia di un ricordo per distinguere le tendenze a lungo termine dagli outlier una tantum.

Per impostazione predefinita, Memory Bank confronta le nuove informazioni solo con lo snapshot più recente di una memoria candidata (una "revisione della memoria"). Per aumentare la profondità di questa analisi, configura il parametro revisions_per_candidate_count. Questo parametro definisce quante revisioni precedenti di ogni "memoria candidata" (il record specifico in fase di valutazione per un aggiornamento) vengono prese in considerazione da Memory Bank durante il consolidamento.

Dizionario

customization_config = {
  "consolidation_customization": {
    "revisions_per_candidate_count": 10
  }
}

Basato sulla classe

from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
from vertexai.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig

customization_config = CustomizationConfig(
    consolidation_customization=ConsolidationConfig(
      revisions_per_candidate_count=10
    )
)

L'aumento di revisions_per_candidate_count comporta ricordi più coerenti e confermati, in quanto tiene conto della ripetizione delle informazioni acquisite. Tuttavia, un conteggio più elevato aumenta il consumo di token durante il processo di consolidamento.

Configurazione della ricerca di somiglianze

La configurazione della ricerca di similarità controlla quale modello di incorporamento viene utilizzato dalla tua istanza per la ricerca di similarità. La ricerca di similarità viene utilizzata per identificare quali ricordi devono essere candidati per il consolidamento e per il recupero dei ricordi basato sulla ricerca di similarità. Se questa configurazione non viene fornita, Memory Bank utilizza text-embedding-005 come modello predefinito.

Se prevedi che le conversazioni degli utenti siano in lingue diverse dall'inglese, utilizza un modello che supporti più lingue, ad esempio gemini-embedding-001 o text-multilingual-embedding-002, per migliorare la qualità del recupero.

Dizionario

memory_bank_config = {
    "similarity_search_config": {
        "embedding_model": "EMBEDDING_MODEL",
    }
}

Basato sulla classe 

from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig as SimilaritySearchConfig

memory_bank_config = MemoryBankConfig(
    similarity_search_config=SimilaritySearchConfig(
        embedding_model="EMBEDDING_MODEL"
    )
)

Sostituisci quanto segue:

  • EMBEDDING_MODEL: il modello di text embedding di Google da utilizzare per la ricerca di similarità, nel formato projects/{project}/locations/{location}/publishers/google/models/{model}.

Configurazione della generazione

La configurazione della generazione controlla quale LLM viene utilizzato per la generazione di ricordi, inclusa l'estrazione di ricordi e il consolidamento di nuovi ricordi con quelli esistenti.

Memory Bank utilizza gemini-2.5-flash come modello predefinito. Per le regioni in cui Gemini regionale non è disponibile, viene utilizzato l'endpoint globale.

Dizionario

memory_bank_config = {
  "generation_config": {
    "model": "LLM_MODEL",
  }
}

Basato sulla classe 

from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigGenerationConfig as GenerationConfig

memory_bank_config = MemoryBankConfig(
  generation_config=GenerationConfig(
    model="LLM_MODEL"
  )
)

Sostituisci quanto segue:

  • LLM_MODEL: il modello Google LLM da utilizzare per estrarre e consolidare i ricordi, nel formato projects/{project}/locations/{location}/publishers/google/models/{model}.

Configurazione della durata (TTL)

La configurazione TTL controlla il modo in cui Memory Bank deve impostare dinamicamente il tempo di scadenza dei ricordi. Una volta trascorso il periodo di scadenza, i ricordi non saranno più disponibili per il recupero e verranno eliminati.

Se la configurazione non viene fornita, il tempo di scadenza non verrà impostato dinamicamente per i ricordi creati o aggiornati, quindi i ricordi non scadranno a meno che il tempo di scadenza non venga impostato manualmente.

Sono disponibili due opzioni per la configurazione del TTL:

  • TTL predefinito: il TTL verrà applicato a tutte le operazioni che creano o aggiornano una memoria, incluse UpdateMemory, CreateMemory e GenerateMemories.

    Dizionario

    memory_bank_config = {
  "ttl_config": {
      "default_ttl": f"TTLs"
  }
}

    Basato sulla classe 

    from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfig as TtlConfig

memory_bank_config = MemoryBankConfig(
  ttl_config=TtlConfig(
      default_ttl=f"TTLs"
  )
)

    Sostituisci quanto segue:

    • TTL: La durata in secondi del TTL. Per le informazioni salvate aggiornate, l'ora di scadenza appena calcolata (ora + TTL) sovrascriverà l'ora di scadenza precedente.

  • TTL granulare (per operazione): il TTL viene calcolato in base all'operazione che ha creato o aggiornato la memoria. Se non è impostato per una determinata operazione, l'operazione non aggiornerà la data di scadenza del ricordo.

    Dizionario

    memory_bank_config = {
  "ttl_config": {
      "granular_ttl": {
          "create_ttl": f"CREATE_TTLs",
          "generate_created_ttl": f"GENERATE_CREATED_TTLs",
          "generate_updated_ttl": f"GENERATE_UPDATED_TTLs"
      }
  }
}

    Basato sulla classe 

    from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfig as TtlConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigTtlConfigGranularTtlConfig as GranularTtlConfig

memory_bank_config = MemoryBankConfig(
  ttl_config=TtlConfig(
      granular_ttl_config=GranularTtlConfig(
          create_ttl=f"CREATE_TTLs",
          generate_created_ttl=f"GENERATE_CREATED_TTLs",
          generate_updated_ttl=f"GENERATE_UPDATED_TTLs",
      )
  )
)

    Sostituisci quanto segue:

    • CREATE_TTL: La durata in secondi del TTL per i ricordi creati utilizzando CreateMemory.
    • GENERATE_CREATED_TTL: La durata in secondi del TTL per i ricordi creati utilizzando GenerateMemories.
    • GENERATE_UPDATED_TTL: La durata in secondi del TTL per le informazioni salvate aggiornate utilizzando GenerateMemories. La data di scadenza appena calcolata (ora + TTL) sovrascriverà la data di scadenza precedente del ricordo.

Passaggi successivi

Guida rapida

Inizia a utilizzare l'API Memory Bank per gestire i ricordi a lungo termine.

Guida rapida

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