Kurzanleitung: Python-Webanwendung (smolagents) in Cloud Run erstellen und bereitstellen

Kurzanleitung: Python-Webanwendung (smolagents) in Cloud Run erstellen und bereitstellen

In diesem Dokument erfahren Sie, wie Sie eine smolagents-Anwendung erstellen und in Cloud Run bereitstellen.

Wenn Sie die Schritte in dieser Kurzanleitung ausführen, erstellt Cloud Run automatisch ein Dockerfile für Sie, wenn Sie aus dem Quellcode bereitstellen.

Hinweis

Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

Installieren Sie die Google Cloud CLI.

Hinweis:Wenn Sie die gcloud CLI zuvor installiert haben, prüfen Sie, ob Sie die aktuelle Version haben, indem Sie gcloud components update ausführen.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Erstellen Sie ein Google Cloud Projekt oder wählen Sie eines aus.

Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

• Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
• Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.

• So erstellen Sie ein Google Cloud -Projekt:

  gcloud projects create PROJECT_ID

  Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud -Projekt, das Sie erstellen.

• Wählen Sie das von Ihnen erstellte Google Cloud Projekt aus:

  gcloud config set project PROJECT_ID

  Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

Wenn Sie für diese Anleitung ein vorhandenes Projekt verwenden, prüfen Sie, ob Sie die erforderlichen Berechtigungen haben. Wenn Sie ein neues Projekt erstellt haben, haben Sie bereits die erforderlichen Berechtigungen.

Prüfen Sie, ob für Ihr Google Cloud Projekt die Abrechnung aktiviert ist.

Installieren Sie die Google Cloud CLI.

Hinweis:Wenn Sie die gcloud CLI zuvor installiert haben, prüfen Sie, ob Sie die aktuelle Version haben, indem Sie gcloud components update ausführen.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Erstellen Sie ein Google Cloud Projekt oder wählen Sie eines aus.

Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

• Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
• Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit dem Projekt verknüpften Ressourcen entfernen.

• So erstellen Sie ein Google Cloud -Projekt:

  gcloud projects create PROJECT_ID

  Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud -Projekt, das Sie erstellen.

• Wählen Sie das von Ihnen erstellte Google Cloud Projekt aus:

  gcloud config set project PROJECT_ID

  Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

Wenn Sie für diese Anleitung ein vorhandenes Projekt verwenden, prüfen Sie, ob Sie die erforderlichen Berechtigungen haben. Wenn Sie ein neues Projekt erstellt haben, haben Sie bereits die erforderlichen Berechtigungen.

Prüfen Sie, ob für Ihr Google Cloud Projekt die Abrechnung aktiviert ist.

1. Wenn Sie einer Domaineinschränkung zur Organisation nicht eingeschränkter Aufrufe für Ihr Projekt unterliegen, müssen Sie auf Ihren bereitgestellten Dienst zugreifen, wie unter Private Dienste testen beschrieben.

2. Aktivieren Sie die Cloud Run Admin API und die Cloud Build APIs:

   Rollen, die zum Aktivieren von APIs erforderlich sind

   Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere Informationen zum Zuweisen von Rollen

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

   Nachdem die Cloud Run Admin API aktiviert wurde, wird das Compute Engine-Standarddienstkonto automatisch erstellt.

3. Cloud Run-Preise ansehen oder Kosten mit dem Preisrechner schätzen
4. Sie benötigen einen API-Schlüssel von Google AI Studio, um die smolagents-App mit einem Gemini-Modell bereitzustellen. Informationen zum Generieren eines API-Schlüssels mit Google AI Studio finden Sie in der Gemini API-Dokumentation unter Gemini API-Schlüssel verwenden.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Ausführen der Kurzanleitung benötigen:

• Rolle Cloud Run Admin (roles/run.admin) im Projekt
• Cloud Run Source Developer (roles/run.sourceDeveloper) im Projekt
• Dienstkontonutzer (roles/iam.serviceAccountUser) für die Dienstidentität
• Loganzeige (roles/logging.viewer) für das Projekt

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Cloud Build-Dienstkonto Zugriff auf Ihr Projekt gewähren

Cloud Build verwendet automatisch das Compute Engine-Standarddienstkonto als Cloud Build-Standarddienstkonto, um Ihren Quellcode und Ihre Cloud Run-Ressource zu erstellen, sofern Sie dieses Verhalten nicht überschreiben.

Damit Cloud Build Ihre Quellen erstellen kann, weisen Sie dem Cloud Build-Dienstkonto die Rolle Cloud Run Builder (roles/run.builder) für Ihr Projekt zu:

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

Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID und SERVICE_ACCOUNT_EMAIL_ADDRESS durch die E-Mail-Adresse des Cloud Build-Dienstkontos. Google CloudWenn Sie das Compute Engine-Standarddienstkonto als Cloud Build-Dienstkonto verwenden, verwenden Sie das folgende Format für die E-Mail-Adresse des Dienstkontos:

[e-mail]

Ersetzen Sie PROJECT_NUMBER durch die Google CloudProjektnummer.

Eine detaillierte Anleitung zum Ermitteln der Projekt-ID und der Projektnummer finden Sie unter Projekte erstellen und verwalten.

Es dauert einige Minuten, bis die Zuweisung der Rolle „Cloud Run Builder“ übertragen wurde.

Beispielanwendung schreiben

So schreiben Sie eine Anwendung in Python:

1. Erstellen Sie ein neues Verzeichnis mit dem Namen my-agent-app und ersetzen Sie das aktuelle Verzeichnis durch dieses Verzeichnis:

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

2. Erstellen Sie eine Datei mit dem Namen main.py und fügen Sie den folgenden Code in diese ein:

   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. Erstellen Sie eine Datei mit dem Namen requirements.txt und fügen Sie den folgenden Code in diese ein:

   fastapi
   uvicorn
   smolagents[toolkit]
   litellm
   

Für Cloud Run aus Quelle bereitstellen

Beim Bereitstellen aus dem Quellcode wird automatisch ein Container-Image aus dem Quellcode erstellt und bereitgestellt.

Stellen Sie es mit dem folgenden Befehl aus der Quelle bereit:

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

Ersetzen Sie API_KEY durch Ihren Google AI Studio-API-Schlüssel.

In Cloud Run wird die Dienst-URL, z. B. https://smolagents-demo-xyz-uc.a.run.app, angezeigt, nachdem Sie die App erfolgreich bereitgestellt haben.

Erfolg:Sie haben eine smolagents-Webanwendung in Cloud Run bereitgestellt.

Cloud Run-Dienst testen

Testen Sie Ihren Dienst, indem Sie mit dem folgenden curl-Befehl eine Aufgabe an den Agent senden:

  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"}'

Ersetzen Sie YOUR-SERVICE-URL durch die URL Ihres Dienstes.

Der Agent sendet die folgende Antwort:

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

Prüfen Sie auf dem Tab Logs des Cloud Run-Dienstes, ob Ihr Dienst ordnungsgemäß funktioniert.

Bereinigen

Löschen Sie das Projekt von Google Cloud zusammen mit den Ressourcen, damit Ihrem Konto von Google Cloud die auf dieser Seite verwendeten Ressourcen nicht in Rechnung gestellt werden.

Damit Ihrem Google Cloud Konto keine zusätzlichen Gebühren in Rechnung gestellt werden, löschen Sie alle Ressourcen, die Sie mit dieser Kurzanleitung bereitgestellt haben.

Repository löschen

Für Cloud Run fallen keine Kosten an, wenn Ihr bereitgestellter Dienst nicht verwendet wird. Das Speichern des Container-Images in Artifact Registry ist jedoch möglicherweise kostenpflichtig. Wenn Sie Artifact Registry-Repositories löschen möchten, folgen Sie der Anleitung unter Repositories löschen in der Artifact Registry-Dokumentation.

Dienst löschen

Für Cloud Run-Dienste fallen erst Kosten an, wenn sie Anfragen empfangen. So löschen Sie Ihren Cloud Run-Dienst:

Console

So löschen Sie einen Dienst:

1. Rufen Sie in der Google Cloud Console die Seite Dienste für Cloud Run auf:

   Zu Cloud Run

2. Klicken Sie in der Übersicht das Kästchen des zu löschenden Dienstes an.

3. Klicken Sie auf Löschen. Dadurch werden alle Überarbeitungen des Dienstes gelöscht.

gcloud

Führen Sie den folgenden Befehl aus, um einen Dienst zu löschen:

gcloud run services delete SERVICE --region REGION

Ersetzen Sie Folgendes:

• SERVICE: Name Ihres Dienstes.
• REGION: Google Cloud Region des Dienstes.

Testprojekt löschen

Wenn Sie Ihr Google Cloud -Projekt löschen, wird die Abrechnung für alle Ressourcen in diesem Projekt beendet. So geben Sie alle Google Cloud Ressourcen in Ihrem Projekt frei:

Achtung: Das Löschen von Projekten hat folgende Auswirkungen:
• Alle Inhalte des Projekts werden gelöscht. Wenn Sie für die Aufgaben in diesem Dokument ein bereits bestehendes Projekt verwendet haben und dieses löschen, werden auch alle anderen im Rahmen des Projekts erstellten Daten gelöscht.
• Benutzerdefinierte Projekt-IDs gehen verloren. Beim Erstellen dieses Projekts haben Sie möglicherweise eine benutzerdefinierte Projekt-ID erstellt, die Sie weiterhin verwenden möchten. Damit die URLs, die die Projekt-ID nutzen, zum Beispiel eine appspot.com-URL, erhalten bleiben, sollten Sie ausgewählte Ressourcen innerhalb des Projekts löschen, anstatt das gesamte Projekt.

Google Cloud -Projekt löschen:

gcloud projects delete PROJECT_ID

Nächste Schritte

Weitere Informationen dazu, wie Sie einen Container aus Quellcode erstellen und diesen mithilfe eines Push-Vorgangs in ein Repository übertragen, finden Sie unter:

• Cloud Run-Dienste entwickeln
• Container erstellen
• Cloud Run-Dienst lokal testen
• Aus Quellcode bereitstellen