Per utilizzare Agent Platform Memory Bank, devi prima creare e configurare un'istanza di Memory Bank. 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 configurare un'istanza di Memory Bank nella console Google Cloud o con l'SDK Agent Platform.
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. Il PROJECT_NUMBER viene creato automaticamente in fase di creazione del progetto, mentre il PROJECT_ID viene creato da te o da chiunque abbia creato il progetto. Per configurare un progetto:
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.
Ottieni le autorizzazioni richieste
Per ottenere le autorizzazioni necessarie per utilizzare Memory Bank, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:
-
Crea o aggiorna un'istanza di Memory Bank:
Agent Platform User (
roles/aiplatform.user) -
Leggere, scrivere o generare memorie:
Agent Platform Memory Bank User Role (
roles/aiplatform.memoryUser)
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 alla banca della memoria da un agente di cui è stato eseguito il deployment su Google Kubernetes Engine (GKE) o Cloud Run, assicurati che il tuo account di servizio disponga delle autorizzazioni necessarie per leggere, scrivere o generare memorie. L'agente di servizio del motore di ragionamento dispone già delle autorizzazioni necessarie per leggere, scrivere e generare memorie, quindi le richieste in uscita da Agent Runtime dovrebbero già avere l'autorizzazione per accedere a Memory Bank.
Installa 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 (ad esempio Colaboratory).
Installa l'SDK Agent Platform:
pip install google-cloud-agentplatform>=2.0.1Autenticazione
Segui le istruzioni riportate in Autenticati in Gemini Enterprise Agent Platform.
Configura un client SDK Agent Platform
Esegui il seguente codice per configurare un client SDK Agent Platform:
SDK Agent Platform
import agentplatform
client = agentplatform.Client(
project="PROJECT_ID",
location="LOCATION",
)
dove
PROJECT_IDè l'ID progetto Google Cloud in cui sviluppi ed esegui il deployment degli agenti,LOCATIONè una delle regioni supportate per Memory Bank.
Endpoint multiregionali e globali
Memory Bank supporta endpoint multiregionali e globali:
- Per le istanze globali, imposta la località su
global. - Per le istanze multiregionali, imposta la località su
usoeu.
Per accoppiare un'istanza multiregionale con un runtime ADK regionale, consulta Utilizza un Memory Bank multiregionale con un runtime regionale.
Crea o aggiorna un'istanza di Memory Bank
Per iniziare a utilizzare Memory Bank, devi prima avere un'istanza di Memory Bank. Se non hai ancora un'istanza, puoi crearne una con la configurazione predefinita nella console Google Cloud o con l'SDK Agent Platform.
Console
Le istanze di Memory Bank autonome vengono visualizzate nella pagina Memory Bank della console Google Cloud (gli agenti di cui è stato eseguito il deployment vengono visualizzati nella pagina Deployment).
Nella console Google Cloud , vai alla pagina Memory Bank della piattaforma agente.
Fai clic su Crea archivio di memoria.
Inserisci un Nome visualizzato, seleziona una Regione e, facoltativamente, inserisci una Descrizione.
Seleziona un'opzione di crittografia (una Google-owned and Google-managed encryption key o una chiave Cloud Key Management Service). Non puoi modificare le impostazioni della regione o della crittografia dopo aver creato l'istanza.
Fai clic su Crea. Agent Platform crea l'istanza di Memory Bank con le impostazioni di memoria predefinite e apre la scheda Configurazione.
(Facoltativo) Fai clic su Collega a un agente nella barra delle azioni per visualizzare i comandi di installazione e il codice Python precompilato con il progetto, la regione e l'ID Memory Bank nelle schede Utilizza con ADK (per Agent Development Kit (ADK)) e Recupera.
Per modificare le informazioni di base, modificare le etichette o eliminare un'istanza autonoma esistente dall'elenco Memory Bank, fai clic sul menu Altre azioni () per l'istanza e seleziona Modifica informazioni di base, Modifica etichette o Elimina.
SDK Agent Platform
# Create the resource
memory_bank = client.memory_banks.create(
config={
"display_name": "My Memory Bank",
}
)
# Optionally, print out the Memory Bank resource name. You need the
# resource name to interact with your Memory Bank instance later.
print(memory_bank.name)
Se vuoi personalizzare la configurazione del comportamento della tua istanza Memory Bank nuova o esistente, consulta Configura l'istanza Memory Bank. Ad esempio, puoi specificare quali informazioni Memory Bank considera significative da rendere persistente.
Una volta creata un'istanza di Memory Bank, puoi utilizzare il nome dell'istanza per leggere o scrivere memorie. Ad esempio:
# Generate memories using your Memory Bank instance.
client.memory_banks.memories.generate(
# `name` should have the format `projects/.../locations/.../reasoningEngines/...`.
name=memory_bank.name,
...
)
Utilizzo con Agent Runtime
Sebbene Memory Bank possa essere utilizzato in qualsiasi runtime, puoi anche utilizzarlo con Agent Runtime per leggere e scrivere informazioni salvate dall'agente di cui hai eseguito il deployment.
Per eseguire il deployment di un agente su Agent Runtime con Memory Bank integrato, devi prima configurare 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 memorie in base alle necessità.
AdkApp
Se utilizzi il modello ADK di Agent Platform, l'agente utilizza VertexAiMemoryBankService per impostazione predefinita quando viene eseguito il deployment in Agent Runtime. Ciò significa che gli strumenti di memoria ADK leggono i ricordi da Memory Bank.
from google.adk.agents import Agent
from agentplatform.frameworks import AdkApp
# Develop an agent using the ADK template.
agent = Agent(...)
adk_app = AdkApp(
agent=adk_agent,
...
)
# Deploy the agent to Agent Runtime.
runtime = client.runtimes.create(
agent=adk_app,
config={
"staging_bucket": "STAGING_BUCKET",
"requirements": ["google-cloud-agentplatform[runtimes,adk]"],
# Optional.
**context_spec
}
)
# Update an existing Agent Runtime to add or modify the Runtime.
runtime = client.runtimes.update(
name=runtime.api_resource.name,
agent=adk_app,
config={
"staging_bucket": "STAGING_BUCKET",
"requirements": ["google-cloud-agentplatform[runtimes,adk]"],
# Optional.
**context_spec
}
)
Sostituisci quanto segue:
- STAGING_BUCKET: il tuo bucket Cloud Storage da utilizzare per la gestione temporanea di Agent Runtime.
Per provare Memory Bank con ADK, consulta la Guida rapida con ADK. Per scegliere strumenti di memoria, callback e runtime, consulta Utilizza Memory Bank con ADK.
Agente personalizzato
Puoi utilizzare Memory Bank con il tuo agente personalizzato di cui è stato eseguito il deployment su Agent Runtime. In questo caso, l'agente deve orchestrare le chiamate a Memory Bank per attivare le chiamate di generazione della memoria e di recupero della memoria.
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 il tuo agente su Agent Runtime, l'agente dispone già dell'autorizzazione per leggere e scrivere le memorie. Se utilizzi un service account cliente, devi concedere al account di servizio le autorizzazioni per leggere e scrivere memorie. Le autorizzazioni richieste dipendono dalle operazioni che l'agente deve essere in grado di eseguire. Se vuoi che l'agente recuperi e generi solo i ricordi,
aiplatform.memories.generate
e
aiplatform.memories.retrieve
sono sufficienti.
Nella console Google Cloud , puoi visualizzare e modificare le impostazioni di Memory Bank per un agente di cui è stato eseguito il deployment nella pagina Deployment aprendo l'agente e facendo clic su Configurazione del servizio > Memory Bank.
Utilizzo in tutti gli altri runtime
Se vuoi utilizzare Memory Bank in un ambiente diverso, come Cloud Run o Colab, crea una Memory Bank. Se non fornisci una configurazione, la banca di memoria viene creata con le impostazioni predefinite per la gestione della generazione e del recupero della memoria.
memory_bank = client.memory_banks.create()
Se hai già utilizzato Memory Bank, la creazione di una nuova istanza di Memory Bank dovrebbe richiedere solo pochi secondi. Se è la prima volta che utilizzi Memory Bank, l'operazione potrebbe richiedere più tempo (1-2 minuti).
Se vuoi configurare il comportamento, fornisci una configurazione della banca della memoria:
Crea
memory_bank = client.memory_banks.create(
managed_semantic_memory_config={
"generation_config": ...,
"unstructured_memory_configs": [...],
"structured_memory_configs": [...],
"similarity_search_config": ...,
"ttl_config": ...,
"disable_memory_revisions": False,
}
)
Aggiorna
Se vuoi modificare la configurazione di Memory Bank, puoi aggiornare l'istanza di Memory Bank.
memory_bank = client.runtimes.update(
# You can access the name using `memory_bank.name` for a MemoryBank object.
name="MEMORY_BANK_NAME",
config={
"context_spec": {
"memory_bank_config": {
"generation_config": ...,
"customization_configs": [...],
"structured_memory_configs": [...],
"similarity_search_config": ...,
"ttl_config": ...,
"disable_memory_revisions": False,
}
}
}
)
Sostituisci quanto segue:
- MEMORY_BANK_NAME: il nome della banca di memoria.
Deve essere nel formato
projects/.../locations/.../reasoningEngines/.... Consulta le regioni supportate per Memory Bank.
Puoi utilizzare Memory Bank in qualsiasi ambiente che disponga dell'autorizzazione per leggere e scrivere memorie. Ad esempio, per utilizzare Memory Bank con Cloud Run, concedi le autorizzazioni all'identità di 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 l'agente recuperi e generi solo memorie, aiplatform.memories.generate e aiplatform.memories.retrieve sono sufficienti.
Configura l'istanza di Memory Bank
Puoi configurare l'istanza di Memory Bank nella consoleGoogle Cloud o con l'SDK Agent Platform per personalizzare il modo in cui le memorie vengono generate e gestite. Se non fornisci una configurazione, Memory Bank utilizza le impostazioni predefinite per ogni opzione di configurazione.
Configura nella console Google Cloud
Per visualizzare o modificare le impostazioni di Memory Bank nella consoleGoogle Cloud (per la modifica è necessario aiplatform.reasoningEngines.update):
- Apri la visualizzazione di configurazione dell'istanza:
- Istanza Memory Bank autonoma: vai alla pagina Memory Bank, fai clic sull'istanza e apri la scheda Configurazione.
- Agente di cui è stato eseguito il deployment su Agent Runtime: vai alla pagina Deployment, fai clic sul tuo agente, quindi su Configurazione del servizio > Banca di memoria.
- Fai clic su Modifica in una delle seguenti sezioni per aggiornare le impostazioni, quindi fai clic su Salva:
- Dettagli (istanze autonome): modifica il nome visualizzato e la descrizione. La regione, la crittografia e le etichette sono di sola lettura in questo riquadro.
- Generazione: attiva o disattiva l'estrazione della memoria, scegli la prospettiva in prima o terza persona e configura gli argomenti della memoria gestiti o personalizzati (la console visualizza gli override a livello di ambito in modalità di sola lettura).
- Recupero: seleziona il modello di embedding per la ricerca di somiglianze. Puoi modificare il modello di embedding solo prima di archiviare il primo ricordo nell'istanza di Memory Bank.
- Conservazione: configura la scadenza della memoria (TTL) e la conservazione della cronologia delle revisioni della memoria.
- (Facoltativo) Per aggiungere o modificare gli schemi dei profili di Memory Profiler strutturati in un'istanza autonoma, fai clic su Schemi nella barra delle azioni (o nella sezione Generazione). Per maggiori dettagli, consulta Profili di memoria.
Configura con l'SDK Agent Platform
Puoi configurare le seguenti impostazioni della banca della memoria per la tua istanza con l'SDK Agent Platform:
- Configurazione della personalizzazione (
unstructured_memory_configs): configura il modo in cui i ricordi vengono estratti dai dati di origine e consolidati con quelli esistenti. - Configurazione della ricerca di somiglianze: specifica quale modello di embedding utilizza Memory Bank per la ricerca di somiglianze.
Il valore predefinito è
text-embedding-005. - Configurazione della generazione: configura l'LLM utilizzato da Memory Bank per la generazione della memoria. Il valore predefinito è
gemini-3.5-flash. - Configurazione TTL: configura il modo in cui il TTL viene impostato automaticamente per le informazioni salvate create o aggiornate. Il valore predefinito è nessun TTL.
L'esempio seguente mostra il Memory Bank predefinito:
Dizionario
managed_semantic_memory_config = {
"generation_config": {
# `gemini-3.5-flash` will be used to extract and consolidate memories.
"model": "projects/{PROJECT}/locations/{LOCATION}/publishers/google/models/gemini-3.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"
},
"unstructured_memory_configs": [
{
# Extract user information, preferences, key conversation details,
# and information that the user explicitly asked to be remembered.
"memory_topics": [
{"managed_memory_topic": {"managed_topic_enum": "USER_PERSONAL_INFO"}},
{"managed_memory_topic": {"managed_topic_enum": "USER_PREFERENCES"}},
{"managed_memory_topic": {"managed_topic_enum": "KEY_CONVERSATION_DETAILS"}},
{"managed_memory_topic": {"managed_topic_enum": "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 su classi
from agentplatform.types import ManagedSemanticMemoryConfig
from agentplatform.types import ManagedSemanticMemoryConfigGenerationConfig as GenerationConfig
from agentplatform.types import ManagedSemanticMemoryConfigSimilaritySearchConfig as SimilaritySearchConfig
from agentplatform.types import ManagedSemanticMemoryConfigTtlConfig as TtlConfig
from agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig
from agentplatform.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
managed_semantic_memory_config = ManagedSemanticMemoryConfig(
generation_config=GenerationConfig(
# `gemini-3.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-3.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"
),
unstructured_memory_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. L'esempio seguente mostra come creare un'istanza con una configurazione specifica di banchi di memoria.
memory_bank = client.memory_banks.create(
managed_semantic_memory_config=managed_semantic_memory_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 durante la configurazione dell'istanza. Utilizza le seguenti opzioni per personalizzare il comportamento:
- Configurazione degli argomenti della memoria: definisci il tipo di informazioni che Memory Bank deve considerare significative da rendere persistenti. Solo le informazioni che rientrano in uno di questi argomenti di memoria verranno conservate da Memory Bank.
- Fornire esempi few-shot: dimostra il comportamento previsto per l'estrazione della memoria in Memory Bank.
- Configurazione della prospettiva dei ricordi: configura se i ricordi devono essere generati in prima persona (impostazione predefinita) o in terza persona.
- Configurazione del consolidamento: configura il numero di revisioni della memoria che Memory Bank considera durante il consolidamento di ogni candidato alla memoria.
- Applicazione delle configurazioni di personalizzazione: applica
le configurazioni di personalizzazione all'istanza utilizzando
unstructured_memory_configs.
Puoi personalizzare il comportamento di estrazione della banca della memoria in due passaggi: indicazione e dimostrazione. Gli argomenti della memoria indicano alla Memory Bank quali informazioni conservare. I few-shot mostrano a Memory Bank quale tipo di informazioni deve generare una memoria specifica, aiutandolo ad apprendere i pattern, le sfumature e le frasi che ti aspetti che comprenda.
Se vuoi, puoi configurare un comportamento diverso per i vari 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 (applicato a tutti gli insiemi di chiavi di ambito) omettendo il campo scope_key. Questa configurazione verrà applicata a tutte le richieste che non hanno una configurazione che corrisponde esattamente alle chiavi di ambito di un'altra configurazione di personalizzazione.
Ad esempio, user_level_config si applica solo alle richieste GenerateMemories che utilizzano esattamente la chiave di ambito user_id (ovvero scope={"user_id":
"123"} senza chiavi aggiuntive). default_config si applica ad altre richieste:
Dizionario
user_level_config = {
"scope_keys": ["user_id"],
"memory_topics": [...],
"generate_memories_examples": [...]
}
default_config = {
"memory_topics": [...],
"generate_memories_examples": [...]
}
managed_semantic_memory_config = {
"unstructured_memory_configs": [
user_level_config,
default_config
]
}
Basato su classi
from agentplatform.types import ManagedSemanticMemoryConfig
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig
user_level_config = CustomizationConfig(
scope_keys=["user_id"],
memory_topics=[...],
generate_memories_examples=[...]
)
default_config = CustomizationConfig(
memory_topics=[...],
generate_memories_examples=[...]
)
managed_semantic_memory_config = ManagedSemanticMemoryConfig(
unstructured_memory_configs=[
user_level_config,
default_config,
]
)
Configurazione degli argomenti della memoria
Gli "argomenti della memoria" identificano le informazioni che Memory Bank considera significative e che, pertanto, devono 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 su classi
from agentplatform.types import ManagedTopicEnum from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic memory_topic = MemoryTopic( managed_memory_topic=ManagedMemoryTopic( managed_topic_enum=ManagedTopicEnum.USER_PERSONAL_INFO ) )Memory Bank supporta i seguenti argomenti gestiti:
- Informazioni sull'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 dell'utente (
USER_PREFERENCES): Mi piace, Non mi piace, stili o comportamenti tipici 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 i 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 di memorizzazione/eliminazione (
EXPLICIT_INSTRUCTIONS): informazioni che l'utente chiede esplicitamente all'agente di memorizzare o eliminare. Ad esempio, se l'utente dice "Ricorda che utilizzo principalmente Python", Memory Bank genera un ricordo come "Utilizzo principalmente Python".
- Informazioni sull'utente (
Argomenti personalizzati: l'etichetta e le istruzioni vengono definite da te durante la configurazione dell'istanza di Memory Bank. Verranno utilizzate 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 su classi
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic from agentplatform.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 su classi
from agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
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 utilizzare 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 su classi
from agentplatform.types import ManagedTopicEnum
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopic as MemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic as CustomMemoryTopic
from agentplatform.types import MemoryBankCustomizationConfigMemoryTopicManagedMemoryTopic as ManagedMemoryTopic
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 mostrare a Memory Bank il comportamento previsto per l'estrazione della memoria. Ad esempio, puoi fornire una conversazione di input di esempio e i ricordi che dovrebbero essere estratti da quella conversazione.
Ti consigliamo di utilizzare sempre few-shot con argomenti personalizzati in modo che Memory Bank possa apprendere il comportamento previsto. I few-shot sono facoltativi quando si utilizzano gli argomenti gestiti, poiché Memory Bank definisce esempi per ogni argomento. Mostra 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 su classi
from google.genai.types import Content, Part
from agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent as ConversationSourceEvent
from agentplatform.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 dovrebbero 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 su classi
from google.genai.types import Content, Part
from agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExample as GenerateMemoriesExample
from agentplatform.types import MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource as ConversationSource
from agentplatform.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 in modo che generi 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 su classi
from agentplatform.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 memoria esistente. Memory Bank valuta se AGGIUNGERE nuovi ricordi, AGGIORNARE quelli esistenti con un contesto aggiuntivo o ELIMINARE i ricordi obsoleti.
Per garantire ricordi di alta qualità e confermati, Memory Bank può facoltativamente analizzare la cronologia di un ricordo per distinguere le tendenze a lungo termine dai valori anomali una tantum.
Per impostazione predefinita, la banca dati della memoria confronta le nuove informazioni solo con l'istantanea 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 il numero di revisioni precedenti di ogni "memoria candidata" (il record specifico in fase di valutazione per un aggiornamento) che la Memory Bank prende in considerazione durante il consolidamento.
Dizionario
customization_config = {
"consolidation_config": {
"revisions_per_candidate_count": 10
}
}
Basato su classi
from agentplatform.types import MemoryBankCustomizationConfig as CustomizationConfig
from agentplatform.types import MemoryBankCustomizationConfigConsolidationConfig as ConsolidationConfig
customization_config = CustomizationConfig(
consolidation_config=ConsolidationConfig(
revisions_per_candidate_count=10
)
)
L'aumento di revisions_per_candidate_count si traduce in memorie più coerenti e
corroborate, tenendo conto della ripetizione delle informazioni acquisite.
Tuttavia, un conteggio più elevato aumenta il consumo di token durante il processo di consolidamento.
Applicazione delle configurazioni di personalizzazione
Per applicare le configurazioni di personalizzazione all'istanza di Memory Bank, forniscile nell'elenco unstructured_memory_configs di managed_semantic_memory_config:
Dizionario
managed_semantic_memory_config = {
"unstructured_memory_configs": [customization_config],
# Include other configurations (similarity search, generation, TTL)...
}
Basato su classi
from agentplatform.types import ManagedSemanticMemoryConfig
managed_semantic_memory_config = ManagedSemanticMemoryConfig(
unstructured_memory_configs=[customization_config],
# Include other configurations (similarity search, generation, TTL)...
)
Configurazione della ricerca di somiglianze
La configurazione della ricerca di somiglianze controlla quale modello di embedding viene utilizzato dalla tua istanza per la ricerca di somiglianze. La ricerca di similarità viene utilizzata per identificare quali memorie devono essere candidate per il consolidamento e per il recupero della memoria 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, come gemini-embedding-2, gemini-embedding-001 o text-multilingual-embedding-002, per migliorare la qualità del recupero.
Dizionario
similarity_search_config = {
"embedding_model": "EMBEDDING_MODEL",
}
Basato su classi
from agentplatform.types import ManagedSemanticMemoryConfigSimilaritySearchConfig as SimilaritySearchConfig
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 somiglianza, nel formato
projects/{project}/locations/{location}/publishers/google/models/{model}.
Configurazione della generazione
La configurazione di generazione controlla quale LLM viene utilizzato per generare i ricordi, tra cui l'estrazione dei ricordi e il consolidamento dei nuovi ricordi con quelli esistenti.
A partire dal 29 giugno 2026, Memory Bank utilizza gemini-3.5-flash per il modello predefinito. Le istanze create prima di questa data utilizzano gemini-2.5-flash.
Per le nuove istanze di Memory Bank che utilizzano il modello predefinito:
- Le istanze di Memory Bank nella località multiregionale
uso nelle regioni singoleus-*(ad esempio us-central1) utilizzano l'endpoint Gemini 3.5 multiregionaleus. - Le istanze di Memory Bank nella località multiregionale
euo nelle regioni singoleeu-*(ad esempio europe-west2) utilizzano l'endpoint Gemini 3.5 multiregionaleeu. - Tutte le altre regioni di Memory Bank utilizzano l'endpoint Gemini 3.5 globale.
Per le istanze di Memory Bank create prima del 29 giugno 2026 utilizzando il modello predefinito, Memory Bank utilizza l'endpoint Gemini global per le regioni che non hanno un endpoint Gemini 2.5 regionale disponibile.
Dizionario
generation_config = {
"model": "LLM_MODEL",
}
Basato su classi
from agentplatform.types import ManagedSemanticMemoryConfigGenerationConfig as GenerationConfig
generation_config = GenerationConfig(
model="LLM_MODEL"
)
Sostituisci quanto segue:
- LLM_MODEL: il modello LLM di Google 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 la scadenza dei ricordi. Trascorso il periodo di scadenza, i ricordi non saranno disponibili per il recupero e verranno eliminati.
Se la configurazione non viene fornita, la data di scadenza non verrà impostata dinamicamente per i ricordi creati o aggiornati, pertanto i ricordi non scadranno a meno che la data di scadenza non venga impostata manualmente.
Esistono due opzioni per la configurazione del TTL:
TTL predefinito: il TTL verrà applicato a tutte le operazioni che creano o aggiornano una memoria, tra cui
UpdateMemory,CreateMemoryeGenerateMemories.Dizionario
ttl_config = { "default_ttl": f"TTLs" }Basato su classi
from agentplatform.types import ManagedSemanticMemoryConfigTtlConfig as TtlConfig ttl_config = TtlConfig( default_ttl=f"TTLs" )Sostituisci quanto segue:
- TTL: la durata in secondi del TTL. Per le informazioni salvate aggiornate, la data di scadenza appena calcolata (ora + TTL) sovrascriverà la data di scadenza precedente della memoria.
TTL granulare (per operazione): il TTL viene calcolato in base all'operazione che ha creato o aggiornato la memoria. Se non viene impostato per una determinata operazione, l'operazione non aggiornerà la data di scadenza della memoria.
Dizionario
ttl_config = { "granular_ttl": { "create_ttl": f"CREATE_TTLs", "generate_created_ttl": f"GENERATE_CREATED_TTLs", "generate_updated_ttl": f"GENERATE_UPDATED_TTLs" } }Basato su classi
from agentplatform.types import ManagedSemanticMemoryConfigTtlConfig as TtlConfig from agentplatform.types import ManagedSemanticMemoryConfigTtlConfigGranularTtlConfig as GranularTtlConfig 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 le informazioni salvate create utilizzando
CreateMemory. - GENERATE_CREATED_TTL: la durata in secondi del TTL per le informazioni salvate create 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 della memoria.
- CREATE_TTL: la durata in secondi del TTL per le informazioni salvate create utilizzando
Passaggi successivi
Guida rapida all'API Memory Bank
Inizia a utilizzare l'API Memory Bank per gestire i ricordi a lungo termine.
Guida rapida con Agent Development Kit
Crea un agente ADK che ricorda le preferenze dell'utente.