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.
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 celles de la section Configurer Memory Bank.

Définir des variables d'environnement

Pour utiliser l'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 la banque de souvenirs.

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.
```
from google.adk.memory import VertexAiMemoryBankService

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

memory_service = VertexAiMemoryBankService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id=agent_engine_id
)
```
VertexAiMemoryBankService est un wrapper ADK autour de Memory Bank, défini par BaseMemoryService de l'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 programme d'exécution 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 vers la banque de mémoire 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.

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

# You can use any ADK session service.
session_service = VertexAiSessionService(
    project="PROJECT_ID",
    location="LOCATION",
    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
)

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

  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 du moteur d'agent

Le modèle ADK Agent Engine (AdkApp) peut être utilisé à la fois localement et pour déployer un agent ADK sur le runtime Agent Engine. 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 la banque de mémoire 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 vertexai
from vertexai.preview.reasoning_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 souvenirs.
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.
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 la banque de souvenirs.
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.

Interagir avec votre agent

Une fois votre agent défini et la banque de mémoire configurée, vous pouvez interagir avec votre agent.

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 :

Remarque : Les réponses de l'agent et de la mémoire peuvent varier en fonction des modèles utilisés.
adk.Runner
Lorsque vous utilisez adk.Runner, vous pouvez appeler directement vos services de mémoire et de session ADK.
```
session = await session_service.create_session(
    app_name="APP_NAME",
    user_id="USER_ID"
)

call_agent(
    "Can you update the temperature to my preferred temperature?",
    session.id,
    "USER_ID"
)

# Agent response: "What is your preferred temperature?"
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 runner.
- 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 du moteur d'agent
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.
```
session = await agent_engine.async_create_session(user_id="USER_ID")

await call_agent(
    "Can you update the temperature to my preferred temperature?",
    session.get("id"),
    "USER_ID"
)

# Agent response: "What is your preferred temperature?"
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 mémoire 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
```
session = await session_service.get_session(
    app_name=app_name,
    user_id="USER_ID",
    session_id=session.id
)
memory_service.add_session_to_memory(session)
```
Modèle ADK du moteur d'agent
Remarque : Pour utiliser async_add_session_to_memory, votre AdkApp doit avoir été créé avec la version 1.110.0 ou ultérieure de google-cloud-aiplatform. Sinon, vous pouvez déclencher la génération de souvenirs en appelant directement la banque de souvenirs.
```
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 précédemment communiquées.

`adk.Runner`

session = await session_service.create_session(
    app_name=app_name,
    user_id="USER_ID"
)

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 :

await memory_service.search_memory(
    app_name="APP_NAME",
    user_id="USER_ID",
    query="Fix the temperature!",
)

Modèle ADK du moteur d'agent

session = await agent_engine.async_create_session(user_id="USER_ID")

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.

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

Créer votre agent ADK

adk.Runner

Modèle ADK du moteur d'agent

Interagir avec votre agent

adk.Runner

Modèle ADK du moteur d'agent

adk.Runner

Modèle ADK du moteur d'agent

adk.Runner

Modèle ADK du moteur d'agent

Effectuer un nettoyage

Étapes suivantes

Démarrage rapide avec l'Agent Development Kit

`adk.Runner`

`adk.Runner`

`adk.Runner`

`adk.Runner`