Démarrage rapide avec l'Agent Development Kit

Une fois que vous avez configuré votre agent Agent Development Kit (ADK) pour qu'il utilise les sessions et la Memory Bank de Vertex AI Agent Engine, votre agent lit et écrit automatiquement les mémoires et les sessions pour vous.

Pour le guide de démarrage rapide utilisant l'API REST, consultez Démarrage rapide avec l'API REST.

Ce tutoriel explique comment utiliser les sessions et la banque de mémoire Vertex AI Agent Engine avec l'ADK pour créer et utiliser des sessions et des mémoires à long terme :

1. Créez votre instance Vertex AI Agent Engine pour accéder aux sessions et à la banque de mémoire Vertex AI Agent Engine.

2. Créez votre agent et votre exécuteur ADK locaux.

3. Interagissez avec votre agent pour générer dynamiquement des souvenirs à long terme accessibles d'une session à l'autre.

4. Effectuez un nettoyage.

Avant de commencer

Pour suivre les étapes décrites dans ce tutoriel, vous devez d'abord configurer votre projet et votre environnement.

Configurer votre projet

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Enable the API

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

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Vertex AI API.

Enable the API

1. Si vous avez sélectionné un projet, assurez-vous de disposer du rôle IAM Utilisateur Vertex AI (roles/aiplatform.user) sur le projet.

S'authentifier sur Vertex AI

Pour utiliser les exemples Python de cette page dans un environnement de développement local, installez et initialisez gcloud CLI, puis configurez le service Identifiants par défaut de l'application à l'aide de vos identifiants utilisateur.

1. Install the Google Cloud CLI.

2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

   If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

Pour en savoir plus, consultez Configurer les ADC pour un environnement de développement local dans la documentation sur l'authentification Google Cloud .

Importer des bibliothèques

Installez le kit de développement d'agents et le SDK Vertex AI :

pip install google-adk>=1.5.0
pip install google-cloud-aiplatform>=1.100.0

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. Seule la région us-central1 est acceptée pour la banque de mémoire Vertex AI Agent Engine.

Créer votre instance Vertex AI Agent Engine

Pour accéder aux sessions Vertex AI Agent Engine et à la mémoire Vertex AI Agent Engine, vous devez d'abord créer une instance Vertex AI Agent Engine. Vous n'avez pas besoin de déployer de code pour commencer à utiliser les sessions et la banque de mémoire. Sans déploiement de code, la création d'une instance Vertex AI Agent Engine devrait prendre quelques secondes.

import vertexai

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

agent_engine = client.agent_engines.create()

Créer votre agent ADK

1. Lorsque vous développez votre agent ADK, incluez un outil Memory, qui contrôle quand le service de mémoire est utilisé et comment les souvenirs sont inclus dans la requête. 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()]
   )
   

2. Créez un service de mémoire VertexAiMemoryBankService, que le runner ADK utilise pour récupérer les souvenirs.

   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
   )
   

3. Créez un exécutable ADK, qui orchestre l'exécution de vos agents, outils et rappels.

   from google.adk.sessions import VertexAiSessionService
   
   # You can use any ADK session service.
   session_service = VertexAiSessionService(
       project_id="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.

Interagir avec votre agent

Après avoir défini votre agent et configuré les sessions et la banque de mémoire, vous pouvez interagir avec votre agent.

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

   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 :

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

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

   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)
   

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

   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?
   

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 :

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

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

Étapes suivantes

• Guide de démarrage rapide avec l'API REST