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

Preview — The Python buildpack supports default entrypoint detection for the Agent Development Kit (ADK) framework google-adk

Cette fonctionnalité est soumise(s) aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités de pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Le framework Agent Development Kit (ADK) simplifie la création, l'évaluation et le déploiement d'agents d'IA. L'ADK fournit une approche modulaire et 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'exemple d'application 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éorologiques.

Coûts

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

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

Vous pouvez obtenir une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût.

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

Avant de commencer

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.

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. Enable the Cloud Run Admin API, Vertex AI API, and Cloud Build APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the APIs

2. Configurez votre environnement de développement Cloud Run dans votre projet Google Cloud .
3. Installez l'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 accédez-y :

   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écifique :

   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.0-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 beta 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. Accédez à /list-apps à partir de l'URL de votre service. Exemple : https://weather-agent-123456789101.us-central1.run.app/list-apps.

Exécuter votre agent

Pour interroger l'agent ADK, exécutez 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": 42}'
   

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 de l'ADK.

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

Effectuer un nettoyage

Pour éviter des frais supplémentaires 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 que vous avez apportées dans ce tutoriel, supprimez les ressources que vous avez 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 entraîne les effets décrits ci-dessous :

• 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. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

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 coûts 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