Agent Platform Memory Bank fournit aux agents que vous créez avec Agent Development Kit (ADK) une mémoire à long terme sur plusieurs sessions. Dans ce guide de démarrage rapide, vous allez exécuter un agent qui mémorise la température préférée d'un utilisateur au cours d'une session et la rappelle lors de la session suivante.
Ce guide de démarrage rapide vous guide tout au long des étapes suivantes :
- configurer votre environnement ;
- Créez une instance Memory Bank.
- Exécuter un agent ADK avec mémoire en local
- Vérifiez que l'agent se souvient de la préférence dans une nouvelle session.
Pour appeler Memory Bank directement sans ADK, consultez le guide de démarrage rapide de l'API Memory Bank. Pour choisir d'autres outils de mémoire, rappels ou environnements d'exécution, consultez Utiliser Memory Bank avec ADK.
Avant de commencer
- 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.
-
If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.
-
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.-
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.
-
If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.
-
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.- Configurez un environnement de développement Python.
-
Si vous utilisez un shell local, créez des identifiants d'authentification locaux pour votre compte utilisateur :
gcloud auth application-default login
Vous n'avez pas besoin de le faire si vous utilisez Cloud Shell.
Si une erreur d'authentification est renvoyée et que vous utilisez un fournisseur d'identité (IdP) externe, vérifiez que vous vous êtes connecté à la gcloud CLI avec votre identité fédérée.
Rôles requis
Pour obtenir les autorisations nécessaires pour créer une instance Memory Bank, et générer et récupérer des souvenirs, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :
- Créer ou mettre à jour une instance Memory Bank : utilisateur Agent Platform (`roles/aiplatform.user`)
- Lire, écrire ou générer des souvenirs : utilisateur de banque de mémoire (`roles/aiplatform.memoryUser`)
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.
Configurer votre environnement
Dans votre terminal, installez ADK et le SDK Agent Platform :
pip install --upgrade "google-adk[gcp]" "google-cloud-agentplatform>=2.0.1"Définissez les variables d'environnement lues par les scripts de ce guide de démarrage rapide :
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE export GOOGLE_CLOUD_PROJECT=PROJECT_ID export GOOGLE_CLOUD_LOCATION=globalRemplacez PROJECT_ID par l'ID du projet Google Cloud .
Ce guide de démarrage rapide utilise le point de terminaison global. Pour utiliser un emplacement régional ou multirégional, remplacez
globalpar l'un des emplacements compatibles. Si vous avez besoin de clés de chiffrement gérées par le client (CMEK), utilisez un emplacement régional ou multirégional, car les CMEK ne sont pas disponibles avec le point de terminaison global.Exécutez le reste de ce guide de démarrage rapide dans la même session de terminal et le même répertoire afin que les scripts puissent lire ces variables.
Créer une instance de banque de mémoire
Créez un fichier nommé
create_memory_bank.pyavec le code suivant :import os import agentplatform client = agentplatform.Client( project=os.environ["GOOGLE_CLOUD_PROJECT"], location=os.environ["GOOGLE_CLOUD_LOCATION"], ) memory_bank = client.memory_banks.create( config={"display_name": "Memory Bank quickstart"} ) # Print only the instance ID, for example 1234567890. print(memory_bank.name.split("/")[-1])Exécutez le script et enregistrez l'ID d'instance dans la variable d'environnement
MEMORY_BANK_ID:export MEMORY_BANK_ID=$(python create_memory_bank.py)S'il s'agit de votre première instance de banque de mémoire, la création peut prendre une à deux minutes.
Vérifiez que la variable contient l'ID de l'instance :
echo $MEMORY_BANK_IDLe résultat est un ID tel que
1234567890. Si la sortie est vide ou renvoie une erreur401ou403, vérifiez vos rôles requis et exécutezgcloud auth application-default login. Si une nouvelle instanceglobalrenvoie une erreur403temporaire lors de la première utilisation, attendez 30 secondes, puis exécutez à nouveau le script.
Exécuter un agent avec mémoire activée
Le script de cette section exécute deux sessions pour le même utilisateur. Lors de la première session, l'utilisateur indique une préférence de température. Lors de la deuxième session, l'agent récupère cette préférence dans la banque de mémoire.
Procédez comme suit :
Créez un répertoire nommé
memory_agent:mkdir memory_agentCréez un fichier nommé
memory_agent/agent.pyavec le code suivant. Le code lit l'ID de votre projet, de votre emplacement et de votre instance à partir des variables que vous avez définies dans Configurer votre environnement et Créer une instance Memory Bank. Vous n'avez pas besoin de modifier le code.import asyncio import os import agentplatform from google import adk from google.adk.agents.callback_context import CallbackContext from google.adk.memory import VertexAiMemoryBankService from google.adk.sessions import InMemorySessionService from google.adk.tools.preload_memory_tool import PreloadMemoryTool from google.genai import types PROJECT_ID = os.environ["GOOGLE_CLOUD_PROJECT"] LOCATION = os.environ["GOOGLE_CLOUD_LOCATION"] MEMORY_BANK_ID = os.environ["MEMORY_BANK_ID"] # Memory Bank scopes memories to this app name and user ID. APP_NAME = "memory_agent" USER_ID = "quickstart_user" async def generate_memories_callback( callback_context: CallbackContext, ) -> None: # Send the latest turn to Memory Bank and wait until memory generation # finishes, so that the next session can retrieve the new memory. await callback_context.add_events_to_memory( events=callback_context.session.events[-5:], custom_metadata={"wait_for_completion": True}, ) return None root_agent = adk.Agent( model="gemini-3.5-flash", name="memory_agent", instruction=( "You are a vehicle voice agent that controls in-vehicle settings. " "Use what you know about the user's preferences. " "If you don't know the user's preferred temperature, ask for it. " "Limit responses to under 30 words." ), tools=[PreloadMemoryTool()], after_agent_callback=generate_memories_callback, ) memory_service = VertexAiMemoryBankService( project=PROJECT_ID, location=LOCATION, agent_engine_id=MEMORY_BANK_ID, ) session_service = InMemorySessionService() runner = adk.Runner( agent=root_agent, app_name=APP_NAME, session_service=session_service, memory_service=memory_service, ) async def send_message(session_id: str, text: str) -> None: print(f"User: {text}") message = types.Content(role="user", parts=[types.Part(text=text)]) async for event in runner.run_async( user_id=USER_ID, session_id=session_id, new_message=message ): if event.is_final_response() and event.content: print(f"Agent: {event.content.parts[0].text}") async def main() -> None: print("--- Session 1: share a preference ---") session = await session_service.create_session( app_name=APP_NAME, user_id=USER_ID ) await send_message(session.id, "Can you fix the temperature?") await send_message(session.id, "I'm comfortable at 71 degrees.") print("--- Session 2: recall the preference ---") session = await session_service.create_session( app_name=APP_NAME, user_id=USER_ID ) await send_message(session.id, "Fix the temperature.") print("--- Memories stored in Memory Bank ---") client = agentplatform.Client(project=PROJECT_ID, location=LOCATION) memory_bank_name = ( f"projects/{PROJECT_ID}/locations/{LOCATION}" f"/reasoningEngines/{MEMORY_BANK_ID}" ) results = client.memory_banks.memories.retrieve( name=memory_bank_name, scope={"app_name": APP_NAME, "user_id": USER_ID}, ) for retrieved_memory in results.page: print(f"* {retrieved_memory.memory.fact}") if __name__ == "__main__": asyncio.run(main())Exécutez le script :
python memory_agent/agent.pyLe rappel attend que la génération de la mémoire se termine après chaque tour, de sorte que la mémoire soit disponible au début de la deuxième session.
Vérifier que l'agent se souvient
Une fois l'exécution du script terminée, les deux conversations et la mémoire stockée s'affichent dans votre terminal. Comparez ce résultat aux exemples suivants pour vérifier que l'agent a mémorisé la préférence dans une nouvelle session.
Lors de la première session, l'agent ne dispose d'aucune information mémorisée sur l'utilisateur. Il demande donc une température :
--- Session 1: share a preference ---
User: Can you fix the temperature?
Agent: Sure. What temperature would you like?
User: I'm comfortable at 71 degrees.
Agent: Okay, I've set the temperature to 71 degrees.
Lors de la deuxième session, l'agent récupère les informations mémorisées dans Memory Bank et règle la température sur 71 degrés sans demander. La mémoire stockée apparaît à la fin du résultat :
--- Session 2: recall the preference ---
User: Fix the temperature.
Agent: Okay, I've set the temperature to 71 degrees, as you prefer.
--- Memories stored in Memory Bank ---
* I like the temperature to be 71 degrees.
La formulation des réponses et des souvenirs de l'agent varie en fonction des modèles utilisés par l'agent et la banque de mémoire.
Facultatif : Discuter avec votre agent dans ADK Web
ADK Web est une interface basée sur un navigateur qui permet de tester les agents pendant le développement.
Dans la même session de terminal, à partir du répertoire contenant le répertoire
memory_agent, exécutez la commande suivante :adk web --memory_service_uri=agentengine://$MEMORY_BANK_ID memory_agentDans votre navigateur, ouvrez
http://localhost:8000?userId=quickstart_user.Le paramètre de requête
userIdcorrespond à l'ID utilisateur dans le script. L'agent peut donc récupérer la mémoire créée par le script.Envoyez le message
Fix the temperature.et vérifiez que l'agent règle la température sur 21 degrés sans demander de confirmation. L'agent utilise la préférence que le script a stockée dans Exécuter un agent avec mémoire.Pour arrêter ADK Web, appuyez sur Ctrl+C dans le terminal.
Effectuer un nettoyage
Pour éviter que les ressources utilisées sur cette page ne soient facturées sur votre compte Google Cloud , vous pouvez supprimer le projet Google Cloud. Sinon, supprimez les ressources individuelles :
Créez un fichier nommé
clean_up.pyavec le code suivant :import os import agentplatform project = os.environ["GOOGLE_CLOUD_PROJECT"] location = os.environ["GOOGLE_CLOUD_LOCATION"] memory_bank_id = os.environ["MEMORY_BANK_ID"] client = agentplatform.Client(project=project, location=location) client.memory_banks.delete( name=f"projects/{project}/locations/{location}/reasoningEngines/{memory_bank_id}", force=True, )Exécutez le script pour supprimer l'instance Memory Bank :
python clean_up.pySupprimez les fichiers locaux que vous avez créés :
rm -r memory_agent create_memory_bank.py clean_up.py
Étapes suivantes
Guide de démarrage rapide de l'API Memory Bank
Premiers pas avec l'API Memory Bank pour gérer les informations mémorisées à long terme.
Utiliser Memory Bank avec ADK
Choisissez des rappels, des outils et des environnements d'exécution pour l'ADK.