Agent Development Kit (ADK) connecte les agents à Agent Platform Memory Bank via VertexAiMemoryBankService, une implémentation de l'interface BaseMemoryService d'ADK. Ce document explique comment choisir un outil de rappel et de récupération de mémoire, et comment connecter le service de mémoire dans chaque environnement d'exécution ADK.
Pour exécuter d'abord un exemple complet, consultez le guide de démarrage rapide de 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.-
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.
- Installez ADK et le SDK Agent Platform :
pip install --upgrade "google-adk[gcp]" "google-cloud-agentplatform>=2.0.1"
- Créez une instance Memory Bank dans la console Google Cloud ou avec le SDK Agent Platform. Sur la page Memory Bank, cliquez sur Associer à un agent > Utiliser avec ADK pour obtenir un code de configuration prérempli. Ignorez cette étape si Agent Runtime crée l'instance pour vous.
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.
Fonctionnement des composants ADK avec Memory Bank
Un agent ADK utilise les composants suivants pour lire et écrire des infos mémorisées :
| Composant | Rôle | Obligatoire |
|---|---|---|
| Instance Memory Bank | Stocke et consolide les souvenirs. | Oui |
VertexAiMemoryBankService |
Connecte votre agent à Memory Bank en tant que service de mémoire ADK. | Oui |
| Service de session | Stocke l'historique des conversations. Vous pouvez utiliser n'importe quel service de session ADK. | Oui |
| Outil de récupération de mémoire | Récupère les souvenirs de l'agent. Consultez Récupérer des souvenirs à l'aide d'un outil. | Pour lire les informations mémorisées |
| Rappel de génération de mémoire | Envoie les événements de conversation à Memory Bank après la réponse de l'agent. Consultez Générer des souvenirs avec un rappel. | Écrire des souvenirs |
Exécuteur ADK ou AdkApp |
Il orchestre l'agent, les services, les outils et les rappels. | Oui |
Le schéma suivant montre comment ces composants interagissent à chaque tour lorsqu'un agent utilise PreloadMemoryTool et un rappel de mémoire :
Memory Bank limite chaque information mémorisée à l'ID utilisateur et au nom de l'application qui exécute votre agent, sous la forme {"user_id": USER_ID, "app_name": APP_NAME}. Seules les requêtes avec le même ID utilisateur et le même nom d'application récupèrent ces souvenirs.
Générer des informations mémorisées avec un rappel
Un rappel de génération de mémoire envoie les événements de conversation à Memory Bank. Memory Bank extrait des informations mémorisées de ces événements et les consolide avec les informations mémorisées existantes. Choisissez une méthode en fonction de la fréquence à laquelle vous traitez les événements :
| Méthode | Événements envoyés | Cas d'utilisation |
|---|---|---|
callback_context.add_events_to_memory |
Un sous-ensemble d'événements que vous sélectionnez | Recommended. Traitez les événements de manière incrémentielle, par exemple après chaque tour. |
callback_context.add_session_to_memory |
Tous les événements de la session | Appelez-la une fois à la fin d'une session pour éviter que les mêmes événements ne soient traités plusieurs fois. |
L'exemple suivant envoie les événements récents après chaque réponse de l'agent :
from google.adk.agents.callback_context import CallbackContext
async def generate_memories_callback(
callback_context: CallbackContext,
) -> None:
await callback_context.add_events_to_memory(
events=callback_context.session.events[-5:]
)
return None
Pour envoyer l'intégralité de la session, appelez await callback_context.add_session_to_memory() dans un rappel à la fin de la session.
Par défaut, VertexAiMemoryBankService envoie des événements à l'aide de l'ingestion d'événements. Pour attendre que la génération de mémoire se termine dans les tests ou les démonstrations, transmettez custom_metadata={"wait_for_completion": True} à add_events_to_memory.
Récupérer des souvenirs avec un outil
Un outil de récupération de la mémoire contrôle quand l'agent récupère les souvenirs et comment ils sont intégrés au prompt. Choisissez l'un des outils suivants :
| Outil | Quand les informations mémorisées sont récupérées | Cas d'utilisation |
|---|---|---|
PreloadMemoryTool |
Au début de chaque tour. Les souvenirs sont injectés dans le contexte de la requête du modèle avant le tour de l'utilisateur actuel. | Établir un contexte de référence sur l'utilisateur à chaque tour. |
LoadMemoryTool |
Lorsque le modèle décide que des souvenirs sont nécessaires pour répondre à la requête. | Laissez le modèle décider quand les infos mémorisées sont pertinentes. |
FunctionTool personnalisé |
Lorsque le modèle appelle votre outil, guidé par la description de l'outil. | Donnez à l'agent des instructions sur le moment où il doit récupérer des souvenirs. |
L'exemple suivant crée un agent qui utilise PreloadMemoryTool et le rappel de la section précédente :
from google import adk
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
agent = adk.Agent(
model="gemini-3.5-flash",
name="stateful_agent",
instruction="You are a vehicle voice agent. Limit responses to 30 words.",
tools=[PreloadMemoryTool()],
after_agent_callback=generate_memories_callback,
)
Pour laisser le modèle décider quand récupérer les souvenirs, importez LoadMemoryTool depuis google.adk.tools.load_memory_tool et transmettez LoadMemoryTool() dans tools.
Pour écrire un outil de récupération personnalisé, appelez tool_context.search_memory à partir d'un appel d'outil de fonction :
from typing import Any
from google import adk
from google.adk.tools import FunctionTool, ToolContext
async def search_memories(query: str, tool_context: ToolContext) -> Any:
"""Query this tool when you need information about user preferences."""
return await tool_context.search_memory(query)
agent = adk.Agent(
model="gemini-3.5-flash",
name="stateful_agent",
instruction=(
"You are a vehicle voice agent. Before you change a setting, call "
"search_memories to look up the user's preferences. Limit responses "
"to 30 words."
),
tools=[FunctionTool(func=search_memories)],
after_agent_callback=generate_memories_callback,
)
Connecter le service de mémoire à votre environnement d'exécution
La façon dont vous connectez VertexAiMemoryBankService dépend de l'endroit où votre agent s'exécute. Sélectionnez votre environnement d'exécution :
Exécuteur local
Lorsque vous exécutez votre agent avec adk.Runner, créez le service de mémoire et transmettez-le à l'exécuteur :
import asyncio
import os
from google import adk
from google.adk.memory import VertexAiMemoryBankService
from google.adk.sessions import InMemorySessionService
from google.genai import types
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"
memory_service = VertexAiMemoryBankService(
project="PROJECT_ID",
location="LOCATION",
agent_engine_id="MEMORY_BANK_ID",
)
# You can use any ADK session service. This example keeps sessions in memory.
# To persist conversation history, use VertexAiSessionService with a
# Sessions instance instead.
session_service = InMemorySessionService()
runner = adk.Runner(
agent=agent,
app_name="APP_NAME",
session_service=session_service,
memory_service=memory_service,
)
async def main() -> None:
session = await session_service.create_session(
app_name="APP_NAME",
user_id="USER_ID",
)
message = types.Content(
role="user", parts=[types.Part(text="Can you fix the temperature?")]
)
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(event.content.parts[0].text)
asyncio.run(main())
Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projet Google Cloud , par exemple
my-project. - LOCATION : votre emplacement, par exemple
global. Consultez les emplacements compatibles ainsi que les points de terminaison mondiaux et multirégionaux pour Memory Bank. - MEMORY_BANK_ID : ID de l'instance Memory Bank, par exemple
456dansprojects/my-project/locations/us-central1/reasoningEngines/456. - APP_NAME : nom de l'application ADK, par exemple
my_agent. La banque de mémoire inclut le nom de l'application dans le champ d'application de la mémoire, de sorte que les informations mémorisées sont isolées entre les applications. - USER_ID : identifiant de votre utilisateur, par exemple
user-123. Les informations mémorisées générées à partir de cette session sont limitées à cet identifiant.
Agent Runtime sur Gemini Enterprise Agent Platform
Lorsque vous déployez un agent ADK sur Agent Runtime avec le modèle ADK (AdkApp), le modèle utilise VertexAiMemoryBankService par défaut. Vous pouvez créer l'instance Memory Bank et déployer l'agent en une seule étape :
import asyncio
import agentplatform
from agentplatform.frameworks import AdkApp
client = agentplatform.Client(
project="PROJECT_ID",
location="LOCATION",
)
adk_app = AdkApp(agent=agent)
# Create a resource with your agent deployed to Agent Runtime. The
# resource also includes an empty Memory Bank instance.
runtime_instance = client.runtimes.create(
agent=adk_app,
config={
"staging_bucket": "STAGING_BUCKET",
"requirements": ["google-cloud-agentplatform[runtimes,adk]"],
},
)
async def main() -> None:
session = await runtime_instance.async_create_session(
user_id="USER_ID"
)
async for event in runtime_instance.async_stream_query(
user_id="USER_ID",
session_id=session.get("id"),
message="Can you fix the temperature?",
):
print(event)
asyncio.run(main())
Pour déployer l'agent sur une ressource existante et conserver les mémoires existantes de la ressource, appelez plutôt client.runtimes.update :
runtime_instance = client.runtimes.update(
name="RUNTIME_NAME",
agent=adk_app,
config={
"staging_bucket": "STAGING_BUCKET",
"requirements": ["google-cloud-agentplatform[runtimes,adk]"],
},
)
Lorsque vous exécutez AdkApp localement, il utilise InMemoryMemoryService par défaut.
Pour utiliser Memory Bank localement, remplacez le service de mémoire :
from google.adk.memory import VertexAiMemoryBankService
def memory_bank_service_builder() -> VertexAiMemoryBankService:
return VertexAiMemoryBankService(
project="PROJECT_ID",
location="LOCATION",
agent_engine_id="MEMORY_BANK_ID",
)
adk_app = AdkApp(
agent=agent,
memory_service_builder=memory_bank_service_builder,
)
Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projet Google Cloud , par exemple
my-project. - LOCATION : région ou emplacement multirégional d'Agent Runtime, par exemple
us-central1. Seules les instancesVertexAiMemoryBankServiceautonomes sont compatibles avecglobal, pas avecclient.runtimes.create. Consultez la section Emplacements compatibles. - STAGING_BUCKET : URI du bucket Cloud Storage pour l'environnement de préproduction de votre Agent Runtime, par exemple
gs://my-staging-bucket. - USER_ID : identifiant de votre utilisateur, par exemple
user-123. - RUNTIME_NAME : nom de ressource de l'Agent Runtime existant, au format
projects/.../locations/.../reasoningEngines/.... - MEMORY_BANK_ID : ID de l'instance Memory Bank, par exemple
456dansprojects/my-project/locations/us-central1/reasoningEngines/456.
Cloud Run
Pour déployer votre agent sur Cloud Run, suivez la documentation de l'ADK et transmettez votre instance de banque de mémoire en tant que service de mémoire :
adk deploy cloud_run \
...
--memory_service_uri=agentengine://MEMORY_BANK_ID
Remplacez MEMORY_BANK_ID par l'ID de votre instance Memory Bank, par exemple 456. Pour tester l'agent déployé, consultez la documentation sur le déploiement d'ADK sur Cloud Run.
Google Kubernetes Engine (GKE)
Pour déployer votre agent sur GKE, suivez la documentation ADK et transmettez votre instance Memory Bank en tant que service de mémoire :
adk deploy gke \
...
--memory_service_uri=agentengine://MEMORY_BANK_ID
Remplacez MEMORY_BANK_ID par l'ID de votre instance Memory Bank, par exemple 456. Pour tester l'agent déployé, consultez la section Tester votre agent de la documentation sur le déploiement de l'ADK sur GKE.
ADK Web
ADK Web est une interface de navigateur locale permettant de tester et d'inspecter votre agent pendant le développement.
ADK Web lit votre projet et votre emplacement à partir de variables d'environnement. Exécutez les commandes suivantes dans votre terminal, à partir du répertoire contenant le dossier de votre agent :
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION
adk web --memory_service_uri=agentengine://MEMORY_BANK_IDRemplacez les éléments suivants :
- PROJECT_ID : ID de votre projet Google Cloud , par exemple
my-project. - LOCATION : votre emplacement, par exemple
global. Consultez les emplacements compatibles ainsi que les points de terminaison mondiaux et multirégionaux pour Memory Bank. - MEMORY_BANK_ID : ID de l'instance Memory Bank, par exemple
456.
Ouvrez ensuite http://localhost:8000 dans votre navigateur. Par défaut, ADK Web définit l'ID utilisateur sur user. Pour utiliser un autre ID utilisateur, ajoutez le paramètre de requête userId, par exemple http://localhost:8000?userId=USER_ID.
Utiliser une Memory Bank multirégionale avec un environnement d'exécution régional
Par défaut, lorsque vous utilisez l'environnement d'exécution avec la banque de mémoire intégrée, votre agent et la banque de mémoire sont déployés dans la même région. Pour conserver une banque de mémoire centralisée dans les déploiements régionaux, vous pouvez associer une banque de mémoire multirégionale (telle que us) à un environnement d'exécution régional (tel que us-central1).
Pour utiliser une banque de mémoire multirégionale, remplacez le compilateur de service de mémoire ADK par défaut afin qu'il pointe vers l'emplacement multirégional et l'ID d'instance :
import agentplatform
from agentplatform.frameworks import AdkApp
from google.adk.memory import VertexAiMemoryBankService
# Create the Memory Bank instance in a multi-region location.
client_mb = agentplatform.Client(
project="PROJECT_ID",
location="us",
)
memory_bank = client_mb.memory_banks.create()
memory_bank_id = memory_bank.name.split("/")[-1]
# Point the memory service to the multi-regional instance.
def memory_bank_service_builder() -> VertexAiMemoryBankService:
return VertexAiMemoryBankService(
project="PROJECT_ID",
location="us",
agent_engine_id=memory_bank_id,
)
adk_app = AdkApp(
agent=agent,
memory_service_builder=memory_bank_service_builder,
)
# Deploy the runtime to a specific region.
client_runtime = agentplatform.Client(
project="PROJECT_ID",
location="us-central1",
)
runtime_instance = client_runtime.runtimes.create(
agent=adk_app,
config={
"staging_bucket": "STAGING_BUCKET",
"requirements": ["google-cloud-agentplatform[runtimes,adk]"],
},
)
Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projet Google Cloud , par exemple
my-project. - STAGING_BUCKET : URI du bucket Cloud Storage pour l'environnement de préproduction de votre Agent Runtime, par exemple
gs://my-staging-bucket.
Pour supprimer ces ressources, supprimez l'environnement d'exécution et l'instance multirégionale.
Si vous supprimez une instance juste après une conversation, la requête peut échouer avec une erreur FAILED_PRECONDITION pendant que la génération de la mémoire se termine. Si cela se produit, attendez une minute, puis relancez la suppression.
client_runtime.runtimes.delete(
name=runtime_instance.api_resource.name,
force=True,
)
client_mb.memory_banks.delete(name=memory_bank.name, force=True)
Étapes suivantes
Guide de démarrage rapide d'Agent Development Kit
Créer un agent ADK qui mémorise les préférences de l'utilisateur