Kurzanleitung: KI-Agent mit dem Agent Development Kit (ADK) erstellen und in Cloud Run bereitstellen

Kurzanleitung: KI-Agent mit dem Agent Development Kit (ADK) erstellen und in Cloud Run bereitstellen

Hier erfahren Sie, wie Sie mit einem einzigen Befehl einen KI-Agenten mit dem Agent Development Kit (ADK) für Python erstellen und in Cloud Run bereitstellen. Der bereitgestellte Agent ruft den Wetterbericht für eine von Ihnen angegebene Stadt ab.

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

Weitere Informationen dazu, wie das Python-Buildpack den Standard einstiegspunkt für Cloud Run-Quellcodebereitstellungen bestimmt, finden Sie unter Python-Anwendung erstellen.

Hinweis

Melden Sie sich in Ihrem Google Cloud Konto an. Wenn Sie noch kein Konto bei Google Cloudhaben, erstellen Sie ein Konto, um die Leistung 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 neues Projekt oder wählen Sie ein vorhandenes Projekt Google Cloud aus.

Erforderliche Rollen zum Auswählen oder Erstellen eines Projekts

• Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können ein beliebiges 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 resourcemanager.projects.create Berechtigung enthält. Rollen zuweisen.

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 ihm verknüpften Ressourcen entfernen.

• Projekt erstellen: Google Cloud

  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 Ihren Google Cloud Projektnamen.

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 neues Projekt oder wählen Sie ein vorhandenes Projekt Google Cloud aus.

Erforderliche Rollen zum Auswählen oder Erstellen eines Projekts

• Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können ein beliebiges 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 resourcemanager.projects.create Berechtigung enthält. Rollen zuweisen.

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 ihm verknüpften Ressourcen entfernen.

• Projekt erstellen: Google Cloud

  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 Ihren Google Cloud Projektnamen.

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. Aktivieren Sie die Cloud Run Admin API, die Vertex AI API und die Cloud Build APIs:

   Erforderliche Rollen zum Aktivieren von APIs

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

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

2. Installieren Sie das ADK gemäß der Anleitung in der Dokumentation zum Agent Development Kit.

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

4. Informationen zu den Preisen für Cloud Run finden Sie auf der Preisseite. Sie können die Kosten auch mit dem Preisrechner schätzen .

Erforderliche Rollen

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

• Cloud Run-Quellcodeentwickler (roles/run.sourceDeveloper) für das Projekt
• Vertex AI-Nutzer (roles/aiplatform.user) für das Projekt
• Dienstkontonutzer (roles/iam.serviceAccountUser) für die Dienstidentität
• Logs-Betrachter (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-Standard Dienstkonto als Standard Cloud Build-Dienstkonto, um Ihren Quellcode und Ihre Cloud Run-Ressource zu erstellen, sofern Sie dieses Verhalten nicht überschreiben.

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

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

Ersetzen Sie PROJECT_ID durch Ihre Google Cloud Projekt-ID und SERVICE_ACCOUNT_EMAIL_ADDRESS durch die E-Mail-Adresse des Cloud Build-Dienstkontos. Wenn 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 Ihre Google Cloud Projektnummer.

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 übergeordnetes Verzeichnis mit dem Namen parent_folder und wechseln Sie dorthin:

   mkdir parent_folder
   cd parent_folder
   

2. Erstellen Sie im Verzeichnis parent_folder ein neues Unterverzeichnis mit dem Namen multi_tool_agent und wechseln Sie dorthin:

   mkdir multi_tool_agent
   cd multi_tool_agent
   

3. Erstellen Sie eine __init__.py-Datei, um den Agent zu importieren:

   from . import agent
   

4. Erstellen Sie eine agent.py-Datei, um den Agent zu definieren, der Fragen zur Uhrzeit und zum Wetter in einer bestimmten Stadt beantwortet:

   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. Erstellen Sie eine .env-Datei und fügen Sie die folgenden Variablen hinzu:

   GOOGLE_GENAI_USE_VERTEXAI=TRUE
   GOOGLE_CLOUD_PROJECT=PROJECT_ID
   GOOGLE_CLOUD_LOCATION=REGION
   

   Ersetzen Sie Folgendes:

   • PROJECT_ID: die Google Cloud Projekt-ID.
   • REGION: die Region, in der Sie Ihren Dienst bereitstellen möchten.

6. Wechseln Sie zum übergeordneten Verzeichnis parent_folder und erstellen Sie eine requirements.txt-Datei, um die Abhängigkeit google-adk hinzuzufügen:

   google-adk
   

   Ihr Quellprojekt hat die folgende Struktur:

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

Die Anwendung ist fertig und kann bereitgestellt werden.

Für Cloud Run aus Quelle bereitstellen

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

1. Stellen Sie in Ihrem Quellcodeverzeichnis (parent_folder) mit dem folgenden Befehl in Cloud Run bereit:

   gcloud run deploy --source .

   1. Wenn Sie zur Eingabe des Dienstnamens aufgefordert werden, drücken Sie die Eingabetaste, um den Standardnamen zu akzeptieren, z. B. weather-agent.

   2. Wenn Sie aufgefordert werden, zusätzliche APIs für das Projekt zu aktivieren, z. B. die Artifact Registry API, antworten Sie durch Drücken von y.

   3. Wenn Sie zur Eingabe der Region aufgefordert werden, wählen Sie die Region Ihrer Wahl aus, zum Beispiel europe-west1.

   4. Wenn Sie aufgefordert werden, ein Repository in der angegebenen Region zu erstellen, antworten Sie durch Drücken von y.

   5. Wenn Sie aufgefordert werden, öffentlichen Zugriff zu erlauben: antworten Sie mit y. Diese Eingabeaufforderung wird möglicherweise nicht angezeigt, wenn eine Organisationsrichtlinie zur Domaineinschränkung dies verhindert. Weitere Informationen finden Sie im Abschnitt Vorbereitung.

   Warten Sie dann einige Sekunden, bis die Bereitstellung abgeschlossen ist. Bei Erfolg wird in der Befehlszeile die Dienst-URL des bereitgestellten Agenten angezeigt. Sie hat das folgende Format: https://weather-agent-123456789101.us-central1.run.app/list-apps.

Agent ausführen

Wenn Sie den ADK-Agent verwenden möchten, können Sie die folgenden `curl`-Befehle ausführen:

1. Führen Sie den folgenden Befehl aus, um die Liste der Apps abzurufen:

   curl -X GET SERVICE_URL/list-apps
   

   Ersetzen Sie SERVICE_URL durch die URL Ihres bereitgestellten Dienstes.

2. Führen Sie den folgenden Befehl aus, um eine Sitzung zu starten:

   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. Führen Sie den folgenden Befehl aus, um den Agent abzufragen:

   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?\" }]}}"
   

Der Agent gibt die Wetterinformationen in den Ergebnissen Ihrer Abfrage zurück.

Weitere Informationen und Beispiele zu den unterstützten `curl`-Befehlen finden Sie in der ADK-Dokumentation unter API-Server verwenden.

Erfolg:Sie haben einen KI-Agenten mit dem Agent Development Kit in Cloud Run bereitgestellt.

Bereinigen

Löschen Sie alle Ressourcen , die Sie mit dieser Kurzanleitung bereitgestellt haben, um zusätzliche Kosten für Ihr Google Cloud Konto zu vermeiden.

Repository löschen

Cloud Run berechnet Ihnen keine Kosten, wenn Ihr bereitgestellter Dienst nicht verwendet wird. Möglicherweise werden Ihnen jedoch weiterhin Kosten für das Speichern des Container-Images in Artifact Registry in Rechnung gestellt. 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 erhalten. 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. 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, z. B. eine appspot.com URL, erhalten bleiben, sollten Sie ausgewählte Ressourcen innerhalb des Projekts löschen, statt das gesamte Projekt.

Projekt löschen: Google Cloud

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