Utiliser Memory Bank avec ADK

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

  1. 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.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

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

    Go to project selector

  3. 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.

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

  5. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. 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.

    Enable the API

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

    Roles required to select or create a project

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

    Go to project selector

  7. 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.

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

  9. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. 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.

    Enable the API

  10. 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.

  11. Installez ADK et le SDK Agent Platform :
    pip install --upgrade "google-adk[gcp]" "google-cloud-agentplatform>=2.0.1"
  12. 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 456 dans projects/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 instances VertexAiMemoryBankService autonomes sont compatibles avec global, pas avec client.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 456 dans projects/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_ID

Remplacez les éléments suivants :

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

Créer un agent ADK qui mémorise les préférences de l'utilisateur

Guide

Découvrez comment générer des informations mémorisées dans Memory Bank.

Guide

Découvrez comment configurer la banque de mémoire.