Gérer les sessions avec le kit de développement d'agents

Cette page explique comment connecter un agent Agent Development Kit (ADK) à des sessions Vertex AI Agent Engine et comment utiliser des sessions gérées dans l'environnement local et de production.

Avant de commencer

Assurez-vous que votre environnement est configuré en suivant les étapes Obtenir les rôles requis et Authentification de la section Configurer votre environnement.

Créer une instance Vertex AI Agent Engine

Pour accéder aux sessions 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 Sessions. Sans déploiement de code, la création d'une instance Vertex AI Agent Engine ne prend que quelques secondes.

import vertexai
from vertexai import agent_engines

# Create an agent engine instance
agent_engine = agent_engines.create()

Développer votre agent ADK

Pour créer votre agent ADK, suivez les instructions de Agent Development Kit ou utilisez le code suivant pour créer un agent qui salue un utilisateur avec des salutations fixes :

from google import adk

def greetings(query: str):
  """Tool to greet user."""
  if 'hello' in query.lower():
    return {"greeting": "Hello, world"}
  else:
    return {"greeting": "Goodbye, world"}

# Define an ADK agent
root_agent = adk.Agent(
    model="gemini-2.0-flash",
    name='my_agent',
    instruction="You are an Agent that greet users, always use greetings tool to respond.",
    tools=[greetings]
)

Configurer l'exécuteur ADK

L'environnement d'exécution ADK orchestre l'exécution de vos agents, outils et rappels, ainsi que les appels pour lire et écrire des sessions. Initialisez le Runner avec VertexAiSessionService, qui se connecte aux sessions Vertex AI Agent Engine.

from google.adk.sessions import VertexAiSessionService

app_name="AGENT_ENGINE_ID"
user_id="USER_ID"

# Create the ADK runner with VertexAiSessionService
session_service = VertexAiSessionService(
       "PROJECT_ID", "LOCATION")
runner = adk.Runner(
    agent=root_agent,
    app_name=app_name,
    session_service=session_service)

# Helper method to send query to the runner
def call_agent(query, session_id, user_id):
  content = types.Content(role='user', parts=[types.Part(text=query)])
  events = runner.run(
      user_id=user_id, session_id=session_id, 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 :

• PROJECT_ID : ID de votre projet

• LOCATION : votre région.

• AGENT_ENGINE_ID : ID de ressource d'une instance Vertex AI Agent Engine.

  • Pour les agents déployés, l'ID de ressource est indiqué en tant que variable d'environnement GOOGLE_CLOUD_AGENT_ENGINE_ID.

  • Pour les agents locaux, vous pouvez récupérer l'ID de ressource à l'aide de agent_engine.name.split("/")[-1].

• USER_ID : identifiant unique non vide pour l'utilisateur, d'une longueur maximale de 128 caractères.

Interagir avec votre agent

Après avoir défini votre agent et configuré les sessions Vertex AI Agent Engine, vous pouvez interagir avec votre agent pour vérifier que l'historique et les états des sessions sont conservés.

agent_engine_id="AGENT_ENGINE_ID"

adk web --session_db_url=agentengine://${agent_engine_id}

# Sample output
+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

# Create a session
session = await session_service.create_session(
       app_name=app_name,
       user_id=user_id)

call_agent("Hello!", session.id, user_id)
# Agent response: "Hello, world"

call_agent("Thanks!", session.id, user_id)
# Agent response: "Goodbye, world"

# List sessions
await session_service.list_sessions(app_name=app_name,user_id=user_id)

# ListSessionsResponse(session_ids=['1122334455', '9988776655'])

# Create a session with state
session = await session_service.create_session(
      app_name=app_name,
      user_id=user_id,
      state={'key': 'value'})

print(session.state['key'])
# value

from google.adk.events import Event, EventActions
import time

# Define state changes
state_changes = {'key': 'new_value'}

# Create event with actions
actions_with_update = EventActions(state_delta=state_changes)
system_event = Event(
  invocation_id="invocation_id",
  author="system", # Or 'agent', 'tool' etc.
  actions=actions_with_update,
  timestamp=time.time()
)

# Append the event
await session_service.append_event(session, system_event)

# Check updated state
updated_session = await session_service.get_session(
      app_name=app_name,
      user_id=user_id,
      session_id=session.id)
# State is updated to new value
print(updated_session.state['key'])
# new_value

await session_service.delete_session(app_name=app_name, user_id=user_id, session_id=session.id)

Déployer votre agent dans Vertex AI Agent Engine

Après avoir testé votre agent en local, vous pouvez le déployer en production en mettant à jour l'instance Vertex AI Agent Engine avec les paramètres suivants :

agent_engines.update(resource_name=agent_engine.name, agent_engine=AGENT, requirements=REQUIREMENTS)

Remplacez les éléments suivants :

• AGENT : application qui implémente la méthode query / stream_query (par exemple, AdkApp pour un agent ADK). Pour en savoir plus, consultez la section Éléments à prendre en compte pour le déploiement.

Effectuer un nettoyage

Pour nettoyer toutes les ressources utilisées dans ce projet, vous pouvez supprimer l'instance Vertex AI Agent Engine ainsi que ses ressources enfants :

agent_engine.delete(force=True)

Étapes suivantes

• Gérez les sessions à l'aide d'appels d'API.