Cette page a été traduite par l'API Cloud Translation.

Démarrage rapide avec l'Agent Development Kit

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.

Ce tutoriel vous explique comment utiliser Memory Bank avec l'ADK pour gérer les souvenirs à long terme :

Créez votre agent et votre exécuteur ADK locaux. 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 banque de mémoire génère des souvenirs ou pour inspecter le contenu de la banque de mémoire.

Avant de commencer

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

Définir des variables d'environnement

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

Google Cloud Projet

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 la banque de mémoire.

Mode Express Vertex AI

import os

os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "TRUE"
os.environ["GOOGLE_API_KEY"] = "API_KEY"

Remplacez les éléments suivants :

API_KEY : votre clé API du mode Express Vertex AI. Si vous utilisez Google Cloudpour la première fois, vous pouvez vous inscrire avec votre compte Gmail pour obtenir une clé API via l'inscription en mode express.

Créer votre agent ADK

Lorsque vous développez votre agent ADK, incluez un outil Memory qui contrôle le moment où l'agent récupère les souvenirs et la manière dont ils sont inclus dans l'invite. L'agent exemple utilise PreloadMemoryTool, qui récupère toujours les souvenirs au début de chaque tour et les inclut dans l'instruction système :

from google import adk

agent = adk.Agent(
    model="gemini-2.0-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=[adk.tools.preload_memory_tool.PreloadMemoryTool()]
)

Créez un service de mémoire VertexAiMemoryBankService, que le runner ADK utilise pour récupérer les souvenirs. Ce paramètre est facultatif si vous utilisez le modèle ADK Agent Engine au lieu de définir votre propre environnement d'exécution ADK. Si vous souhaitez configurer le comportement de votre instance Memory Bank, consultez le guide de configuration.
Google Cloud Projet
```
from google.adk.memory import VertexAiMemoryBankService
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 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]

memory_service = VertexAiMemoryBankService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id=agent_engine_id
)
```
Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projet
- LOCATION : votre région. Consultez les régions disponibles pour la banque de mémoire.
Mode Express Vertex AI
```
from google.adk.memory import VertexAiMemoryBankService
import vertexai

client = vertexai.Client(
  api_key="API_KEY",
)
# 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 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]

# Make sure your environment variables are set. VertexAiMemoryBankService
# will read your api key from the GOOGLE_API_KEY environment variable.
memory_service = VertexAiMemoryBankService(
    agent_engine_id=agent_engine_id
)
```
Remplacez les éléments suivants :
- API_KEY : votre clé API Vertex AI Express Mode. Si vous utilisez Google Cloudpour la première fois, vous pouvez vous inscrire avec votre compte Gmail pour obtenir une clé API via l'inscription en mode express.
VertexAiMemoryBankService est un wrapper ADK autour de Memory Bank, défini par BaseMemoryService d'ADK et qui utilise une interface différente de celle du SDK Agent Engine. Vous pouvez utiliser le SDK Agent Engine pour appeler directement l'API Memory Bank. L'interface VertexAiMemoryBankService comprend les éléments suivants :
- memory_service.add_session_to_memory, ce qui déclenche une requête GenerateMemories vers Memory Bank en utilisant le adk.Session fourni comme contenu source. Les appels à cette méthode ne sont pas orchestrés par le lanceur ADK. Si vous souhaitez automatiser la génération de mémoire avec ADK, vous devez définir vos propres fonctions de rappel.
- memory_service.search_memory, ce qui déclenche une requête RetrieveMemories à Memory Bank pour récupérer les souvenirs pertinents pour les user_id et app_name actuels. Les appels à cette méthode sont orchestrés par le lanceur ADK lorsque vous fournissez un outil de mémoire à votre agent.
Créez un ADK Runtime, qui orchestre l'exécution de vos agents, outils et rappels. La configuration d'ADK Runner dépend de l'environnement de déploiement que vous utilisez :

`adk.Runner`

adk.Runner est généralement utilisé dans un environnement local, comme Colab. La plupart des options de déploiement, comme Agent Engine Runtime, proposent leur propre environnement d'exécution pour l'ADK.

import asyncio

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

# 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
)

# For Express Mode users, ensure your environment variables are set and
# initialize VertexAiSessionService as follows:
#
# session_service = VertexAiSessionService(
#    agent_engine_id=agent_engine_id
# )

app_name="APP_NAME"

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 :

APP_NAME : nom de votre application ADK.

Modèle ADK Agent Engine

Le modèle ADK Agent Engine (AdkApp) peut être utilisé à la fois localement 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. Dans ce cas, vous n'avez pas besoin de fournir explicitement un service de mémoire.

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 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 la banque de mémoire.
AGENT_ENGINE_ID : ID Agent Engine à utiliser pour Memory Bank. Par exemple, 456 dans projects/my-project/locations/us-central1/reasoningEngines/456.
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 :

# For Google Cloud Project users:
def memory_bank_service_builder():
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="LOCATION",
        agent_engine_id="AGENT_ENGINE_ID"
    )
# For Express Mode users, ensure your environment variables are set.
#
# def memory_bank_service_builder():
#    return VertexAiMemoryBankService(
#        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 la banque de mémoire.
AGENT_ENGINE_ID : ID Agent Engine à utiliser pour 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é la banque de mémoire, vous pouvez interagir avec lui.

Créez votre première session. Comme aucune mémoire n'est disponible lors de la première session avec un utilisateur, l'agent ne connaît aucune préférence de l'utilisateur, comme sa température préférée :

`adk.Runner`

Lorsque vous utilisez adk.Runner, vous pouvez appeler directement vos services de mémoire et de session ADK.

# 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 update the temperature to my preferred temperature?",
    session.id,
    "USER_ID"
)
# Agent response: "What is your preferred temperature?"

# Use `asyncio.run(call_agent(...))` if you're running this code as a
# standard Python script.
await call_agent(
  "I like it at 71 degrees", session.id, "USER_ID")
# Agent Response:  Setting the temperature to 71 degrees Fahrenheit.
# Temperature successfully changed.

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

Modèle ADK 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 update the temperature to my preferred temperature?",
    session.get("id"),
    "USER_ID"
)
# Agent response: "What is your preferred temperature?"

# Use `asyncio.run(call_agent(...))` if you're running this code as a
# standard Python script.
await call_agent("I like it at 71 degrees", session.get("id"), "USER_ID")
# Agent Response:  Setting the temperature to 71 degrees Fahrenheit.
# Temperature successfully changed.

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

Générez des souvenirs pour votre session en cours. Si la Banque de souvenirs extrait des souvenirs de la conversation, ils sont stockés dans le champ d'application {"user_id": USER_ID, "app_name": APP_NAME}.

`adk.Runner`

async def trigger_memory_generation(app_name, session):
    # Refresh your `session` object so that all of the session events locally available.
    session = await session_service.get_session(
        app_name=app_name,
        user_id="USER_ID",
        session_id=session.id
    )
    await memory_service.add_session_to_memory(session)

# Use `asyncio.run(trigger_memory_generation(...))` if you're running this
# code as a standard Python script.
await trigger_memory_generation(app_name, session)

Modèle ADK Agent Engine

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

Créez votre deuxième session. Si vous avez utilisé PreloadMemoryTool, l'agent récupère les souvenirs au début de chaque tour pour accéder aux préférences que l'utilisateur lui a communiquées précédemment.

`adk.Runner`

# Use `asyncio.run(session_service.create_session(...))` 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("Fix the temperature!", session.id, "USER_ID")
# Agent Response:  Setting temperature to 71 degrees.  Is that correct?

Vous pouvez également utiliser memory_service.search_memory pour récupérer directement des souvenirs :

# Use `asyncio.run(memory_service.search_memory(...))` if you're running
# this code as a standard Python script.
await memory_service.search_memory(
    app_name="APP_NAME",
    user_id="USER_ID",
    query="Fix the temperature!",
)

Modèle ADK Agent Engine

# Use `asyncio.run(agent_engine.async_add_session_to_memory(...))` 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("Fix the temperature!", session.get("id"), "USER_ID")
# Agent Response:  Setting temperature to 71 degrees.  Is that correct?

Vous pouvez également utiliser agent_engine.async_search_memory pour récupérer directement des souvenirs : Remarque : Pour utiliser async_search_memory, votre AdkApp doit avoir été créé avec la version 1.110.0 ou ultérieure de google-cloud-aiplatform. Sinon, vous pouvez récupérer des souvenirs en appelant directement la Memory Bank.

# Use `asyncio.run(agent_engine.async_search_memory(...))` if you're
# running this code as a standard Python script.
await agent_engine.async_search_memory(
    user_id="USER_ID",
    query="Fix the temperature!",
)

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.

Avant de commencer

Définir des variables d'environnement

Google Cloud Projet

Mode Express Vertex AI

Créer votre agent ADK

Google Cloud Projet

Mode Express Vertex AI

adk.Runner

Modèle ADK Agent Engine

Interagir avec votre agent

adk.Runner

Modèle ADK Agent Engine

adk.Runner

Modèle ADK Agent Engine

adk.Runner

Modèle ADK Agent Engine

Effectuer un nettoyage

Étapes suivantes

Démarrage rapide avec l'Agent Development Kit

`adk.Runner`

`adk.Runner`

`adk.Runner`

`adk.Runner`