Démarrage rapide avec l'Agent Development Kit

Ce tutoriel explique comment utiliser Memory Bank avec l'ADK pour gérer les souvenirs à long terme. Une fois que vous avez configuré votre agent Agent Development Kit (ADK) pour qu'il utilise Memory Bank, votre agent orchestre les appels à Memory Bank pour gérer les souvenirs à long terme pour vous.

L'utilisation de Memory Bank avec ADK implique les étapes suivantes :

Créez votre agent et votre exécuteur ADK. Les runners ADK connectent votre agent aux services qui fournissent la gestion des sessions et de la mémoire.
Interagissez avec votre agent pour générer dynamiquement des souvenirs à long terme accessibles d'une session à l'autre.
Effectuez un nettoyage.

Pour effectuer des appels directement à Memory Bank sans orchestration ADK, consultez le guide de démarrage rapide avec le SDK Agent Engine. L'utilisation du SDK Agent Engine est utile pour comprendre comment la Memory Bank génère des souvenirs ou pour inspecter son contenu.

Gérer les souvenirs 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 souvenirs.

L'interface VertexAiMemoryBankService comprend 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, ce qui déclenche une requête GenerateMemories vers 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 requête RetrieveMemories à la banque de données pour récupérer les souvenirs pertinents pour les user_id et app_name actuels. 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 celles 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_VERTEXAI"] = "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 avec 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 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) pour qu'ils soient traités 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 la 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 souvenirs et la manière dont ils sont inclus dans l'invite.

Si vous utilisez PreloadMemoryTool, votre agent récupérera les souvenirs au début de chaque tour et les inclura dans l'instruction système, ce qui est utile pour établir un contexte de base sur l'utilisateur. Si vous utilisez LoadMemoryTool, le modèle appellera cet outil lorsqu'il décidera que des souvenirs sont nécessaires pour répondre à la requête de l'utilisateur.

  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-2.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 souvenirs. Cela peut être utile lorsque vous souhaitez fournir des instructions à votre agent sur le moment où il doit récupérer des souvenirs :

  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-2.5-flash",
      name='stateful_agent',
      instruction="""...""",
      tools=[FunctionTool(func=search_memories)],
      after_agent_callback=generate_memories_callback
  )

Définir un service de mémoire et un environnement d'exécution Memory Bank ADK

Une fois que vous avez créé votre agent compatible avec la mémoire, vous devez l'associer à un service de mémoire. La procédure de configuration de votre service de mémoire ADK dépend de l'endroit où votre agent ADK s'exécute, ce qui orchestre l'exécution de vos agents, outils et rappels.

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

  import vertexai

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

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

  agent_engine_id = agent_engine.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.

Ensuite, transmettez l'ID Agent Engine aux scripts d'exécution ou de déploiement afin que votre agent utilise Memory Bank comme service de mémoire ADK.

Coureur 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=agent_engine_id
)

# You can use any ADK session service. This example uses Agent Engine Sessions.
session_service = VertexAiSessionService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id=agent_engine_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 souvenirs générés afin que les souvenirs soient isolés pour les utilisateurs et les applications.

Agent Engine

Le modèle ADK Agent Engine (AdkApp) peut être utilisé à la fois en local et pour déployer un agent ADK sur Agent Engine Runtime. Lorsqu'il est déployé sur Agent Engine Runtime, le modèle ADK Agent Engine utilise VertexAiMemoryBankService comme service de mémoire par défaut, en utilisant la même instance Agent Engine pour Memory Bank que pour Agent Engine Runtime. 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 environnement d'exécution Agent Engine, y compris sur la personnalisation du comportement de votre banque de mémoire, consultez Configurer Agent Engine.

Utilisez le code suivant pour déployer votre agent ADK compatible avec la mémoire sur Agent Engine 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 Agent Engine with your agent deployed to Agent Engine Runtime.
# The Agent Engine instance will also include an empty Memory Bank.
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 Agent Engine to deploy your agent to Agent Engine Runtime.
# Your agent will have access to the Agent Engine 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 préparer votre Agent Engine 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="AGENT_ENGINE_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 Engine Runtime,
  # use `client.agent_engines.create(...)` or `client.agent_engines.update(...)`
  # and call the returned Agent Engine 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.
AGENT_ENGINE_ID : ID Agent Engine à utiliser pour la banque de mémoire. Par exemple, 456 dans projects/my-project/locations/us-central1/reasoningEngines/456.

Cloud Run

Pour déployer votre agent sur Cloud Run, consultez les 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

GKE

Pour déployer votre agent sur Google Kubernetes Engine (GKE), consultez les 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

Interagir avec votre agent

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

Les souvenirs seront stockés à 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 :

Coureur 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 programme d'exécution.
USER_ID : identifiant de votre utilisateur. Les souvenirs générés à partir de cette session sont identifiés par cet identifiant opaque. Le champ d'application des souvenirs générés est stocké sous la forme {"user_id": "USER_ID"}.

Agent Engine

Lorsque vous utilisez le modèle ADK Agent Engine, vous pouvez appeler votre Agent Engine 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 souvenirs générés à partir de cette session sont identifiés par cet identifiant opaque. Le champ d'application des souvenirs générés est stocké sous la forme {"user_id": "USER_ID"}.

Cloud Run

Consultez la section Tester votre agent de la documentation sur le déploiement de l'ADK sur Cloud Run.

GKE

Consultez la section Tester votre agent de la documentation sur le déploiement ADK GKE.

Exemple d'interaction

Première session

Si vous avez utilisé PreloadMemoryTool, l'agent tentera de récupérer des souvenirs 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 mémoire n'est disponible pour être récupérée. L'agent ne connaît donc aucune préférence de l'utilisateur, comme sa température préférée, comme le montre l'exemple suivant :

Premier tour :
- Utilisateur : "Peux-tu régler la température ?"
- (Appel d'outil) : ADK tente de récupérer des souvenirs, mais aucun n'est disponible.
- Modèle : "Quelle température préférez-vous ?"
- (Rappel) : ADK déclenche la génération de mémoire. Aucun souvenir n'est extrait.
Deuxième tour :
- Utilisateur : Je suis à l'aise à 22 degrés.
- (Appel d'outil) : ADK tente de récupérer des souvenirs, mais aucun 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. La mémoire "J'aime la température de 22 degrés" est créée.

Deuxième séance

La mémoire extraite sera disponible pour la prochaine session avec le même nom d'application et le même ID utilisateur. Si l'utilisateur fournit des informations similaires ou contradictoires à celles des souvenirs existants, les nouvelles informations seront consolidées avec les souvenirs existants.

Premier tour
- Utilisateur : Règle la température. C'est tellement inconfortable !
- (Appel d'outil) : ADK tente de récupérer des souvenirs. La mémoire "J'aime la température de 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. Aucun souvenir n'est extrait, car l'utilisateur n'a partagé aucun contenu pertinent à conserver.
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 souvenirs. La mémoire "J'aime la température de 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. La mémoire existante "J'aime la température à 22 degrés" est mise à jour et devient "J'aime généralement la température à 22 degrés, mais je préfère qu'il fasse plus chaud le matin".

Effectuer un nettoyage

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

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

Utilisez l'exemple de code suivant pour supprimer l'instance Vertex AI Agent Engine, ce qui supprime également toutes les sessions ou mémoires appartenant à ce Vertex AI Agent Engine.
```
agent_engine.delete(force=True)
```
Supprimez tous les fichiers créés localement.

Étapes suivantes

Guide de démarrage rapide avec le SDK Agent Engine

Démarrage rapide avec l'Agent Development Kit Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Gérer les souvenirs avec le service de mémoire ADK et Memory Bank

Avant de commencer

Définir des variables d'environnement

Créer votre agent ADK

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

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

Définir un service de mémoire et un environnement d'exécution Memory Bank ADK

Coureur local

Agent Engine

Cloud Run

GKE

Interagir avec votre agent

Coureur local

Agent Engine

Cloud Run

GKE

Exemple d'interaction

Effectuer un nettoyage

Étapes suivantes

Démarrage rapide avec l'Agent Development Kit