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

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

Diese Funktion unterliegt den „Pre-GA-Angebotsbedingungen“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Funktionen sind „wie gesehen“ verfügbar und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie in den Beschreibungen der Produkteinführungsphasen.

Das Agent Development Kit (ADK) vereinfacht die Erstellung, Bewertung und Bereitstellung von KI-Agenten. Das ADK bietet einen modularen, Code-First-Ansatz zum Erstellen von Agenten, die Überlegungen anstellen, planen und Tools verwenden können.

In dieser Anleitung erfahren Sie, wie Sie einen KI-Agenten mit dem ADK für Python erstellen und in Cloud Run bereitstellen. Dieser Agent ruft den Wetterbericht für eine von Ihnen angegebene Stadt ab.

Weitere Informationen zum Hosten Ihres ADK-Agents mit der Google Cloud CLI finden Sie in der ADK-Dokumentation unter In Cloud Run bereitstellen.

Ziele

• Beispielanwendung schreiben, um den Wetter-Agenten zu definieren.
• Agent aus der Quelle in Cloud Run bereitstellen
• Führen Sie Ihren Agent aus, um Informationen zum Wetter abzufragen.

Kosten

In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:

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

Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen.

Neuen Nutzern von Google Cloud steht möglicherweise eine kostenlose Testversion zur Verfügung.

Hinweis

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. Richten Sie Ihre Cloud Run-Entwicklungsumgebung in Ihrem Google Cloud -Projekt ein.
3. Installieren Sie das ADK gemäß der Anleitung in der ADK-Dokumentation.

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

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, damit Sie die Berechtigungen erhalten, die Sie zum Bereitstellen eines KI-Agents in Cloud Run benötigen:

• Cloud Run Source Developer (roles/run.sourceDeveloper) im Projekt
• Vertex AI User (roles/aiplatform.user) 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.

Beispielanwendung schreiben

So schreiben Sie eine Anwendung in Python:

1. Erstellen Sie ein neues übergeordnetes Verzeichnis mit dem Namen parent_folder und ersetzen Sie das aktuelle Verzeichnis durch dieses Verzeichnis:

   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 zum Beantworten von Fragen zu Uhrzeit und Wetter in einer bestimmten Stadt zu definieren:

   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. 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 Ordnerverzeichnis parent_folder und erstellen Sie eine requirements.txt-Datei, um die google-adk-Abhängigkeit 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 beta 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 angezeigt. Rufen Sie über Ihre Dienst-URL /list-apps auf. Beispiel: https://weather-agent-123456789101.us-central1.run.app/list-apps

Agent ausführen

Führen Sie die folgenden curl-Befehle aus, um den ADK-Agenten abzufragen:

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

3. Führen Sie den folgenden Befehl aus, um den Agenten 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 Anfrage zurück.

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

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

Bereinigen

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

Projekt löschen

Wenn Sie ein neues Projekt für diese Anleitung erstellt haben, löschen Sie das Projekt. Wenn Sie ein vorhandenes Projekt verwendet haben und es beibehalten möchten, ohne die Änderungen in dieser Anleitung hinzuzufügen, löschen Sie die für die Anleitung erstellten Ressourcen.

Am einfachsten vermeiden Sie weitere Kosten, wenn Sie das zum Ausführen der Anleitung erstellte Projekt löschen.

So löschen Sie das Projekt:

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.

Wenn Sie mehrere Architekturen, Anleitungen und Kurzanleitungen durcharbeiten möchten, können Sie die Überschreitung von Projektkontingenten verhindern, indem Sie Projekte wiederverwenden.

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.

Anleitungsressourcen löschen

1. Löschen Sie den Cloud Run-Dienst, den Sie in dieser Anleitung bereitgestellt haben. Für Cloud Run-Dienste fallen erst Kosten an, wenn sie Anfragen empfangen.

   Führen Sie den folgenden Befehl aus, um Ihren Cloud Run-Dienst zu löschen:

   gcloud run services delete SERVICE-NAME

   Ersetzen Sie SERVICE-NAME durch den Namen Ihres Dienstes.

   Sie können Cloud Run-Dienste auch über die Google Cloud Console löschen.

2. Entfernen Sie die Konfiguration der Standardregion gcloud, die Sie während der Einrichtung für die Anleitung hinzugefügt haben:

    gcloud config unset run/region
   

3. Entfernen Sie die Projektkonfiguration:

    gcloud config unset project