Guide de démarrage rapide de Memory Bank avec ADK

Agent Platform Memory Bank permet à vos agents de gérer des informations mémorisées à long terme sur plusieurs sessions. Lorsqu'il est utilisé avec Agent Development Kit (ADK), votre agent peut orchestrer automatiquement les appels à Memory Bank pour stocker et récupérer des informations mémorisées en fonction des interactions de l'utilisateur.

Ce document explique comment créer un agent ADK, le configurer pour qu'il utilise Memory Bank et interagir avec lui pour générer des informations mémorisées et y accéder.

Pour savoir comment effectuer des appels directs à l'API sans ADK, consultez le guide de démarrage rapide de l'API Memory Bank.

Important : ADK utilise principalement des fonctions asynchrones. Si vous exécutez du code dans un notebook comme Colaboratory, vous pouvez directement await des fonctions asynchrones, car une boucle d'événements est déjà en cours d'exécution. Si vous exécutez ce code en tant que script Python standard, vous devez encapsuler vos appels de fonction asynchrones avec asyncio.run() pour créer et gérer une boucle d'événements afin d'exécuter vos fonctions asynchrones. Sinon, vous risquez d'obtenir une erreur de type 'await' outside function.

Pour voir un exemple d'utilisation de Memory Bank avec ADK, exécutez le notebook "Premiers pas avec Memory Bank sur ADK" dans l'un des environnements suivants :

Ouvrir dans Colab | Ouvrir dans Colab Enterprise | Ouvrir dans Agent Platform Workbench | Afficher sur GitHub

Gérer les informations mémorisées avec le service de mémoire ADK et Memory Bank

VertexAiMemoryBankService est un wrapper ADK autour de Memory Bank, défini par BaseMemoryService d'ADK. Vous pouvez définir des rappels et des outils qui interagissent avec le service de mémoire pour lire et écrire des informations mémorisées.

L'interface VertexAiMemoryBankService inclut les éléments suivants :

• memory_service.add_session_to_memory déclenche une requête GenerateMemories à Memory Bank en utilisant tous les événements du adk.Session fourni comme contenu source. Vous pouvez orchestrer les appels à cette méthode à l'aide de callback_context.add_session_to_memory dans vos rappels.

  from google.adk.agents.callback_context import CallbackContext
  
  async def add_session_to_memory_callback(callback_context: CallbackContext):
      await callback_context.add_session_to_memory()
      return None
  

• memory_service.add_events_to_memory qui déclenche une GenerateMemories requête à Memory Bank à l'aide d'un sous-ensemble d'événements. Vous pouvez orchestrer les appels à cette méthode à l'aide de callback_context.add_events_to_memory dans vos rappels.

  from google.adk.agents.callback_context import CallbackContext
  
  async def add_events_to_memory_callback(callback_context: CallbackContext):
      await callback_context.add_events_to_memory(events=callback_context.session.events[-5:-1])
      return None
  

• memory_service.search_memory déclenche une RetrieveMemories requête à Memory Bank pour récupérer les informations mémorisées pertinentes pour les actuels user_id et app_name. Vous pouvez orchestrer les appels à cette méthode à l'aide d'outils de mémoire intégrés (LoadMemoryTool ou PreloadMemoryTool) ou d'un outil personnalisé qui appelle tool_context.search_memory.

Avant de commencer

Pour suivre les étapes décrites dans ce tutoriel, vous devez d'abord suivre les étapes de la section Premiers pas de la page Configurer Memory Bank.

Définir des variables d'environnement

Pour utiliser ADK, définissez vos variables d'environnement :

import os

os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"

Remplacez les éléments suivants :

• PROJECT_ID : ID de votre projet
• LOCATION : votre région Consultez les régions disponibles pour Memory Bank.

Créer votre agent ADK

Pour créer un agent compatible avec la mémoire, configurez des outils et des rappels qui orchestrent les appels à votre service de mémoire.

Définir un rappel de génération de la mémoire

Pour orchestrer les appels de génération de mémoire, créez une fonction de rappel qui déclenche la génération de mémoire. Vous pouvez envoyer un sous-ensemble d'événements (avec callback_context.add_events_to_memory) ou tous les événements d'une session (avec callback_context.add_session_to_memory) à traiter en arrière-plan :

from google.adk.agents.callback_context import CallbackContext

async def generate_memories_callback(callback_context: CallbackContext):
    # Option 1 (Recommended): Send events to Memory Bank for memory generation,
    # which is ideal for incremental processing of events.
    await callback_context.add_events_to_memory(
      events=callback_context.session.events[-5:-1])

    # Option 2: Send the full session to Memory Bank for memory generation.
    # It's recommended to only call this at the end of a session to minimize
    # how many times a single event is re-processed.
    await callback_context.add_session_to_memory()

    return None

Définir un outil de récupération de mémoire

Lorsque vous développez votre agent ADK, incluez un outil de mémoire qui contrôle le moment où l'agent récupère les informations mémorisées et la manière dont elles sont incluses dans le prompt.

Si vous utilisez PreloadMemoryTool, votre agent récupère les informations mémorisées au début de chaque tour et les inclut dans l'instruction système, ce qui est utile pour établir un contexte de base concernant l'utilisateur. Si vous utilisez LoadMemoryTool, le modèle appelle cet outil lorsqu'il décide que des informations mémorisées sont nécessaires pour répondre à la requête de l'utilisateur.

from google import adk
from google.adk.tools.load_memory_tool import LoadMemoryTool
from google.adk.tools.preload_memory_tool import PreloadMemoryTool

memory_retrieval_tools = [
  # Option 1: Retrieve memories at the start of every turn.
  PreloadMemoryTool(),
  # Option 2: Retrieve memories via tool calls. The model will only call this tool
  # when it decides that memories are necessary to respond to the user query.
  LoadMemoryTool()
]

agent = adk.Agent(
    model="gemini-3.5-flash",
    name='stateful_agent',
    instruction="""You are a Vehicle Voice Agent, designed to assist users with information and in-vehicle actions.

1.  **Direct Action:** If a user requests a specific vehicle function (e.g., "turn on the AC"), execute it immediately using the corresponding tool. You don't have the outcome of the actual tool execution, so provide a hypothetical tool execution outcome.
2.  **Information Retrieval:** Respond concisely to general information requests with your own knowledge (e.g., restaurant recommendation).
3.  **Clarity:** When necessary, try to seek clarification to better understand the user's needs and preference before taking an action.
4.  **Brevity:** Limit responses to under 30 words.
""",
    tools=memory_retrieval_tools,
    after_agent_callback=generate_memories_callback
)

Vous pouvez également créer votre propre outil personnalisé pour récupérer des informations mémorisées, ce qui est utile lorsque vous souhaitez fournir des instructions à votre agent sur le moment où il doit récupérer des informations mémorisées :

from google import adk
from google.adk.tools import ToolContext, FunctionTool

async def search_memories(query: str, tool_context: ToolContext):
  """Query this tool when you need to fetch information about user preferences."""
  return await tool_context.search_memory(query)

agent = adk.Agent(
    model="gemini-3.5-flash",
    name='stateful_agent',
    instruction="""...""",
    tools=[FunctionTool(func=search_memories)],
    after_agent_callback=generate_memories_callback
)

Définir un service de mémoire ADK Memory Bank et une instance Memory Bank

Une fois que vous avez créé votre agent compatible avec la mémoire, vous devez le lier à un service de mémoire. Le processus de configuration de votre service de mémoire ADK dépend de l'endroit où votre agent ADK s'exécute. L'environnement d'exécution orchestre l'exécution de vos agents, outils et rappels.

Créer une instance Memory Bank

Remarque : Ignorez cette section si vous disposez déjà d'une instance Memory Bank.

Vous devez d'abord créer une instance Memory Bank. Cette étape est facultative si vous utilisez Agent Runtime pour déployer votre agent. Pour en savoir plus sur la personnalisation du comportement de votre Memory Bank, consultez la section Configurer votre instance Memory Bank de la page Configurer Memory Bank.

import vertexai

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION"
)
# If you don't have a Memory Bank instance already, create a
# Memory Bank instance using the default configuration.
memory_bank = client.agent_engines.create()

# Optionally, print out the resource name. You will need the
# resource name if you want to interact with your Memory Bank instance later on.
print(memory_bank.api_resource.name)

agent_engine_id = memory_bank.api_resource.name.split("/")[-1]

Remplacez les éléments suivants :

• PROJECT_ID : ID de votre projet
• LOCATION : votre région Consultez les régions disponibles pour Memory Bank.

Créer un environnement d'exécution ADK

Transmettez l'ID d'instance Memory Bank à l'environnement d'exécution ou aux scripts de déploiement afin que votre agent utilise Memory Bank comme service de mémoire ADK.

Exécuteur local

adk.Runner est généralement utilisé dans un environnement local, comme Colab. Dans ce cas, vous devez créer directement le service de mémoire et l'exécuteur.

import asyncio

from google.adk.memory import VertexAiMemoryBankService
from google.adk.sessions import VertexAiSessionService
from google.genai import types

memory_service = VertexAiMemoryBankService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id="MEMORY_BANK_ID",
)

# You can use any ADK session service. This example uses Sessions.
session_service = VertexAiSessionService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id="SESSIONS_ID",
)

runner = adk.Runner(
    agent=agent,
    app_name="APP_NAME",
    session_service=session_service,
    memory_service=memory_service
)

async def call_agent(query, session, user_id):
  content = types.Content(role='user', parts=[types.Part(text=query)])
  events = runner.run_async(
    user_id=user_id, session_id=session, new_message=content)

  async for event in events:
      if event.is_final_response():
          final_response = event.content.parts[0].text
          print("Agent Response: ", final_response)

Remplacez les éléments suivants :

• PROJECT_ID : ID de votre projet
• LOCATION : votre région Consultez les régions disponibles pour Memory Bank.
• APP_NAME : nom de l'application ADK Le nom de l'application sera inclus dans le dictionnaire scope des informations mémorisées générées afin que les informations mémorisées soient isolées entre les utilisateurs et les applications.
• MEMORY_BANK_ID : ID de l'instance Memory Bank Par exemple, 456 dans projects/my-project/locations/us-central1/reasoningEngines/456.
• SESSIONS_ID : ID de l'instance Agent Platform Sessions Par exemple, 789 dans projects/my-project/locations/us-central1/reasoningEngines/789.

Agent Runtime sur Gemini Enterprise Agent Platform

Le modèle ADK Agent Runtime (AdkApp) peut être utilisé à la fois en local et pour déployer un agent ADK sur Agent Runtime. Lorsqu'il est déployé sur Agent Platform, le modèle ADK Memory Bank utilise VertexAiMemoryBankService comme service de mémoire par défaut. Vous pouvez donc créer votre instance Memory Bank et la déployer dans un environnement d'exécution en une seule étape.

Pour en savoir plus sur la configuration de votre instance Memory Bank, y compris sur la personnalisation de son comportement, consultez la section Configurer Memory Bank.

Utilisez le code suivant pour déployer votre agent ADK compatible avec la mémoire sur Agent Runtime :

import asyncio

import vertexai
from vertexai.agent_engines import AdkApp

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION"
)

adk_app = AdkApp(agent=agent)

# Create a new resource with your agent deployed to Agent Runtime.
# The Agent Runtime instance will also include an empty Memory Bank instance.
agent_engine = client.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
      }
)

# Alternatively, update an existing resource to deploy your agent to Agent Platform.
# Your agent will have access to the Runtime instance's existing memories.
agent_engine = client.agent_engines.update(
      name=agent_engine.api_resource.name,
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
      }
)

async def call_agent(query, session_id, user_id):
    async for event in agent_engine.async_stream_query(
        user_id=user_id,
        session_id=session_id,
        message=query,
    ):
        print(event)

Remplacez les éléments suivants :

• PROJECT_ID : ID de votre projet
• LOCATION : votre région Consultez les régions disponibles pour Memory Bank.
• STAGING_BUCKET : bucket Cloud Storage à utiliser pour la préparation de votre Agent Runtime

Lorsqu'il est exécuté en local, le modèle ADK utilise InMemoryMemoryService comme service de mémoire par défaut. Toutefois, vous pouvez remplacer le service de mémoire par défaut pour utiliser VertexAiMemoryBankService :

def memory_bank_service_builder():
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="LOCATION",
        agent_engine_id="MEMORY_BANK_ID"
    )

adk_app = AdkApp(
      agent=adk_agent,
      # Override the default memory service.
      memory_service_builder=memory_bank_service_builder
)

async def call_agent(query, session_id, user_id):
  # adk_app is a local agent. If you want to deploy it to Agent Runtime,
  # use `client.agent_engines.create(...)` or `client.agent_engines.update(...)`
  # and call the returned Agent Runtime instance instead.
  async for event in adk_app.async_stream_query(
      user_id=user_id,
      session_id=session_id,
      message=query,
  ):
      print(event)

Remplacez les éléments suivants :

• PROJECT_ID : ID de votre projet
• LOCATION : votre région Consultez les régions disponibles pour Memory Bank.
• MEMORY_BANK_ID : ID de l'instance Memory Bank à utiliser pour Memory Bank. Par exemple, 456 dans projects/my-project/locations/us-central1/reasoningEngines/456.

Cloud Run

Pour voir un exemple d'utilisation de Memory Bank avec Cloud Run, exécutez le notebook "Premiers pas avec Sessions et Memory Bank pour les agents ADK dans Cloud Run" dans l'un des environnements suivants :

Ouvrir dans Colab | Ouvrir dans Colab Enterprise | Ouvrir dans Agent Platform Workbench | Afficher sur GitHub

Pour déployer votre agent sur Cloud Run, reportez-vous aux instructions de la documentation ADK pour savoir comment définir votre agent à déployer sur Cloud Run.

adk deploy cloud_run \
    ...
    --memory_service_uri=agentengine://AGENT_ENGINE_ID

Google Kubernetes Engine (GKE)

Pour voir un exemple d'utilisation de Memory Bank avec Google Kubernetes Engine, exécutez le notebook "Premiers pas avec Sessions et Memory Bank pour les agents ADK dans Google Kubernetes Engine" dans l'un des environnements suivants :

Ouvrir dans Colab | Ouvrir dans Colab Enterprise | Ouvrir dans Agent Platform Workbench | Afficher sur GitHub

Pour déployer votre agent sur GKE, reportez-vous aux instructions de la documentation ADK pour savoir comment définir votre agent à déployer sur GKE.

adk deploy gke \
    ...
    --memory_service_uri=agentengine://AGENT_ENGINE_ID

ADK Web

Important : ADK Web n'est pas destiné à être utilisé dans les déploiements en production. Vous ne devez utiliser ADK Web qu'à des fins de développement et de débogage.

L'interface Web ADK vous permet de tester vos agents directement dans le navigateur.

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 :

• PROJECT_ID : ID de votre projet
• LOCATION : votre région Consultez les régions disponibles pour Memory Bank.
• MEMORY_BANK_ID : ID de l'instance Memory Bank Par exemple, 456 dans projects/my-project/locations/us-central1/reasoningEngines/456.

Interagir avec votre agent

Après avoir défini votre agent et configuré Memory Bank, vous pouvez interagir avec votre agent. Si vous avez fourni un rappel pour déclencher la génération de mémoire lors de l'initialisation de votre agent, la génération de mémoire sera déclenchée chaque fois que l'agent sera appelé.

Les informations mémorisées seront stockées à l'aide du champ d'application {"user_id": USER_ID, "app_name": APP_NAME} correspondant à l'ID utilisateur et au nom de l'application utilisés pour exécuter votre agent.

La méthode d'interaction avec votre agent dépend de son environnement d'exécution :

Exécuteur local

# Use `asyncio.run(session_service.create(...))` if you're running this
# code as a standard Python script.
session = await session_service.create_session(
    app_name="APP_NAME",
    user_id="USER_ID"
)

# Use `asyncio.run(call_agent(...))` if you're running this code as a
# standard Python script.
await call_agent(
    "Can you fix the temperature?",
    session.id,
    "USER_ID"
)

Remplacez les éléments suivants :

• APP_NAME : nom de l'application pour votre exécuteur
• USER_ID : identifiant de votre utilisateur Les informations mémorisées générées à partir de cette session sont indexées par cet identifiant opaque. Le champ d'application des informations mémorisées générées est stocké sous la forme {"user_id": "USER_ID"}.

Agent Runtime

Lorsque vous utilisez le modèle ADK, vous pouvez appeler votre Agent Runtime pour interagir avec la mémoire et les sessions.

# Use `asyncio.run(agent_engine.async_create_session(...))` if you're
# running this code as a standard Python script.
session = await agent_engine.async_create_session(user_id="USER_ID")

# Use `asyncio.run(call_agent(...))` if you're running this code as a
# standard Python script.
await call_agent(
    "Can you fix the temperature?",
    session.get("id"),
    "USER_ID"
)

Remplacez les éléments suivants :

• USER_ID : identifiant de votre utilisateur Les informations mémorisées générées à partir de cette session sont indexées par cet identifiant opaque. Le champ d'application des informations mémorisées générées' est stocké sous la forme {"user_id": "USER_ID"}.

Cloud Run

Reportez-vous à la section Tester votre agent de la documentation sur le déploiement d'ADK Cloud Run.

GKE

Reportez-vous à la section Tester votre agent de la documentation sur le déploiement d'ADK GKE.

ADK Web

Pour utiliser ADK Web, accédez au serveur local à l'adresse http://localhost:8000.

Par défaut, ADK Web définit l'ID utilisateur sur user. Pour remplacer l'ID utilisateur par défaut, incluez userId dans les paramètres de requête, comme http://localhost:8000?userId=YOUR_USER_ID.

Pour en savoir plus, consultez la page ADK Web de la documentation ADK.

Exemple d'interaction

Première session

Si vous avez utilisé PreloadMemoryTool, l'agent tente de récupérer les informations mémorisées au début de chaque tour pour accéder aux préférences que l'utilisateur lui a précédemment communiquées. Lors de la première interaction de l'agent avec l'utilisateur, aucune information mémorisée n'est disponible. L'agent ne connaît donc aucune préférence de l'utilisateur, comme sa température préférée, comme illustré dans l'exemple suivant :

1. Premier tour :

   • Utilisateur : "Pouvez-vous régler la température ?"

   • (Appel d'outil) : ADK tente de récupérer des informations mémorisées, mais aucune n'est disponible.

   • Modèle : "Quelle température préférez-vous ?"

   • (Rappel): ADK déclenche la génération de mémoire. Aucune information mémorisée n'est extraite.

2. Deuxième tour :

   • Utilisateur : Je me sens bien à 22 degrés.

   • (Appel d'outil) : ADK tente de récupérer des informations mémorisées, mais aucune n'est disponible.

   • Modèle : OK, j'ai réglé la température sur 22 degrés.

   • (Rappel): ADK déclenche la génération de mémoire. L'information mémorisée "J'aime la température à 22 degrés" est créée.

Deuxième session

Les informations mémorisées extraites seront disponibles pour la session suivante pour le même nom d'application et le même ID utilisateur. Si l'utilisateur fournit des informations similaires ou contradictoires aux informations mémorisées existantes, les nouvelles informations seront consolidées avec les informations mémorisées existantes.

1. Premier tour

   • Utilisateur : Réglez la température. C'est tellement inconfortable !

   • (Appel d'outil): ADK tente de récupérer des informations mémorisées. L'information mémorisée "J'aime la température à 22 degrés" est récupérée.

   • Modèle : OK, j'ai réglé la température sur 22 degrés.

   • (Rappel): ADK déclenche la génération de mémoire. Aucune information mémorisée n'est extraite, car l'utilisateur n'a rien partagé d'utile à conserver.

2. Deuxième tour

   • Utilisateur : En fait, je préfère qu'il fasse plus chaud le matin.

   • (Appel d'outil): ADK tente de récupérer des informations mémorisées. L'information mémorisée "J'aime la température à 22 degrés" est récupérée.

   • Modèle : OK, j'ai augmenté la température.

   • (Rappel): ADK déclenche la génération de mémoire. L'information mémorisée existante "J'aime la température à 22 degrés" est mise à jour et devient "En général, j'aime la température à 22 degrés, mais je préfère qu'il fasse plus chaud le matin".

Remarque : Les réponses de l'agent et de Memory Bank peuvent varier en fonction des modèles utilisés.

Utiliser un Memory Bank multirégional avec un environnement d'exécution régional

Lorsque vous utilisez Runtime avec Memory Bank intégré, votre agent et Memory Bank sont déployés dans la même région par défaut. Toutefois, vous pouvez les dissocier pour utiliser un Memory Bank multirégional (par exemple, us) avec un environnement d'exécution régional (par exemple, us-central1). Cette configuration vous permet de conserver un Memory Bank centralisé sur différents déploiements régionaux.

Pour utiliser un Memory Bank multirégional, vous devez remplacer le compilateur de service de mémoire ADK par défaut pour qu'il pointe vers l'emplacement multirégional et l'ID Memory Bank correspondant.

import vertexai
from google.adk.memory import VertexAiMemoryBankService
from vertexai.agent_engines import AdkApp

# Create the Memory Bank instance in a multi-region location (for example, 'us')
client_mb = vertexai.Client(project="PROJECT_ID", location="us")
memory_bank = client_mb.agent_engines.create()
memory_bank_id = memory_bank.api_resource.name.split(\"/\")[-1]


# Point your memory service to the 'us' location, 'us' Memory Bank
def memory_bank_service_builder():
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="us",
        agent_engine_id=memory_bank_id
    )

# Create the AdkApp with the overridden builder
adk_app = AdkApp(
    agent=agent,
    memory_service_builder=memory_bank_service_builder
)

# Deploy the runtime to a specific region (for example, 'us-central1')
client_runtime = vertexai.Client(project="PROJECT_ID", location="us-central1")
agent_engine = client_runtime.agent_engines.create(
    agent=adk_app,
    config={
        "staging_bucket": "STAGING_BUCKET",
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
    }
)

Remplacez les éléments suivants :

• PROJECT_ID : ID de votre projet
• STAGING_BUCKET : bucket Cloud Storage à utiliser pour la préparation de votre Agent Runtime

Libérer de l'espace

Pour nettoyer toutes les ressources utilisées dans ce projet, vous pouvez supprimer le Google Cloud projet que vous avez utilisé pour ce tutoriel.

Vous pouvez également supprimer les ressources individuelles que vous avez créées, comme suit :

1. Utilisez l'exemple de code suivant pour supprimer l'instance Agent Runtime, ce qui supprime également toutes les sessions ou informations mémorisées appartenant à cet environnement d'exécution.

   agent_engine.delete(force=True)
   

2. Supprimez tous les fichiers créés localement.

Étape suivante

Guide de démarrage rapide

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.