Guide de démarrage rapide : Créer et déployer une application Web Python (smolagents) sur Cloud Run

Guide de démarrage rapide : Créer et déployer une application Web Python (smolagents) sur Cloud Run

Ce document vous explique comment créer et déployer une application smolagents sur Cloud Run.

En suivant les étapes de ce guide de démarrage rapide, Cloud Run crée automatiquement un Dockerfile pour vous lorsque vous déployez à partir du code source.

Avant de commencer

Connectez-vous à votre Google Cloud compte. Si vous n'avez jamais utilisé Google Cloud, créez un compte pour évaluer les performances de nos produits dans des scénarios réels. 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.

Installez Google Cloud CLI.

Remarque : Si vous avez déjà installé gcloud CLI, assurez-vous que vous disposez de la dernière version en exécutant gcloud components update.

Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

Pour initialiser la gcloud CLI, exécutez la commande suivante :

gcloud init

Créez ou sélectionnez un Google Cloud projet.

Rôles requis pour sélectionner ou créer un projet

• Sélectionner un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
• Créer un projet : pour créer un projet, vous avez besoin du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu d'en sélectionner un existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

• Créez un Google Cloud projet :

  gcloud projects create PROJECT_ID

  Remplacez PROJECT_ID par le nom du Google Cloud projet que vous créez.

• Sélectionnez le Google Cloud projet que vous avez créé :

  gcloud config set project PROJECT_ID

  Remplacez PROJECT_ID par le nom de votre Google Cloud projet.

Si vous utilisez un projet existant pour ce guide, vérifiez que vous disposez des autorisations nécessaires pour suivre les instructions. Si vous avez créé un nouveau projet, vous disposez déjà des autorisations requises.

Vérifiez que la facturation est activée pour votre Google Cloud projet.

Installez Google Cloud CLI.

Remarque : Si vous avez déjà installé gcloud CLI, assurez-vous que vous disposez de la dernière version en exécutant gcloud components update.

Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

Pour initialiser la gcloud CLI, exécutez la commande suivante :

gcloud init

Créez ou sélectionnez un Google Cloud projet.

Rôles requis pour sélectionner ou créer un projet

• Sélectionner un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
• Créer un projet : pour créer un projet, vous avez besoin du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu d'en sélectionner un existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

• Créez un Google Cloud projet :

  gcloud projects create PROJECT_ID

  Remplacez PROJECT_ID par le nom du Google Cloud projet que vous créez.

• Sélectionnez le Google Cloud projet que vous avez créé :

  gcloud config set project PROJECT_ID

  Remplacez PROJECT_ID par le nom de votre Google Cloud projet.

Si vous utilisez un projet existant pour ce guide, vérifiez que vous disposez des autorisations nécessaires pour suivre les instructions. Si vous avez créé un nouveau projet, vous disposez déjà des autorisations requises.

Vérifiez que la facturation est activée pour votre Google Cloud projet.

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

2. Activez l'API Cloud Run Admin et les API Cloud Build :

   Rôles requis pour activer les API

   Pour activer les API, vous avez besoin du rôle IAM Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin), qui contient l' serviceusage.services.enable autorisation. Découvrez comment attribuer des rôles.

   gcloud services enable run.googleapis.com cloudbuild.googleapis.com

   Une fois l'API Cloud Run Admin activée, le compte de service Compute Engine par défaut est créé automatiquement.

3. Consultez la tarification de Cloud Run ou estimez les coûts à l'aide du simulateur de coût.
4. Vous avez besoin d'une clé API de Google AI Studio pour déployer l'application smolagents avec un modèle Gemini. Pour générer une clé API à l'aide de Google AI Studio, consultez la section Utiliser des clés API Gemini dans la documentation de l'API Gemini.

Rôles requis

Pour obtenir les autorisations nécessaires pour suivre ce guide de démarrage rapide, demandez à votre administrateur de vous accorder les rôles IAM suivants :

• Administrateur Cloud Run (roles/run.admin) sur le projet
• Développeur source Cloud Run (roles/run.sourceDeveloper) sur le projet
• Utilisateur du compte de service (roles/iam.serviceAccountUser) sur l'identité du service
• Lecteur des 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.

Accorder l'accès au compte de service Cloud Build à votre projet

Cloud Build utilise automatiquement le compte de service Compute Engine par défaut comme compte de service Cloud Build par défaut pour créer votre code source et votre ressource Cloud Run, sauf si vous remplacez ce comportement.

Pour que Cloud Build puisse créer vos sources, accordez au compte de service Cloud Build le rôle Compilateur Cloud Run (roles/run.builder) sur votre projet :

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS \
    --role=roles/run.builder

Remplacez PROJECT_ID par votre Google Cloud ID de projet et SERVICE_ACCOUNT_EMAIL_ADDRESS par l'adresse e-mail du compte de service Cloud Build. Si vous utilisez le compte de service Compute Engine par défaut comme compte de service Cloud Build, utilisez le format suivant pour l'adresse e-mail du compte de service :

[e-mail]

Remplacez PROJECT_NUMBER par votre Google Cloud numéro de projet.

Pour obtenir des instructions détaillées sur la recherche de votre ID et de votre numéro de projet, consultez la section Créer et gérer des projets.

La propagation de l'attribution du rôle de compilateur Cloud Run prend quelques minutes pour se propager.

Coder l'exemple d'application

Pour écrire une application en Python :

1. Créez un répertoire nommé my-agent-app et modifiez les sous-répertoires comme suit :

   mkdir my-agent-app
   cd my-agent-app
   

2. Créez un fichier nommé main.py et collez-y le code suivant :

   import os
   from fastapi import FastAPI, HTTPException
   from pydantic import BaseModel
   from smolagents import CodeAgent, LiteLLMModel, tool
   
   # 1. Define a simple tool for the agent
   @tool
   def get_greeting(name: str) -> str:
     """
     Returns a special greeting for the user.
     Args:
         name: The name of the person to greet.
     """
     return f"Hello {name}, welcome to the agentic world running on Cloud Run!"
   
   # 2. Initialize the Gemini Model via LiteLLM
   # Make sure GEMINI_API_KEY is set in your environment variables
   model = LiteLLMModel(
   model_id="gemini/gemini-2.5-flash", # This is the model name. If a newer model is available, you can use that.
   api_key=os.environ.get("GEMINI_API_KEY")
   )
   
   # 3. Create the CodeAgent
   agent = CodeAgent(
     tools=[get_greeting],
     model=model,
     add_base_tools=True # Adds basic python tools like print
   )
   
   # 4. Setup FastAPI
   app = FastAPI()
   
   class AgentRequest(BaseModel):
     task: str
   
   @app.get("/")
   def health_check():
     return {"status": "running", "service": "smolagents-fastapi"}
   
   @app.post("/run")
   def run_agent(request: AgentRequest):
     try:
       # Run the agent with the user's task
       response = agent.run(request.task)
       return {"response": str(response)}
     except Exception as e:
       raise HTTPException(status_code=500, detail=str(e))
   

3. Créez un fichier nommé requirements.txt et collez-y le code suivant :

   fastapi
   uvicorn
   smolagents[toolkit]
   litellm
   

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.

Pour déployer à partir de la source à l'aide de la commande suivante :

  gcloud run deploy smolagents-demo \
    --source . \
    --region us-central1 \
    --no-allow-unauthenticated \
    --set-env-vars GEMINI_API_KEY=API_KEY

Remplacez API_KEY par votre clé API Google AI Studio.

Cloud Run affiche l'URL du service, par exemple https://smolagents-demo-xyz-uc.a.run.app, une fois l'application déployée.

Succès : Vous avez déployé une application Web smolagents sur Cloud Run.

Tester votre service Cloud Run

Testez votre service en envoyant une tâche à l'agent à l'aide de la commande curl suivante :

  curl -X POST YOUR-SERVICE-URL/run \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
    -d '{"task": "Use the greeting tool to say hello to Gemini User"}'

Remplacez YOUR-SERVICE-URL par l'URL de votre service.

L'agent envoie la réponse suivante :

{
 "response": "Hello Gemini User, welcome to the agentic world running on Cloud Run!"
}

Pour vérifier que votre service fonctionne correctement, consultez l'onglet Journaux du service Cloud Run.

Effectuer un nettoyage

Pour éviter que les ressources utilisées dans cette démonstration soient facturées sur votre Google Cloud compte pour les ressources utilisées sur cette page, supprimez le Google Cloud projet qui les contient.

Pour éviter des frais supplémentaires sur votre Google Cloud compte, supprimez toutes les ressources que vous avez déployées avec ce guide de démarrage rapide.

Supprimer votre dépôt

Cloud Run ne vous facture pas lorsque votre service déployé n'est pas utilisé. Toutefois, vous pouvez toujours être facturé pour le stockage de l'image de conteneur dans Artifact Registry. Pour supprimer des dépôts Artifact Registry, suivez les étapes décrites dans la section Supprimer des dépôts de la documentation Artifact Registry.

Supprimer votre service

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, procédez comme suit :

Console

Pour supprimer un service, procédez comme suit :

1. Dans la Google Cloud console, accédez à la page Services de Cloud Run :

   Accédez à Cloud Run

2. Recherchez le service que vous souhaitez supprimer dans la liste des services, puis cliquez la case correspondante pour le sélectionner.

3. Cliquez sur Supprimer pour supprimer toutes les révisions du service. Cette opération supprime également toutes les révisions du service.

gcloud

Pour supprimer un service, exécutez la commande suivante :

gcloud run services delete SERVICE --region REGION

Remplacez les éléments suivants :

• SERVICE : nom de votre service.
• REGION : Google Cloud région du service.

Supprimer votre projet de test

La suppression de votre Google Cloud projet arrête la facturation de toutes les ressources de ce projet. Pour libérer toutes les Google Cloud ressources de votre projet, procédez comme suit :

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 appspot.com URL, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.

Supprimer un Google Cloud projet :

gcloud projects delete PROJECT_ID

Étape suivante

Pour savoir comment créer un conteneur à partir d'une source de code et le transférer vers un dépôt, consultez la section suivante :

• Développer votre service Cloud Run
• Créer des conteneurs
• Tester un service Cloud Run localement
• Déployer des fonctions à partir du code source