Diese Seite wurde von der Cloud Translation API übersetzt.

ADK-Agent in Cloud Run bereitstellen, verwalten und beobachten

1. Einführung

In dieser Anleitung erfahren Sie, wie Sie einen leistungsstarken Agent, der mit dem Agent Development Kit (ADK) erstellt wurde, in Google Cloud Run bereitstellen, verwalten und überwachen. Mit dem ADK können Sie Agents erstellen, die komplexe Multi-Agent-Workflows ausführen können. Mit Cloud Run, einer vollständig verwalteten serverlosen Plattform, können Sie Ihren Agent als skalierbare, containerisierte Anwendung bereitstellen, ohne sich um die zugrunde liegende Infrastruktur kümmern zu müssen. Mit dieser leistungsstarken Kombination können Sie sich auf die Kernlogik Ihres Agents konzentrieren und gleichzeitig von der robusten und skalierbaren Umgebung von Google Cloud profitieren.

In diesem Tutorial wird die nahtlose Integration des ADK in Cloud Run erläutert. Sie erfahren, wie Sie Ihren Agent bereitstellen und wie Sie Ihre Anwendung in einer produktionsähnlichen Umgebung verwalten. Wir zeigen Ihnen, wie Sie neue Versionen Ihres Agents sicher einführen können, indem Sie den Traffic verwalten. So können Sie neue Funktionen mit einer Teilmenge von Nutzern testen, bevor Sie sie vollständig veröffentlichen.

Außerdem erhalten Sie praktische Erfahrung mit der Überwachung der Leistung Ihres Agents. Wir simulieren ein reales Szenario, indem wir einen Lasttest durchführen, um die automatischen Skalierungsfunktionen von Cloud Run in Aktion zu beobachten. Um detailliertere Informationen zum Verhalten und zur Leistung Ihres Agents zu erhalten, aktivieren wir das Tracing mit Cloud Trace. So erhalten Sie einen detaillierten End-to-End-Überblick über Anfragen, während sie durch Ihren Agent laufen. Dadurch können Sie Leistungsengpässe identifizieren und beheben. Am Ende dieser Anleitung haben Sie ein umfassendes Verständnis davon, wie Sie Ihre ADK-basierten Agents in Cloud Run effektiv bereitstellen, verwalten und überwachen.

In diesem Codelab gehen Sie schrittweise so vor:

PostgreSQL-Datenbank in CloudSQL für den ADK Agent-Datenbanksitzungsdienst erstellen
Einfachen ADK-Agent einrichten
Datenbanksitzungsdienst für die Verwendung durch ADK-Runner einrichten
Agent in Cloud Run bereitstellen
Cloud Run-Autoscaling mit Lasttests prüfen
Neue Agent-Überarbeitung bereitstellen und Traffic zu neuen Überarbeitungen schrittweise erhöhen
Cloud-Tracing einrichten und Agent-Lauf-Tracing prüfen

Architekturübersicht

Voraussetzungen

Vertrautheit mit Python
Grundkenntnisse der Full-Stack-Architektur mit HTTP-Dienst

Lerninhalte

ADK-Struktur und lokale Dienstprogramme
ADK-Agent mit dem Datenbank-Sitzungsdienst einrichten
PostgreSQL in Cloud SQL für die Verwendung durch den Datenbank-Sitzungsdienst einrichten
Anwendung mit Dockerfile in Cloud Run bereitstellen und anfängliche Umgebungsvariablen einrichten
Cloud Run-Autoscaling mit Lasttests konfigurieren und testen
Strategie für die schrittweise Veröffentlichung mit Cloud Run
ADK Agent-Tracing für Cloud Trace einrichten

Voraussetzungen

Chrome-Webbrowser
Ein Gmail-Konto
Ein Cloud-Projekt mit aktivierter Abrechnung

In diesem Codelab, das sich an Entwickler aller Erfahrungsstufen (auch Anfänger) richtet, wird Python in der Beispielanwendung verwendet. Python-Kenntnisse sind jedoch nicht erforderlich, um die vorgestellten Konzepte zu verstehen.

2. 🚀 Vorbereitung der Workshop-Entwicklung

Schritt 1: Aktives Projekt in der Cloud Console auswählen

Wählen Sie in der Google Cloud Console auf der Seite zur Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines (siehe oben links in der Console).

Klicken Sie darauf, um eine Liste aller Ihrer Projekte aufzurufen, wie in diesem Beispiel:

Der Wert, der durch das rote Kästchen angegeben wird, ist die PROJEKT-ID. Dieser Wert wird im gesamten Tutorial verwendet.

Die Abrechnung für das Cloud-Projekt muss aktiviert sein. Klicken Sie dazu links oben in der Leiste auf das Dreistrich-Menü ☰, um das Navigationsmenü aufzurufen, und suchen Sie nach dem Abrechnungsmenü.

Wenn Sie unter dem Titel Abrechnung / Übersicht ( oben links in der Cloud Console ) das Google Cloud Platform-Testabrechnungskonto sehen, kann Ihr Projekt für diese Anleitung verwendet werden. Falls nicht, kehren Sie zum Anfang dieses Tutorials zurück und lösen Sie das Abrechnungskonto für den Testzeitraum ein.

Schritt 2: Cloud SQL-Datenbank vorbereiten

Wir benötigen eine Datenbank, die später vom ADK-Agenten verwendet werden kann. Erstellen wir eine PostgreSQL-Datenbank in Cloud SQL. Rufen Sie zuerst die Suchleiste oben in der Cloud Console auf und geben Sie „Cloud SQL“ ein. Klicken Sie dann auf das Produkt Cloud SQL.

Danach müssen wir eine neue Datenbankinstanz erstellen. Klicken Sie dazu auf Instanz erstellen und wählen Sie PostgreSQL aus.

Möglicherweise müssen Sie auch die Compute Engine API aktivieren, wenn Sie mit einem neuen Projekt beginnen. Klicken Sie einfach auf API aktivieren, wenn diese Aufforderung angezeigt wird.

Als Nächstes wählen wir die Spezifikationen der Datenbank aus. Wählen Sie die Enterprise-Version mit der Sandbox-Versionsvoreinstellung aus.

Legen Sie dann hier den Instanznamen und das Standardpasswort für den Nutzer postgres fest. Sie können beliebige Anmeldedaten verwenden. In dieser Anleitung verwenden wir jedoch „adk-deployment“ als Instanznamen und „ADK-deployment123“ als Passwort.

In dieser Anleitung verwenden wir us-central1 mit einer einzelnen Zone. Wir können die Datenbankerstellung dann abschließen und die erforderliche Einrichtung durch Klicken auf die Schaltfläche Instanz erstellen abschließen lassen.

Während wir darauf warten, dass dieser Vorgang abgeschlossen wird, können wir mit dem nächsten Abschnitt fortfahren.

Schritt 3: Mit Cloud Shell vertraut machen

Für den Großteil der Anleitungen verwenden Sie Cloud Shell. Klicken Sie dazu oben in der Google Cloud Console auf „Cloud Shell aktivieren“. Wenn Sie zur Autorisierung aufgefordert werden, klicken Sie auf Autorisieren.

Nachdem Sie eine Verbindung zu Cloud Shell hergestellt haben, müssen wir prüfen, ob die Shell ( oder das Terminal) bereits mit Ihrem Konto authentifiziert ist.

gcloud auth list

Wenn Sie Ihr privates Gmail-Konto wie im Beispiel unten sehen, ist alles in Ordnung.

Credentialed Accounts

ACTIVE: *
ACCOUNT: alvinprayuda@gmail.com

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Falls nicht, aktualisieren Sie Ihren Browser und klicken Sie auf Autorisieren, wenn Sie dazu aufgefordert werden. Möglicherweise wurde die Verbindung unterbrochen.

Als Nächstes müssen wir prüfen, ob die Shell bereits für die richtige PROJEKT-ID konfiguriert ist. Wenn Sie im Terminal vor dem Symbol „$“ einen Wert in Klammern sehen (im Screenshot unten ist der Wert "adk-cloudrun-deployment-476504"), gibt dieser Wert das konfigurierte Projekt für Ihre aktive Shell-Sitzung an.

Wenn der angezeigte Wert bereits korrekt ist, können Sie den nächsten Befehl überspringen. Wenn sie nicht korrekt ist oder fehlt, führen Sie den folgenden Befehl aus:

gcloud config set project <YOUR_PROJECT_ID>

Klonen Sie dann das Arbeitsverzeichnis der Vorlage für dieses Codelab von GitHub, indem Sie den folgenden Befehl ausführen. Das Arbeitsverzeichnis wird im Verzeichnis deploy_and_manage_adk erstellt.

git clone https://github.com/alphinside/deploy-and-manage-adk-service.git deploy_and_manage_adk

Schritt 4: Cloud Shell-Editor kennenlernen und Arbeitsverzeichnis der Anwendung einrichten

Jetzt können wir unseren Code-Editor für einige Programmieraufgaben einrichten. Dazu verwenden wir den Cloud Shell-Editor.

Klicken Sie auf die Schaltfläche Editor öffnen, um den Cloud Shell-Editor zu öffnen.

Klicken Sie dann im oberen Bereich des Cloud Shell-Code-Editors auf Datei > Ordner öffnen, suchen Sie nach dem Verzeichnis username und dann nach dem Verzeichnis deploy_and_manage_adk und klicken Sie auf die Schaltfläche „OK“. Dadurch wird das ausgewählte Verzeichnis zum Hauptarbeitsverzeichnis. In diesem Beispiel ist der Nutzername alvinprayuda. Der Verzeichnispfad wird unten angezeigt.

Ihr Cloud Shell Editor-Arbeitsverzeichnis sollte nun so aussehen ( innerhalb von deploy_and_manage_adk):

Öffnen Sie nun das Terminal für den Editor. Klicken Sie dazu in der Menüleiste auf Terminal -> Neues Terminal oder verwenden Sie die Tastenkombination Strg + Umschalt + C. Dadurch wird unten im Browser ein Terminalfenster geöffnet.

Das aktuelle aktive Terminal sollte sich im Arbeitsverzeichnis deploy_and_manage_adk befinden. In diesem Codelab verwenden wir Python 3.12 und den uv-Python-Projektmanager, um das Erstellen und Verwalten von Python-Versionen und virtuellen Umgebungen zu vereinfachen. Das uv-Paket ist bereits in Cloud Shell vorinstalliert.

Führen Sie diesen Befehl aus, um die erforderlichen Abhängigkeiten in der virtuellen Umgebung im Verzeichnis .venv zu installieren.

uv sync --frozen

Jetzt müssen wir die erforderlichen APIs über den unten gezeigten Befehl aktivieren. Das kann etwas dauern.

gcloud services enable aiplatform.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       sqladmin.googleapis.com

Bei erfolgreicher Ausführung des Befehls sollte eine Meldung wie die unten gezeigte angezeigt werden:

Operation "operations/..." finished successfully.

Als Nächstes müssen wir Konfigurationsdateien für dieses Projekt einrichten.

Benennen Sie die Datei .env.example in .env um.

cp .env.example .env

Öffnen Sie die Datei .env und aktualisieren Sie den Wert GOOGLE_CLOUD_PROJECT mit Ihrer Projekt-ID.

# .env

# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True

# Database connection for session service
# DB_CONNECTION_NAME=your-db-connection-name

In diesem Codelab verwenden wir die vorkonfigurierten Werte für GOOGLE_CLOUD_LOCATION und GOOGLE_GENAI_USE_VERTEXAI.. DB_CONNECTION_NAME lassen wir vorerst auskommentiert.

Nun können wir mit dem nächsten Schritt fortfahren: die Agent-Logik prüfen und bereitstellen.

3. 🚀 Wetter-Agent mit ADK und Gemini 2.5 erstellen

Einführung in die ADK-Verzeichnisstruktur

Sehen wir uns zuerst an, was das ADK zu bieten hat und wie Sie den Agenten erstellen. Die vollständige ADK-Dokumentation finden Sie unter dieser URL . Das ADK bietet viele Dienstprogramme für die Ausführung von CLI-Befehlen. Einige davon sind :

Agent-Verzeichnisstruktur einrichten
Schnell Interaktion über CLI-Ein- und -Ausgabe ausprobieren
Schnelle Einrichtung der Web-Benutzeroberfläche für die lokale Entwicklung

Sehen wir uns nun die Agent-Struktur im Verzeichnis weather_agent an.

weather_agent/
├── __init__.py
├── agent.py
└── tool.py

Wenn Sie init.py und agent.py untersuchen, sehen Sie diesen Code.

# __init__.py

from weather_agent.agent import root_agent

__all__ = ["root_agent"]

# agent.py


import os
from pathlib import Path

import google.auth
from dotenv import load_dotenv
from google.adk.agents import Agent
from weather_agent.tool import get_weather

# Load environment variables from .env file in root directory
root_dir = Path(__file__).parent.parent
dotenv_path = root_dir / ".env"
load_dotenv(dotenv_path=dotenv_path)


# Use default project from credentials if not in .env
_, project_id = google.auth.default()
os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",
    instruction="""
You are a helpful AI assistant designed to provide accurate and useful information.
""",
    tools=[get_weather],
)

ADK Erläuterung zum Code

Dieses Skript enthält unsere Agent-Initialisierung, in der wir Folgendes initialisieren:

Legen Sie das zu verwendende Modell auf gemini-2.5-flash fest.
Stelle das Tool get_weather zur Unterstützung der Agent-Funktionalität als Wetter-Agent bereit.

Web-UI ausführen

Jetzt können wir mit dem Agent interagieren und sein Verhalten lokal untersuchen. Mit dem ADK können wir eine Web-UI für die Entwicklung verwenden, um zu interagieren und zu prüfen, was während der Interaktion passiert. Führen Sie den folgenden Befehl aus, um den lokalen Entwicklungsserver für die Benutzeroberfläche zu starten:

uv run adk web --port 8080

Es wird eine Ausgabe wie im folgenden Beispiel erzeugt. Das bedeutet, dass wir bereits auf die Weboberfläche zugreifen können.

INFO:     Started server process [xxxx]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8080.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

Klicken Sie nun oben im Cloud Shell Editor auf die Schaltfläche Webvorschau und wählen Sie Vorschau auf Port 8080 aus, um die Vorschau aufzurufen.

Auf der folgenden Webseite können Sie oben links im Drop-down-Menü verfügbare Agents auswählen ( in unserem Fall sollte es weather_agent sein) und mit dem Bot interagieren. Im linken Fenster werden während der Laufzeit des Agents viele Informationen zu den Protokolldetails angezeigt.

Versuchen Sie jetzt, mit dem Gerät zu interagieren. In der linken Leiste können wir den Ablauf für jede Eingabe untersuchen, um zu sehen, wie lange es dauert, bis der Agent die einzelnen Aktionen ausführt, bevor er die endgültige Antwort formuliert.

Dies ist eine der Beobachtbarkeitsfunktionen, die in das ADK integriert wurden. Derzeit wird sie lokal geprüft. Später sehen wir, wie dies in Cloud Trace integriert wird, damit wir einen zentralen Trace aller Anfragen haben.

4. 🚀 In Cloud Run bereitstellen

Stellen wir diesen Agent-Dienst jetzt in Cloud Run bereit. Im Rahmen dieser Demo wird dieser Dienst als öffentlicher Dienst bereitgestellt, auf den andere zugreifen können. Dies ist jedoch nicht die beste Vorgehensweise, da sie nicht sicher ist.

In diesem Codelab verwenden wir Dockerfile, um unseren Agent in Cloud Run bereitzustellen. An diesem Punkt haben wir bereits alle erforderlichen Dateien ( Dockerfile und server.py), um unsere Anwendungen in Cloud Run bereitzustellen. Darauf gehen wir später noch genauer ein.

Stellen Sie den Dienst zuerst bereit. Rufen Sie dazu das Cloud Shell-Terminal auf und prüfen Sie, ob das aktuelle Projekt auf Ihr aktives Projekt konfiguriert ist. Falls nicht, müssen Sie die Projekt-ID mit dem Befehl „gcloud configure“ festlegen:

gcloud config set project [PROJECT_ID]

Jetzt müssen wir die Datei .env noch einmal aufrufen und öffnen. Dort müssen wir die Variable DB_CONNECTION_NAME auskommentieren und mit dem richtigen Wert füllen.

# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True

# Database connection for session service
DB_CONNECTION_NAME=your-db-connection-name

Den Wert DB_CONNECTION_NAME finden Sie, wenn Sie noch einmal zu Cloud SQL wechseln und auf die von Ihnen erstellte Instanz klicken. Rufen Sie die Suchleiste oben in der Cloud Console auf und geben Sie „Cloud SQL“ ein. Klicken Sie dann auf das Produkt Cloud SQL.

Danach wird die zuvor erstellte Instanz angezeigt. Klicken Sie darauf.

Scrollen Sie auf der Instanzseite nach unten zum Abschnitt Mit dieser Instanz verbinden. Dort können Sie den Verbindungsnamen kopieren, um den Wert DB_CONNECTION_NAME zu ersetzen.

Öffnen Sie dann die Datei .env und ändern Sie die Variable DB_CONNECTION_NAME. Ihre ENV-Datei sollte wie im folgenden Beispiel aussehen.

# Google Cloud and Vertex AI configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True

# Database connection for session service
DB_CONNECTION_NAME=your-project-id:your-location:your-instance-name

Führen Sie danach das Bereitstellungsskript aus.

bash deploy_to_cloudrun.sh

Wenn Sie aufgefordert werden, die Erstellung eines Artifact Registry-Repositorys für Docker zu bestätigen, antworten Sie einfach mit Y.

Während wir auf den Abschluss des Bereitstellungsvorgangs warten, sehen wir uns deploy_to_cloudrun.sh an.

#!/bin/bash

# Load environment variables from .env file
if [ -f .env ]; then
    export $(cat .env | grep -v '^#' | xargs)
else
    echo "Error: .env file not found"
    exit 1
fi

# Validate required variables
required_vars=("GOOGLE_CLOUD_PROJECT" "DB_CONNECTION_NAME")
for var in "${required_vars[@]}"; do
    if [ -z "${!var}" ]; then
        echo "Error: $var is not set in .env file"
        exit 1
    fi
done

gcloud run deploy weather-agent \
    --source . \
    --port 8080 \
    --project ${GOOGLE_CLOUD_PROJECT} \
    --allow-unauthenticated \
    --add-cloudsql-instances ${DB_CONNECTION_NAME} \
    --update-env-vars SESSION_SERVICE_URI="postgresql+pg8000://postgres:ADK-deployment123@postgres/?unix_sock=/cloudsql/${DB_CONNECTION_NAME}/.s.PGSQL.5432",GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT} \
    --region us-central1 \
    --min 1 \
    --memory 1G \
    --concurrency 10

In diesem Skript wird die Variable .env geladen und dann der Bereitstellungsbefehl ausgeführt.

Bei genauerer Betrachtung benötigen wir nur einen gcloud run deploy-Befehl, um alle erforderlichen Schritte auszuführen, die beim Bereitstellen eines Dienstes anfallen: Erstellen des Images, Push in die Registry, Bereitstellen des Dienstes, Festlegen der IAM-Richtlinie, Erstellen der Revision und sogar Weiterleiten des Traffics. In diesem Beispiel stellen wir das Dockerfile bereits zur Verfügung. Dieser Befehl verwendet es also, um die App zu erstellen.

Nach Abschluss der Bereitstellung sollten Sie einen Link ähnlich dem folgenden erhalten:

https://weather-agent-*******.us-central1.run.app

Nachdem Sie diese URL erhalten haben, können Sie Ihre Anwendung über das Inkognitofenster oder Ihr Mobilgerät verwenden und auf die Entwickler-UI des Agents zugreifen. Während wir auf das Deployment warten, sehen wir uns im nächsten Abschnitt den detaillierten Dienst an, den wir gerade bereitstellen.

5. 💡 Dockerfile und Back-End-Server-Script

Damit der Agent als Dienst zugänglich ist, wird er in eine FastAPI-App eingebunden, die mit dem Dockerfile-Befehl ausgeführt wird. Nachfolgend finden Sie den Inhalt des Dockerfile.

FROM python:3.12-slim

RUN pip install --no-cache-dir uv==0.7.13

WORKDIR /app

COPY . .

RUN uv sync --frozen

EXPOSE 8080

CMD ["uv", "run", "uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8080"]

Hier können wir die erforderlichen Dienste zur Unterstützung des Agents konfigurieren, z. B. die Vorbereitung des Session-, Memory- oder Artifact-Dienstes für Produktionszwecke. Hier ist der Code der Datei server.py, die verwendet wird.

import os

from dotenv import load_dotenv
from fastapi import FastAPI
from google.adk.cli.fast_api import get_fast_api_app
from pydantic import BaseModel
from typing import Literal
from google.cloud import logging as google_cloud_logging


# Load environment variables from .env file
load_dotenv()

logging_client = google_cloud_logging.Client()
logger = logging_client.logger(__name__)

AGENT_DIR = os.path.dirname(os.path.abspath(__file__))

# Get session service URI from environment variables
session_uri = os.getenv("SESSION_SERVICE_URI", None)

# Prepare arguments for get_fast_api_app
app_args = {"agents_dir": AGENT_DIR, "web": True, "trace_to_cloud": True}

# Only include session_service_uri if it's provided
if session_uri:
    app_args["session_service_uri"] = session_uri
else:
    logger.log_text(
        "SESSION_SERVICE_URI not provided. Using in-memory session service instead. "
        "All sessions will be lost when the server restarts.",
        severity="WARNING",
    )

# Create FastAPI app with appropriate arguments
app: FastAPI = get_fast_api_app(**app_args)

app.title = "weather-agent"
app.description = "API for interacting with the Agent weather-agent"


class Feedback(BaseModel):
    """Represents feedback for a conversation."""

    score: int | float
    text: str | None = ""
    invocation_id: str
    log_type: Literal["feedback"] = "feedback"
    service_name: Literal["weather-agent"] = "weather-agent"
    user_id: str = ""


# Example if you want to add your custom endpoint
@app.post("/feedback")
def collect_feedback(feedback: Feedback) -> dict[str, str]:
    """Collect and log feedback.

    Args:
        feedback: The feedback data to log

    Returns:
        Success message
    """
    logger.log_struct(feedback.model_dump(), severity="INFO")
    return {"status": "success"}


# Main execution
if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=8080)

Erläuterung zum Servercode

Folgendes wird im Skript server.py definiert:

Wandeln Sie den Agent mit der Methode get_fast_api_app in eine FastAPI-App um. So wird dieselbe Routendefinition übernommen, die für die Webentwicklungs-Benutzeroberfläche verwendet wird.
Konfigurieren Sie den erforderlichen Sitzungs-, Speicher- oder Artefaktdienst, indem Sie die Keyword-Argumente der Methode get_fast_api_app hinzufügen. Wenn wir in dieser Anleitung die Umgebungsvariable SESSION_SERVICE_URI konfigurieren, wird sie vom Sitzungsdienst verwendet. Andernfalls wird die In-Memory-Sitzung verwendet.
Wir können eine benutzerdefinierte Route hinzufügen, um andere Backend-Geschäftslogik zu unterstützen. Im Skript fügen wir ein Beispiel für eine Feedbackfunktionsroute hinzu.
Aktivieren Sie Cloud Tracing in den get_fast_api_app-Argumentparametern, um Traces an Google Cloud Trace zu senden.
FastAPI-Dienst mit Uvicorn ausführen

Wenn Ihre Bereitstellung bereits abgeschlossen ist, versuchen Sie, über die Cloud Run-URL in der Web-Entwickler-UI mit dem Agent zu interagieren.

6. 🚀 Cloud Run-Autoscaling mit Lasttests untersuchen

Als Nächstes sehen wir uns die Autoscaling-Funktionen von Cloud Run an. In diesem Szenario stellen wir eine neue Version bereit und aktivieren die maximale Anzahl von Nebenläufigkeiten pro Instanz. Im vorherigen Abschnitt haben wir die maximale Parallelität auf 10 festgelegt ( Flag --concurrency 10). Daher können wir davon ausgehen, dass Cloud Run versucht, die Instanz zu skalieren, wenn wir einen Lastentest durchführen, der diese Zahl überschreitet.

Sehen wir uns die Datei load_test.py an. Dieses Skript verwenden wir für die Lasttests mit dem Locust-Framework. Dieses Skript führt folgende Aktionen aus :

Zufällig erstellte user_id und session_id
session_id für die user_id erstellen
Endpunkt „/run_sse“ mit der erstellten „user_id“ und „session_id“ aufrufen

Wir benötigen die URL des bereitgestellten Dienstes, falls Sie sie nicht notiert haben. Rufen Sie die Cloud Run Console auf und klicken Sie auf den Dienst weather-agent.

Suchen Sie dann nach dem Dienst weather-agent und klicken Sie darauf.

Die Dienst-URL wird direkt neben den Regionsinformationen angezeigt. Beispiel:

Führen Sie dann den folgenden Befehl aus, um den Lasttest durchzuführen:

uv run locust -f load_test.py \
              -H {YOUR_SERVICE_URL} \
              -u 60 \
              -r 5 \
              -t 120 \
              --headless

Wenn Sie diesen Befehl ausführen, werden Messwerte wie die folgenden angezeigt. ( In diesem Beispiel sind alle Anforderungen erfüllt. )

Type     Name                                  # reqs      # fails |    Avg     Min     Max    Med |   req/s  failures/s
--------|------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
POST     /run_sse end                             813     0(0.00%) |   5817    2217   26421   5000 |    6.79        0.00
POST     /run_sse message                         813     0(0.00%) |   2678    1107   17195   2200 |    6.79        0.00
--------|------------------------------------|-------|-------------|-------|-------|-------|-------|--------|-----------
         Aggregated                              1626     0(0.00%) |   4247    1107   26421   3500 |   13.59        0.00

Sehen wir uns dann an, was in Cloud Run passiert ist. Rufen Sie dazu noch einmal Ihren bereitgestellten Dienst auf und sehen Sie sich das Dashboard an. So sehen Sie, wie Cloud Run die Instanz automatisch skaliert, um eingehende Anfragen zu verarbeiten. Da wir die maximale Nebenläufigkeit auf 10 pro Instanz begrenzen, versucht die Cloud Run-Instanz, die Anzahl der Container automatisch an diese Bedingung anzupassen.

7. 🚀 Neue Überarbeitungen schrittweise veröffentlichen

Stellen wir uns nun das folgende Szenario vor. Wir möchten den Prompt des Agents aktualisieren. Öffnen Sie weather_agent/agent.py und überschreiben Sie den Inhalt mit dem folgenden Code:

# weather_agent/agent.py

import os
from pathlib import Path

import google.auth
from dotenv import load_dotenv
from google.adk.agents import Agent
from weather_agent.tool import get_weather

# Load environment variables from .env file in root directory
root_dir = Path(__file__).parent.parent
dotenv_path = root_dir / ".env"
load_dotenv(dotenv_path=dotenv_path)


# Use default project from credentials if not in .env
_, project_id = google.auth.default()
os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id)
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True")

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",
    instruction="""
You are a helpful AI assistant designed to provide accurate and useful information.
You only answer inquiries about the weather. Refuse all other user query
""",
    tools=[get_weather],
)

Sie möchten dann neue Überarbeitungen veröffentlichen, aber nicht, dass der gesamte Anfragetraffic direkt an die neue Version gesendet wird. Mit Cloud Run können wir eine schrittweise Einführung durchführen. Zuerst müssen wir eine neue Überarbeitung bereitstellen, aber mit dem Flag –no-traffic. Speichern Sie das vorherige Agent-Skript und führen Sie den folgenden Befehl aus:

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project {YOUR_PROJECT_ID} \
                  --allow-unauthenticated \
                  --region us-central1 \
                  --no-traffic

Danach erhalten Sie ein ähnliches Log wie beim vorherigen Deployment-Prozess, mit dem Unterschied, dass die Anzahl der bereitgestellten Zugriffe angegeben ist. Es werden 0 % des Traffics angezeigt.

Service [weather-agent] revision [weather-agent-xxxx-xxx] has been deployed and is serving 0 percent of traffic.

Rufen Sie als Nächstes die Cloud Run-Produktseite auf und suchen Sie nach Ihrer bereitgestellten Instanz. Geben Sie „Cloud Run“ in die Suchleiste ein und klicken Sie auf das Cloud Run-Produkt.

Suchen Sie dann nach dem Dienst weather-agent und klicken Sie darauf.

Rufen Sie den Tab Überarbeitungen auf. Dort wird die Liste der bereitgestellten Überarbeitungen angezeigt.

Die neue bereitgestellte Überarbeitung wird mit 0 % ausgeliefert. Klicken Sie auf das Dreipunkt-Menü (⋮) und wählen Sie Traffic verwalten aus.

Im neu geöffneten Fenster können Sie den Prozentsatz des Traffics bearbeiten, der an die einzelnen Überarbeitungen gesendet wird.

Nach einer Weile wird der Traffic proportional entsprechend den Prozentkonfigurationen weitergeleitet. So können wir bei Problemen mit dem neuen Release ganz einfach ein Rollback zu den vorherigen Überarbeitungen durchführen.

8. 🚀 ADK-Tracing

Mit dem ADK erstellte Agents unterstützen bereits das Tracing, da OpenTelemetry darin eingebettet ist. Mit Cloud Trace können wir diese Traces erfassen und visualisieren. Sehen wir uns an, wie wir den Dienst in server.py aktivieren.

# server.py

...

app_args = {"agents_dir": AGENT_DIR, "web": True, "trace_to_cloud": True}

...

app: FastAPI = get_fast_api_app(**app_args)

...

Hier übergeben wir das trace_to_cloud-Argument an True. Wenn Sie die Bereitstellung mit anderen Optionen vornehmen, finden Sie in dieser Dokumentation weitere Informationen dazu, wie Sie das Tracing zu Cloud Trace über verschiedene Bereitstellungsoptionen aktivieren.

Versuchen Sie, auf die Web-UI Ihres Dienstes zuzugreifen und mit dem Agent zu chatten. Geben Sie dann in der Suchleiste der Cloud Console „Trace Explorer“ ein und wählen Sie das Produkt Trace Explorer aus.

Auf der Seite „Trace Explorer“ (Trace-Explorer) sehen Sie, dass der Unterhaltungs-Trace mit dem Agenten gesendet wurde. Im Abschnitt Span-Name können Sie den Span für unseren Agent sehen ( er heißt agent_run [weather_agent]) und ihn herausfiltern.

Wenn die Spannen bereits gefiltert sind, können Sie auch jede einzelne Spur direkt untersuchen. Dort wird die genaue Dauer jeder Aktion angezeigt, die vom Agent ausgeführt wurde. Sehen Sie sich beispielsweise die Bilder unten an.

In jedem Abschnitt können Sie die Details in den Attributen prüfen, wie unten dargestellt.

So haben wir jetzt eine gute Beobachtbarkeit und Informationen zu jeder Interaktion unseres Agenten mit dem Nutzer, um Probleme zu beheben. Probieren Sie ruhig verschiedene Tools oder Workflows aus.

9. 🎯 Herausforderung

Testen Sie Multi-Agent- oder Agent-Workflows, um zu sehen, wie sie unter Last funktionieren und wie der Trace aussieht.

10. 🧹 Bereinigen

So vermeiden Sie, dass Ihrem Google Cloud-Konto die in diesem Codelab verwendeten Ressourcen in Rechnung gestellt werden:

Wechseln Sie in der Google Cloud Console zur Seite Ressourcen verwalten.
Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie auf Löschen.
Geben Sie im Dialogfeld die Projekt-ID ein und klicken Sie auf Beenden, um das Projekt zu löschen.
Alternativ können Sie in der Console zu Cloud Run wechseln, den gerade bereitgestellten Dienst auswählen und löschen.