Créer et déployer un agent d'IA sur Cloud Run à l'aide de l'Agent Development Kit (ADK)

Le framework Agent Development Kit (ADK) simplifie la création, l'évaluation et le déploiement d'agents d'IA. ADK fournit une approche modulaire axée sur le code pour créer des agents capables de raisonner, de planifier et d'utiliser des outils.

Ce tutoriel vous explique comment créer et déployer un agent d'IA sur Cloud Run à l'aide de l'ADK pour Python. Cet agent récupère le bulletin météo pour une ville que vous spécifiez.

Pour en savoir plus sur l'hébergement de votre agent ADK à l'aide de Google Cloud CLI, consultez Déployer sur Cloud Run dans la documentation ADK.

Objectifs

• Écrivez l'application exemple pour définir l'agent météo.
• Déployez l'agent sur Cloud Run à partir de la source.
• Exécutez votre agent pour interroger les informations météo.

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Google Cloud :

• Artifact Registry
• Cloud Build
• Cloud Run
• Vertex AI

Pour obtenir une estimation des coûts en fonction de votre utilisation prévue, utilisez le simulateur de coût.

Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai sans frais.

Avant de commencer

Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Activez les API Cloud Run Admin, Vertex AI et Cloud Build si elles ne le sont pas déjà.

   Rôles requis pour activer les API

   Pour activer les API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation grâce au rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation grâce au rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

   Activer les API

2. Configurez votre environnement de développement Cloud Run dans votre projet Google Cloud .
3. Installez ADK en suivant les instructions de la documentation Agent Development Kit.

4. Si vous êtes soumis à une règle d'administration de restriction de domaine limitant les appels non authentifiés pour votre projet, vous devez accéder au service déployé comme décrit dans la section Tester les services privés.

Rôles requis

Pour obtenir les autorisations nécessaires pour déployer un agent d'IA sur Cloud Run, demandez à votre administrateur de vous accorder les rôles IAM suivants :

• Développeur de source Cloud Run (roles/run.sourceDeveloper) sur le projet
• Utilisateur Vertex AI (roles/aiplatform.user) sur le projet
• Utilisateur du compte de service (roles/iam.serviceAccountUser) sur l'identité du service
• Lecteur de journaux (roles/logging.viewer) sur le projet

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Coder l'exemple d'application

Pour écrire une application en Python :

1. Créez un répertoire parent nommé parent_folder et modifiez les sous-répertoires comme suit :

   mkdir parent_folder
   cd parent_folder
   

2. Dans le répertoire parent_folder, créez un sous-répertoire nommé multi_tool_agent et accédez-y :

   mkdir multi_tool_agent
   cd multi_tool_agent
   

3. Créez un fichier __init__.py pour importer l'agent :

   from . import agent
   

4. Créez un fichier agent.py pour définir l'agent qui répond aux questions sur l'heure et la météo dans une ville spécifiée :

   import datetime
   from zoneinfo import ZoneInfo
   from google.adk.agents import Agent
   
   def get_weather(city: str) -> dict:
       """Retrieves the current weather report for a specified city.
   
       Args:
           city (str): The name of the city for which to retrieve the weather report.
   
       Returns:
           dict: status and result or error msg.
       """
       if city.lower() == "new york":
           return {
               "status": "success",
               "report": (
                   "The weather in New York is sunny with a temperature of 25 degrees"
                   " Celsius (77 degrees Fahrenheit)."
               ),
           }
       else:
           return {
               "status": "error",
               "error_message": f"Weather information for '{city}' is not available.",
           }
   
   def get_current_time(city: str) -> dict:
       """Returns the current time in a specified city.
   
       Args:
           city (str): The name of the city for which to retrieve the current time.
   
       Returns:
           dict: status and result or error msg.
       """
   
       if city.lower() == "new york":
           tz_identifier = "America/New_York"
       else:
           return {
               "status": "error",
               "error_message": (
                   f"Sorry, I don't have timezone information for {city}."
               ),
           }
   
       tz = ZoneInfo(tz_identifier)
       now = datetime.datetime.now(tz)
       report = (
           f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
       )
       return {"status": "success", "report": report}
   
   root_agent = Agent(
       name="weather_time_agent",
       model="gemini-2.5-flash",
       description=(
           "Agent to answer questions about the time and weather in a city."
       ),
       instruction=(
           "You are a helpful agent who can answer user questions about the time and weather in a city."
       ),
       tools=[get_weather, get_current_time],
   )
   

5. Créez un fichier .env et ajoutez les variables suivantes :

   GOOGLE_GENAI_USE_VERTEXAI=TRUE
   GOOGLE_CLOUD_PROJECT=PROJECT_ID
   GOOGLE_CLOUD_LOCATION=REGION
   

   Remplacez les éléments suivants :

   • PROJECT_ID : ID du projet Google Cloud .
   • REGION : région dans laquelle vous prévoyez de déployer votre service.

6. Accédez au répertoire du dossier parent parent_folder et créez un fichier requirements.txt pour ajouter la dépendance google-adk :

   google-adk
   

   Votre projet source inclut la structure suivante :

   parent_folder/
   ├── requirements.txt
   └── multi_tool_agent/
       ├── __init__.py
       ├── agent.py
       └── .env
   

Votre application est terminée et prête à être déployée.

Déployer sur Cloud Run depuis la source

Cette fonction crée automatiquement une image de conteneur à partir du code source et la déploie.

1. Dans le répertoire du code source (parent_folder), déployez sur Cloud Run à l'aide de la commande suivante :

   gcloud run deploy --source .

   1. Lorsque vous êtes invité à saisir le nom du service, appuyez sur Entrée pour accepter le nom par défaut, par exemple weather-agent.

   2. Si vous êtes invité à activer des API supplémentaires sur le projet, par exemple l'API Artifact Registry, répondez en appuyant sur y.

   3. Lorsque vous êtes invité à indiquer la région, sélectionnez la région de votre choix, par exemple europe-west1.

   4. Si vous êtes invité à créer un dépôt dans la région spécifiée, répondez en appuyant sur y.

   5. Si vous êtes invité à autoriser l'accès public, répondez y. Cette invite peut ne pas s'afficher si une règle d'administration de restriction de domaine l'empêche. Pour plus d'informations, consultez la section Avant de commencer.

   Patientez quelques instants jusqu'à la fin du déploiement. En cas de réussite, la ligne de commande affiche l'URL du service de l'agent déployé, qui se présente sous la forme suivante : https://weather-agent-123456789101.us-central1.run.app/list-apps.

Exécuter votre agent

Pour utiliser l'agent ADK, vous pouvez exécuter les commandes curl suivantes :

1. Pour obtenir la liste des applications, exécutez la commande suivante :

   curl -X GET SERVICE_URL/list-apps
   

   Remplacez SERVICE_URL par l'URL de votre service déployé.

2. Pour démarrer une session, exécutez la commande suivante :

   curl -X POST SERVICE_URL/apps/multi_tool_agent/users/u_123/sessions/s_123 -H "Content-Type: application/json" -d '{"key1": "value1", "key2": "value2"}'
   

3. Pour interroger l'agent, exécutez la commande suivante :

   curl -X POST SERVICE_URL/run \
   -H "Content-Type: application/json" \
   -d "{\"appName\": \"multi_tool_agent\",\"userId\": \"u_123\",\"sessionId\": \"s_123\",\"newMessage\": { \"role\": \"user\", \"parts\": [{ \"text\": \"What's the weather in New York today?\" }]}}"
   

L'agent renvoie les informations météorologiques dans les résultats de votre requête.

Pour en savoir plus et obtenir des exemples sur les commandes curl compatibles, consultez Utiliser le serveur d'API dans la documentation ADK.

Réussite : vous avez déployé un agent d'IA sur Cloud Run à l'aide de l'Agent Development Kit.

Effectuer un nettoyage

Pour éviter que des frais supplémentaires ne soient facturés sur votre compte Google Cloud , supprimez toutes les ressources que vous avez déployées avec ce tutoriel.

Supprimer le projet

Si vous avez créé un projet pour ce tutoriel, supprimez-le. Si vous avez utilisé un projet existant et que vous devez le conserver sans les modifications apportées lors du présent tutoriel, supprimez les ressources créées pour ce tutoriel.

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet que vous avez créé pour ce tutoriel.

Pour supprimer le projet :

Attention : La suppression d'un projet aura les effets suivants :

• Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches décrites dans ce document et que vous le supprimez, vous supprimerez également tout autre travail effectué dans le projet.
• Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID de projet, telle qu'une URL appspot.com, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.

Si vous envisagez d'explorer plusieurs architectures, tutoriels et guides de démarrage rapide, réutiliser des projets peut vous aider à ne pas dépasser les limites de quotas des projets.

1. Dans la console Google Cloud , accédez à la page Gérer les ressources.

   Accéder à la page "Gérer les ressources"

2. Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer.
3. Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.

Supprimer les ressources du tutoriel

1. Supprimez le service Cloud Run que vous avez déployé dans ce tutoriel. Les services Cloud Run n'entraînent pas de frais tant qu'ils ne reçoivent pas de requêtes.

   Pour supprimer votre service Cloud Run, exécutez la commande suivante :

   gcloud run services delete SERVICE-NAME

   Remplacez SERVICE-NAME par le nom du service.

   Vous pouvez également supprimer des services Cloud Run à partir de la consoleGoogle Cloud .

2. Supprimez la configuration régionale par défaut gcloud que vous avez ajoutée lors de la configuration du tutoriel :

    gcloud config unset run/region
   

3. Supprimez la configuration du projet :

    gcloud config unset project