Pour utiliser Agent Platform Memory Bank, vous devez d'abord créer et configurer une instance Gemini Enterprise Agent Platform. Cette instance gère vos souvenirs et peut être intégrée à vos agents sur différents runtimes.
Ce document explique comment configurer votre projet Google Cloud , installer les bibliothèques requises et créer ou mettre à jour une instance avec des configurations personnalisées telles que des thèmes et un TTL.
Commencer
Avant d'utiliser Memory Bank, vous devez configurer votre environnement.
Configurer votre projet Google Cloud
Chaque projet peut être identifié de deux manières : par son numéro ou par son ID. PROJECT_NUMBER est automatiquement généré lorsque vous créez le projet, tandis que PROJECT_ID est défini par vous ou par le créateur du projet. Pour configurer un projet :
- Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.
-
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.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.-
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.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.
Obtenir les rôles requis
Pour obtenir les autorisations nécessaires pour utiliser Memory Bank, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :
-
Tous : Utilisateur de la plate-forme Agent (
roles/aiplatform.user)
Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.
Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.
Si vous envoyez des requêtes à Memory Bank depuis un agent déployé sur Google Kubernetes Engine ou Cloud Run, assurez-vous que votre compte de service dispose des autorisations nécessaires. L'agent de service Reasoning Engine dispose déjà des autorisations nécessaires pour lire et écrire des souvenirs. Les requêtes sortantes d'Agent Runtime devraient donc déjà être autorisées à accéder à la banque de mémoire.
Installer les bibliothèques
Cette section suppose que vous avez configuré un environnement de développement Python ou que vous utilisez un environnement d'exécution avec un environnement de développement Python (tel que Colab).
Installez le SDK Agent Platform :
pip install google-cloud-aiplatform>=1.111.0Authentification
Suivez les instructions de la section S'authentifier sur Vertex AI.
Configurer un client SDK Agent Platform
Exécutez le code suivant pour configurer un client Agent Platform SDK :
SDK Agent Platform
import vertexai
client = vertexai.Client(
project="PROJECT_ID",
location="LOCATION",
)
Où :
PROJECT_IDcorrespond à l'ID de projet Google Cloud sous lequel vous développerez et déploierez des agents.LOCATIONest l'une des régions compatibles avec Memory Bank.
Créer ou mettre à jour une instance Agent Platform
Pour commencer à utiliser Memory Bank, vous devez d'abord disposer d'une instance Agent Platform. Si vous n'avez pas encore d'instance, vous pouvez la créer à l'aide de la configuration par défaut :
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)
Si vous souhaitez personnaliser la configuration du comportement de votre instance Memory Bank nouvelle ou existante, consultez Configurer votre instance Agent Platform pour Memory Bank. Par exemple, vous pouvez spécifier les informations que la Banque de mémoire considère comme importantes à conserver.
Votre instance Agent Platform est compatible avec les sessions et la Memory Bank prêtes à l'emploi. Aucun agent n'est déployé lorsque vous créez l'instance. Pour utiliser Agent Runtime, vous devez fournir l'agent à déployer lorsque vous créez ou mettez à jour votre instance Agent Platform.
Une fois que vous disposez d'une instance Agent Platform, vous pouvez utiliser son nom pour lire ou écrire des souvenirs. Exemple :
# 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,
...
)
Utiliser avec Agent Runtime
Bien que Memory Bank puisse être utilisée dans n'importe quel environnement d'exécution, vous pouvez également utiliser Memory Bank avec Agent Runtime pour lire et écrire des mémoires à partir de votre agent déployé.
Pour déployer un agent avec Memory Bank sur Agent Platform, commencez par configurer votre environnement pour Agent Runtime. Ensuite, préparez votre agent à être déployé sur Agent Runtime avec l'intégration de la mémoire. Votre agent déployé doit effectuer des appels pour lire et écrire des mémoires si nécessaire.
AdkApp
Si vous utilisez le modèle Agent Development Kit d'Agent Platform, l'agent utilise VertexAiMemoryBankService par défaut lorsqu'il est déployé sur Agent Platform. Cela signifie que les outils de mémoire de l'ADK lisent les souvenirs de Memory Bank.
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
}
)
Remplacez les éléments suivants :
- STAGING_BUCKET : bucket Cloud Storage à utiliser pour préparer votre Agent Runtime.
Pour en savoir plus sur l'utilisation de Memory Bank avec ADK, consultez le guide de démarrage rapide avec le kit de développement d'agent.
Agent personnalisé
Vous pouvez utiliser Memory Bank avec votre agent personnalisé déployé sur Agent Runtime. Dans ce cas, votre agent doit orchestrer les appels à la banque de mémoire pour déclencher les appels de génération de mémoire et de récupération de mémoire.
Votre application déployée dans Agent Runtime peut lire les variables d'environnement GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION et GOOGLE_CLOUD_AGENT_ENGINE_ID pour déduire le nom Agent Runtime de l'environnement :
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}"
Si vous utilisez l'agent de service par défaut pour votre agent sur Agent Runtime, votre agent est déjà autorisé à lire et à écrire des souvenirs. Si vous utilisez un compte de service client, vous devez accorder à votre compte de service les autorisations de lecture et d'écriture des souvenirs. Les autorisations requises dépendent des opérations que votre agent doit pouvoir effectuer. Si vous souhaitez uniquement que votre agent récupère et génère des souvenirs, aiplatform.memories.generate et aiplatform.memories.retrieve suffisent.
Utiliser dans tous les autres environnements d'exécution
Si vous souhaitez utiliser Memory Bank dans un autre environnement, comme Cloud Run ou Colab, créez un Agent Runtime sans fournir d'agent. Si vous ne fournissez pas de configuration, Memory Bank est créé avec les paramètres par défaut pour la gestion de la génération et de la récupération de la mémoire.
agent_engine = client.agent_engines.create()
Si vous avez déjà utilisé Agent Platform, la création d'une instance Agent Platform sans environnement d'exécution ne devrait prendre que quelques secondes. Si vous utilisez la plate-forme d'agent pour la première fois, cela peut prendre plus de temps (une à deux minutes).
Si vous souhaitez configurer le comportement, fournissez une configuration Memory Bank :
Créer
agent_engine = client.agent_engines.create(
config={
"context_spec": {
"memory_bank_config": ...
}
}
)
Mettre à jour
Si vous souhaitez modifier la configuration de votre Memory Bank, vous pouvez mettre à jour votre instance 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": ...
}
}
)
Remplacez les éléments suivants :
- RUNTIME_NAME : nom de l'environnement d'exécution de l'agent.
Il doit être au format
projects/.../locations/.../reasoningEngines/.... Consultez les régions compatibles pour Memory Bank.
Vous pouvez utiliser Memory Bank dans n'importe quel environnement autorisé à lire et à écrire des mémoires. Par exemple, pour utiliser Memory Bank avec Cloud Run, accordez à l'identité du service Cloud Run les autorisations de lecture et d'écriture des souvenirs. Les autorisations requises dépendent des opérations que votre agent doit pouvoir effectuer. Si vous souhaitez uniquement que votre agent récupère et génère des souvenirs, aiplatform.memories.generate et aiplatform.memories.retrieve suffisent.
Configurer votre instance Agent Platform pour Memory Bank
Vous pouvez configurer votre Memory Bank pour personnaliser la façon dont les souvenirs sont générés et gérés. Si vous ne fournissez pas de configuration, Memory Bank utilise les paramètres par défaut pour chaque type de configuration.
Vous pouvez configurer les paramètres de Memory Bank suivants pour votre instance :
- Configuration de la personnalisation : configure la façon dont les souvenirs sont extraits des données sources et consolidés avec les souvenirs existants.
- Configuration de la recherche de similarité : spécifie le modèle d'embedding que Memory Bank utilise pour la recherche de similarité.
La valeur par défaut est
text-embedding-005. - Configuration de la génération : configure le LLM que la banque de mémoire utilise pour la génération de mémoire. La valeur par défaut est
gemini-2.5-flash. - Configuration de la valeur TTL : configure la façon dont la valeur TTL est automatiquement définie pour les entrées de mémoire créées ou mises à jour. Par défaut, aucune valeur TTL n'est définie.
L'exemple suivant montre la banque de mémoire par défaut :
Dictionnaire
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
}
Basée sur les classes
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
)
Vous pouvez ajuster la configuration de la Memory Bank lorsque vous créez ou mettez à jour votre instance Agent Platform. L'exemple suivant montre comment créer ou mettre à jour une instance avec une configuration de Memory Bank spécifique.
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
}
}
)
Configuration de la personnalisation de la mémoire en langage naturel
Pour personnaliser la façon dont Memory Bank extrait les souvenirs en langage naturel, configurez le comportement d'extraction lorsque vous configurez votre instance. Utilisez les options suivantes pour personnaliser le comportement :
- Configuration des thèmes de mémoire : définissez le type d'informations que la Memory Bank doit considérer comme significatives pour les conserver. Seules les informations qui correspondent à l'un de ces thèmes de mémoire seront conservées par Memory Bank.
- Fournir des exemples few-shot : montrez le comportement attendu pour l'extraction de la mémoire vers la banque de mémoire.
- Configurer la perspective de la mémoire : configurez si les souvenirs doivent être générés à la première personne (par défaut) ou à la troisième personne.
- Configurer la consolidation : configurez le nombre de révisions de mémoire que la Banque de mémoire prend en compte lors de la consolidation de chaque mémoire candidate.
Vous pouvez personnaliser le comportement d'extraction de votre banque de mémoire en deux étapes : dire et montrer. Les thèmes de mémoire indiquent à la banque de mémoire quelles informations conserver. Les exemples de type "few-shot" montrent à la Memory Bank le type d'informations qui doivent entraîner une mémoire spécifique, ce qui l'aide à apprendre les schémas, les nuances et les expressions que vous attendez qu'elle comprenne.
Vous pouvez éventuellement configurer différents comportements pour différents niveaux de portée. Par exemple, les thèmes qui ont du sens pour les souvenirs au niveau de la session peuvent ne pas en avoir pour les souvenirs au niveau de l'utilisateur (sur plusieurs sessions). Pour configurer le comportement d'un certain sous-ensemble de souvenirs, définissez les clés de portée de la configuration de personnalisation. Seules les requêtes GenerateMemories qui incluent ces clés de portée utiliseront cette configuration. Vous pouvez également configurer le comportement par défaut (qui s'applique à tous les ensembles de clés de portée) en omettant le champ scope_key. Cette configuration s'appliquera à toutes les requêtes qui ne disposent pas d'une configuration correspondant exactement aux clés de portée d'une autre configuration de personnalisation.
Par exemple, user_level_config ne s'appliquerait qu'aux requêtes GenerateMemories qui utilisent exactement la clé de portée user_id (c'est-à-dire scope={"user_id":
"123"} sans clé supplémentaire). default_config s'appliquerait aux autres demandes :
Dictionnaire
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
]
}
Basée sur les classes
from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
user_level_config = CustomizationConfig(
scope_keys=["user_id"],
memory_topics=[...],
generate_memories_examples=[...]
)
Configurer les thèmes de la mémoire
Les "thèmes de mémoire" identifient les informations que Memory Bank considère comme importantes et qui doivent donc être conservées en tant que souvenirs générés. Memory Bank est compatible avec deux types de thèmes de mémoire :
Sujets gérés : le libellé et les instructions sont définis par Memory Bank. Il vous suffit d'indiquer le nom du thème géré. Par exemple,
Dictionnaire
memory_topic = { "managed_memory_topic": { "managed_topic_enum": "USER_PERSONAL_INFO" } }Basée sur les classes
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 ) )Memory Bank accepte les thèmes gérés suivants :
- Informations sur l'utilisateur (
USER_PERSONAL_INFO) : informations importantes sur l'utilisateur, comme son nom, ses relations, ses loisirs et ses dates importantes. Par exemple, "Je travaille chez Google" ou "Mon anniversaire de mariage est le 31 décembre". - Préférences de l'utilisateur (
USER_PREFERENCES) : préférences explicites ou implicites, styles ou motifs préférés. Par exemple, "Je préfère le siège du milieu". - Événements clés de la conversation et résultats des tâches (
KEY_CONVERSATION_DETAILS) : étapes ou conclusions importantes du dialogue. Par exemple, "J'ai réservé des billets d'avion aller-retour entre JFK et SFO. Je pars le 1er juin 2025 et reviens le 7 juin 2025." - Instructions explicites pour se souvenir ou oublier (
EXPLICIT_INSTRUCTIONS) : informations que l'utilisateur demande explicitement à l'agent de mémoriser ou d'oublier. Par exemple, si l'utilisateur dit "Souviens-toi que j'utilise principalement Python", Memory Bank génère un souvenir tel que "J'utilise principalement Python".
- Informations sur l'utilisateur (
Thèmes personnalisés : le libellé et les instructions sont définis par vous lorsque vous configurez votre instance Memory Bank. Elles seront utilisées dans la requête pour l'étape d'extraction de Memory Bank. Par exemple,
Dictionnaire
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.""" } }Basée sur les classes
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.""" ) )Lorsque vous utilisez des thèmes personnalisés, nous vous recommandons également de fournir des exemples few-shot montrant comment les souvenirs doivent être extraits de votre conversation.
La personnalisation vous permet d'utiliser n'importe quelle combinaison de thèmes de souvenirs. Par exemple, vous pouvez utiliser un sous-ensemble des thèmes de mémoire gérée disponibles :
Dictionnaire
customization_config = {
"memory_topics": [
{ "managed_memory_topic": { "managed_topic_enum": "USER_PERSONAL_INFO" } },
{ "managed_memory_topic": { "managed_topic_enum": "USER_PREFERENCES" } }
]
}
Basée sur les classes
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)
),
]
)
Vous pouvez également utiliser une combinaison de thèmes gérés et personnalisés (ou uniquement des thèmes personnalisés) :
Dictionnaire
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."""
}
}
]
}
Basée sur les classes
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."""
)
)
]
)
Exemples few-shot
Les exemples few-shot vous permettent de montrer à la Memory Bank le comportement attendu pour l'extraction de la mémoire. Par exemple, vous pouvez fournir un exemple de conversation et les souvenirs qui doivent être extraits de cette conversation.
Nous vous recommandons de toujours utiliser des few-shots avec des thèmes personnalisés pour que Memory Bank puisse apprendre le comportement souhaité. Les few-shots sont facultatifs lorsque vous utilisez des thèmes gérés, car la Memory Bank définit des exemples pour chaque thème. Montrez les conversations qui ne devraient pas générer de souvenirs en fournissant une liste generated_memories vide.
Par exemple, vous pouvez fournir des exemples few-shot qui montrent comment extraire les commentaires sur votre entreprise à partir des messages des clients :
Dictionnaire
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."
}
]
}
Basée sur les classes
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."
)
]
)
Vous pouvez également fournir des exemples de conversations qui ne doivent générer aucun souvenir en fournissant une liste vide pour le résultat attendu (generated_memories) :
Dictionnaire
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": []
}
Basée sur les classes
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=[]
)
Perspective de la mémoire
Par défaut, les souvenirs sont générés à la première personne (par exemple, "J'utilise Memory Bank pour gérer ma mémoire."). Vous pouvez configurer Memory Bank pour qu'il génère du contenu à la troisième personne (par exemple, "L'utilisateur utilise Memory Bank pour la gestion de la mémoire.") à l'aide du paramètre enable_third_person_memories.
Dictionnaire
customization_config = {
"enable_third_person_memories": True
}
Basée sur les classes
from vertexai.types import MemoryBankCustomizationConfig as CustomizationConfig
customization_config = CustomizationConfig(
enable_third_person_memories=True
)
Personnalisation de la consolidation
Lors de la consolidation, la Banque de mémoire détermine comment intégrer les nouvelles informations acquises à votre ensemble de souvenirs existant. La banque de mémoire évalue s'il faut AJOUTER de nouveaux souvenirs, METTRE À JOUR les souvenirs existants avec du contexte supplémentaire ou SUPPRIMER les souvenirs obsolètes.
Pour garantir des souvenirs corroborés et de haute qualité, Memory Bank peut éventuellement analyser l'historique d'un souvenir afin de distinguer les tendances à long terme des valeurs aberrantes ponctuelles.
Par défaut, la Memory Bank ne compare les nouvelles informations qu'à l'instantané le plus récent d'une mémoire candidate (une révision de mémoire). Pour approfondir cette analyse, configurez le paramètre revisions_per_candidate_count. Ce paramètre définit le nombre de révisions précédentes de chaque "mémoire candidate" (l'enregistrement spécifique évalué pour une mise à jour) que la banque de mémoire prend en compte lors de la consolidation.
Dictionnaire
customization_config = {
"consolidation_customization": {
"revisions_per_candidate_count": 10
}
}
Basée sur les classes
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'augmentation de revisions_per_candidate_count permet d'obtenir des souvenirs plus cohérents et corroborés en tenant compte de la répétition des informations ingérées.
Toutefois, un nombre plus élevé augmente la consommation de jetons lors du processus de consolidation.
Configuration de la recherche de similarités
La configuration de la recherche par similarité contrôle le modèle d'embedding utilisé par votre instance pour la recherche par similarité. La recherche de similarité permet d'identifier les souvenirs qui peuvent être consolidés et pour la récupération de souvenirs basée sur la recherche de similarité.
Si cette configuration n'est pas fournie, Memory Bank utilise text-embedding-005 comme modèle par défaut.
Si vous pensez que les conversations des utilisateurs seront dans des langues autres que l'anglais, utilisez un modèle qui prend en charge plusieurs langues, comme gemini-embedding-001 ou text-multilingual-embedding-002, pour améliorer la qualité de la récupération.
Dictionnaire
memory_bank_config = {
"similarity_search_config": {
"embedding_model": "EMBEDDING_MODEL",
}
}
Basée sur les classes
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"
)
)
Remplacez les éléments suivants :
- EMBEDDING_MODEL : modèle d'embedding textuel Google à utiliser pour la recherche par similarité, au format
projects/{project}/locations/{location}/publishers/google/models/{model}.
Configuration de génération
La configuration de génération contrôle le LLM utilisé pour générer des souvenirs, y compris pour extraire des souvenirs et consolider de nouveaux souvenirs avec des souvenirs existants.
Memory Bank utilise gemini-2.5-flash comme modèle par défaut. Pour les régions où Gemini n'est pas disponible, le point de terminaison mondial est utilisé.
Dictionnaire
memory_bank_config = {
"generation_config": {
"model": "LLM_MODEL",
}
}
Basée sur les classes
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfig as MemoryBankConfig
from vertexai.types import ReasoningEngineContextSpecMemoryBankConfigGenerationConfig as GenerationConfig
memory_bank_config = MemoryBankConfig(
generation_config=GenerationConfig(
model="LLM_MODEL"
)
)
Remplacez les éléments suivants :
- LLM_MODEL : modèle LLM Google à utiliser pour extraire et consolider les souvenirs, au format
projects/{project}/locations/{location}/publishers/google/models/{model}.
Configuration de la valeur TTL (Time to Live)
La configuration TTL contrôle la façon dont Memory Bank doit définir dynamiquement le délai d'expiration des souvenirs. Une fois leur durée de vie expirée, les souvenirs ne pourront plus être récupérés et seront supprimés.
Si la configuration n'est pas fournie, le délai d'expiration ne sera pas défini de manière dynamique pour les souvenirs créés ou modifiés. Par conséquent, les souvenirs n'expireront pas, sauf si leur délai d'expiration est défini manuellement.
Deux options s'offrent à vous pour configurer le TTL :
Valeur TTL par défaut : la valeur TTL sera appliquée à toutes les opérations qui créent ou mettent à jour une entrée de mémoire, y compris
UpdateMemory,CreateMemoryetGenerateMemories.Dictionnaire
memory_bank_config = { "ttl_config": { "default_ttl": f"TTLs" } }Basée sur les classes
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" ) )Remplacez les éléments suivants :
- TTL : durée en secondes de la valeur TTL. Pour les entrées de mémoire mises à jour, le nouveau délai d'expiration calculé (maintenant + TTL) remplacera le délai d'expiration précédent.
Valeur TTL précise (par opération) : la valeur TTL est calculée en fonction de l'opération qui a créé ou mis à jour la mémoire. Si elle n'est pas définie pour une opération donnée, l'opération ne met pas à jour le délai d'expiration du souvenir.
Dictionnaire
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" } } }Basée sur les classes
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", ) ) )Remplacez les éléments suivants :
- CREATE_TTL : durée en secondes de la valeur TTL pour les entrées de mémoire créées à l'aide de
CreateMemory. - GENERATE_CREATED_TTL : durée en secondes de la valeur TTL pour les entrées de mémoire créées à l'aide de
GenerateMemories. - GENERATE_UPDATED_TTL : durée en secondes de la valeur TTL pour les souvenirs mis à jour à l'aide de
GenerateMemories. La nouvelle date d'expiration calculée (maintenant + TTL) remplacera la date d'expiration précédente de l'entrée de mémoire.
- CREATE_TTL : durée en secondes de la valeur TTL pour les entrées de mémoire créées à l'aide de
Étapes suivantes
Guide de démarrage rapide de l'API Memory Bank
Faites vos premiers pas avec l'API Memory Bank pour gérer les souvenirs à long terme.
Démarrage rapide avec Agent Development Kit
Faites vos premiers pas avec Agent Development Kit (ADK).