ADK-Agent in Cloud Run bereitstellen, verwalten und beobachten

1. Einführung

WICHTIGE HINWEISE:

Für diese Anleitung ist ein Google Cloud-Projekt mit einem aktiven Rechnungskonto erforderlich. Wenn Sie noch keines haben, folgen Sie der Anleitung unten, um ein Testabrechnungskonto zu erstellen, das Sie für dieses Tutorial verwenden können:

1. Inkognitofenster öffnen
2. Rufen Sie dieses Einlösungsportal für Test-Rechnungskonten auf.
3. Melden Sie sich mit Ihrem privaten Gmail-Konto an. Google Workspace- oder andere E‑Mail-Adressen funktionieren nicht. )
4. Schritt-für-Schritt-Anleitung

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 erkennen 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:

1. PostgreSQL-Datenbank in CloudSQL für den ADK Agent-Datenbanksitzungsdienst erstellen
2. Einfachen ADK-Agent einrichten
3. Datenbanksitzungsdienst für die Verwendung durch ADK-Runner einrichten
4. Agent zum ersten Mal in Cloud Run bereitstellen
5. Cloud Run-Autoscaling mit Lasttests prüfen
6. Neue Agent-Überarbeitung bereitstellen und Traffic zu neuen Überarbeitungen schrittweise erhöhen
7. Cloud-Tracing einrichten und Agent-Laufzeit-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. Hinweis

Aktives Projekt in der Cloud Console auswählen

In diesem Codelab wird davon ausgegangen, dass Sie bereits ein Google Cloud-Projekt mit aktivierter Abrechnung haben. Wenn Sie noch kein Konto haben, können Sie der Anleitung unten folgen, um loszulegen.

1. Wählen Sie in der Google Cloud Console auf der Seite zur Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
2. Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist.

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-Voreinstellung 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“ für den Instanznamen und das Passwort.

Wichtig! Nutzername und Passwort sind vertrauliche Daten. Achten Sie darauf, dass Sie diese Werte vor anderen geheim gehalten haben.

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.

Haben Sie Geduld. Es dauert etwa 5 bis 10 Minuten,bis die Datenbank erstellt ist.

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

Cloud-Projekt im Cloud Shell-Terminal einrichten

1. Sie verwenden Cloud Shell, eine Befehlszeilenumgebung, die in Google Cloud ausgeführt wird. Klicken Sie oben in der Google Cloud Console auf „Cloud Shell aktivieren“.

2. Wenn Sie mit Cloud Shell verbunden sind, können Sie mit dem folgenden Befehl prüfen, ob Sie bereits authentifiziert sind und das Projekt auf Ihre Projekt-ID festgelegt ist:

gcloud auth list

3. Führen Sie den folgenden Befehl in Cloud Shell aus, um zu bestätigen, dass der gcloud-Befehl Ihr Projekt kennt.

gcloud config list project

4. Wenn Ihr Projekt nicht festgelegt ist, verwenden Sie den folgenden Befehl, um es festzulegen:

gcloud config set project <YOUR_PROJECT_ID>

Alternativ können Sie die PROJECT_ID-ID auch in der Console sehen.

Klicken Sie darauf. Rechts sehen Sie dann alle Ihre Projekte und die Projekt-ID.

5. Aktivieren Sie die erforderlichen APIs mit dem unten gezeigten Befehl. Dies kann einige Minuten 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.

Alternativ zum gcloud-Befehl können Sie in der Konsole nach den einzelnen Produkten suchen oder diesen Link verwenden.

Wenn eine API fehlt, können Sie sie jederzeit während der Implementierung aktivieren.

Informationen zu gcloud-Befehlen und deren Verwendung finden Sie in der Dokumentation.

Cloud Shell-Editor aufrufen und Arbeitsverzeichnis der Anwendung einrichten

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

1. Klicken Sie auf die Schaltfläche „Editor öffnen“. Dadurch wird ein Cloud Shell-Editor geöffnet, in dem wir unseren Code schreiben können 
2. Achten Sie darauf, dass das Cloud Code-Projekt in der Statusleiste unten links im Cloud Shell-Editor festgelegt ist, wie im Bild unten dargestellt, und auf das aktive Google Cloud-Projekt festgelegt ist, in dem die Abrechnung aktiviert ist. Autorisieren, wenn Sie dazu aufgefordert werden. Wenn Sie den vorherigen Befehl bereits ausgeführt haben, wird die Schaltfläche möglicherweise direkt zu Ihrem aktivierten Projekt weitergeleitet und nicht zur Schaltfläche „Anmelden“.

Bitte haben Sie etwas Geduld. Nach der Initialisierung des Cloud Shell-Editors kann es eine Weile dauern, bis die Schaltfläche Cloud Code – Anmelden angezeigt wird.

3. Als Nächstes klonen wir das Arbeitsverzeichnis der Vorlage für dieses Codelab von GitHub. Führen Sie dazu den folgenden Befehl aus. 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

4. Klicken Sie dann im oberen Bereich des Cloud Shell-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 sollte jetzt so aussehen:

Als Nächstes können wir die Einrichtung unserer Python-Umgebung konfigurieren.

Umgebung einrichten

Virtuelle Python-Umgebung vorbereiten

Im nächsten Schritt bereiten Sie die Entwicklungsumgebung vor. Ihr aktuelles aktives Terminal-Arbeitsverzeichnis 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.

1. Wenn Sie das Terminal noch nicht geöffnet haben, klicken Sie auf Terminal > Neues Terminal oder verwenden Sie Strg + Umschalt + C. Dadurch wird ein Terminalfenster im unteren Bereich des Browsers geöffnet.

2. Laden Sie uv herunter und installieren Sie Python 3.12 mit dem folgenden Befehl:

curl -LsSf https://astral.sh/uv/0.6.16/install.sh | sh && \
source $HOME/.local/bin/env && \
uv python install 3.12

3. Initialisieren wir jetzt die virtuelle Umgebung mit uv. Führen Sie diesen Befehl aus:

uv sync --frozen

Dadurch wird das Verzeichnis .venv erstellt und die Abhängigkeiten werden installiert. Ein kurzer Blick in die Datei pyproject.toml gibt Ihnen Informationen zu den Abhängigkeiten, die so angezeigt werden:

dependencies = [
    "google-adk==1.3.0",
    "locust==2.37.10",
    "pg8000==1.31.2",
    "python-dotenv==1.1.0",
]

Hinweis:Python-Abhängigkeiten werden in pyproject.toml deklariert und in der Datei uv.lock versionsgesperrt.

4. Um die virtuelle Umgebung zu testen, erstellen Sie die neue Datei main.py und kopieren Sie den folgenden Code.

def main():
   print("Hello from deploy_and_manage_adk!")

if __name__ == "__main__":
   main()

5. Führen Sie dann den folgenden Befehl aus:

uv run main.py

Die Ausgabe sollte in etwa so aussehen:

Using CPython 3.12
Creating virtual environment at: .venv
Hello from deploy_and_manage_adk!

Das zeigt, dass das Python-Projekt richtig eingerichtet wird.

Hinweis:Wir mussten keine virtuelle Umgebung manuell erstellen oder aktivieren, da uv dies bereits erledigt. Ab diesem Punkt werden Standard-Python-Befehle (z.B. python main.py) durch uv run (z.B. uv run main.py) ersetzt.

Konfigurationsdateien einrichten

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

Benennen Sie die Datei .env.example in .env um. Der Wert wird dann unten angezeigt. Aktualisieren Sie den Wert von GOOGLE_CLOUD_PROJECT mit Ihrer Projekt-ID.

# 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
# SESSION_SERVICE_URI=postgresql+pg8000://<username>:<password>@/<database>?unix_sock=/cloudsql/<instance_connection_name>/.s.PGSQL.5432

Wichtiger Hinweis:Aktualisieren Sie die Werte von GOOGLE_CLOUD_PROJECT mit Ihrer Projekt-ID.

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

Nun können wir zum nächsten Schritt übergehen: 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 uns 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

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 google.cloud import logging as google_cloud_logging

# 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")

logging_client = google_cloud_logging.Client()
logger = logging_client.logger("weather-agent")


def get_weather(city: str) -> dict:
    """Retrieves the current weather report for a specified city.

    Args:
        city (str): The name of the city (e.g., "New York", "London", "Tokyo").

    Returns:
        dict: A dictionary containing the weather information.
              Includes a 'status' key ('success' or 'error').
              If 'success', includes a 'report' key with weather details.
              If 'error', includes an 'error_message' key.
    """
    logger.log_text(
        f"--- Tool: get_weather called for city: {city} ---", severity="INFO"
    )  # Log tool execution
    city_normalized = city.lower().replace(" ", "")  # Basic normalization

    # Mock weather data
    mock_weather_db = {
        "newyork": {
            "status": "success",
            "report": "The weather in New York is sunny with a temperature of 25°C.",
        },
        "london": {
            "status": "success",
            "report": "It's cloudy in London with a temperature of 15°C.",
        },
        "tokyo": {
            "status": "success",
            "report": "Tokyo is experiencing light rain and a temperature of 18°C.",
        },
    }

    if city_normalized in mock_weather_db:
        return mock_weather_db[city_normalized]
    else:
        return {
            "status": "error",
            "error_message": f"Sorry, I don't have weather information for '{city}'.",
        }


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],
)

Hinweis:Die Verzeichnisstruktur, der Agent-Import in init.py und die root_agent-Deklaration in agent.py sind die obligatorische Struktur , die von der ADK-Befehlszeile erkannt werden muss.

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

Erinnerung Wir beenden jetzt den adk web-Prozess. Drücken Sie dazu STRG + C.

4. Das Backend-Server-Skript

Damit der Agent als Dienst zugänglich ist, wird er in eine FastAPI-App eingebunden. Hier können wir die erforderlichen Dienste zur Unterstützung des Agents konfigurieren, z. B. die Vorbereitung von Session-, Memory- oder Artifact-Diensten 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
from tracing import CloudTraceLoggingSpanExporter
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider, export


# 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}

# 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",
    )

provider = TracerProvider()
processor = export.BatchSpanProcessor(CloudTraceLoggingSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

# 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 = ""


@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:

1. 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.
2. 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.
3. 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.
4. Cloud Tracing aktivieren, um Traces an Google Cloud Trace zu senden

5. 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. Beachten Sie jedoch, dass dies keine Best Practices sind, da sie nicht sicher sind.

In diesem Codelab verwenden wir Dockerfile, um unseren Agent in Cloud Run bereitzustellen. Nachfolgend finden Sie den Inhalt des Dockerfile, der verwendet wird.

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"]

Wir haben jetzt alle Dateien, die zum Bereitstellen unserer Anwendungen in Cloud Run erforderlich sind. Stellen wir sie also bereit. Rufen Sie das Cloud Shell-Terminal auf und prüfen Sie, ob das aktuelle Projekt für 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]

Führen Sie dann den folgenden Befehl aus, um die Anwendung in Cloud Run bereitzustellen.

gcloud run deploy weather-agent \
                  --source . \
                  --port 8080 \
                  --project {YOUR_PROJECT_ID} \
                  --allow-unauthenticated \
                  --add-cloudsql-instances {YOUR_DB_CONNECTION_NAME} \
                  --update-env-vars SESSION_SERVICE_URI="postgresql+pg8000://postgres:{YOUR_DEFAULT_USER_PASS}@postgres/?unix_sock=/cloudsql/{YOUR_DB_CONNECTION_NAME}/.s.PGSQL.5432",GOOGLE_CLOUD_PROJECT={YOUR_PROJECT_ID} \
                  --region us-central1

Wichtiger Hinweis:Aktualisieren Sie hier die Werte für YOUR_DB_CONNECTION_NAME, YOUR_DEFAULT_USER_PASS und YOUR_PROJECT_ID.

Beachten Sie außerdem, dass wir SESSION_SERVICE_URI hier als Umgebungsvariablen für das Tutorial bereitstellen. Dies wird nicht empfohlen, da dadurch der Datenbanknutzername und das Datenbankpasswort offengelegt werden. Verwenden Sie in diesem Fall ein Secret.

Den Wert {YOUR_DB_CONNECTION_NAME} finden Sie, wenn Sie noch einmal zu Cloud SQL wechseln und auf die von Ihnen erstellte Instanz klicken. Scrollen Sie auf der Instanzseite nach unten zum Abschnitt Mit dieser Instanz verbinden. Dort können Sie den Verbindungsnamen kopieren, um den Wert {YOUR_DB_CONNECTION_NAME} zu ersetzen. Sehen Sie sich beispielsweise das Bild unten an.

Hinweis:Wenn SESSION_SERVICE_URI eingerichtet ist, verwendet unser ADK-Agent den URI für den Dienst, um die Sitzungsinformationen und den Status zu speichern. In dieser Anleitung verwenden wir eine PostgreSQL-Unix-Socket-Verbindung mit dem pg8000-Treiber.

Hinweis: Im Beispiel verwenden wir den Standardnutzer postgres und die Standarddatenbank postgres. Wenn Sie dieselben Werte wie in der Anleitung verwenden, sollte SESSION_SERVICE_URI so aussehen:

SESSION_SERVICE_URI="postgresql+pg8000://postgres:adk-deployment@postgres/?unix_sock=/cloudsql/{YOUR_PROJECT_ID}:us-central1:adk-deployment/.s.PGSQL.5432"

Sie müssen daher nur die Projekt-ID ersetzen.

Wenn Sie aufgefordert werden, die Erstellung eines Artifact Registry-Repositorys für Docker zu bestätigen, antworten Sie einfach mit Y. Hinweis: Wir erlauben hier den nicht authentifizierten Zugriff, da es sich um eine Demoanwendung handelt. Wir empfehlen, für Ihre Unternehmens- und Produktionsanwendungen eine geeignete Authentifizierung zu verwenden.

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

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

Sie können Ihre Anwendung nun im Inkognitofenster oder auf Ihrem Mobilgerät verwenden. Sie sollte bereits aktiv sein.

6. Cloud Run-Autoscaling mit Lasttests prüfen

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

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

Wichtiger Hinweis:Aktualisieren Sie hier die Werte von YOUR_PROJECT_ID.

Sehen wir uns danach 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 :

1. Zufällig erstellte user_id und session_id
2. session_id für die user_id erstellen
3. 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

Wichtiger Hinweis:Aktualisieren Sie hier die Werte von YOUR_SERVICE_URL.

Hinweis:Dadurch wird ein Hochfahren von 0 bis 60 parallelen Nutzeranfragen mit einer Rate von 5 Nutzern pro Sekunde über einen Zeitraum von 120 Sekunden simuliert.

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 Anfragen pro Instanz begrenzen, versucht die Cloud Run-Instanz, die Anzahl der Container automatisch an diese Bedingung anzupassen.

Hinweis:Sie können nicht nur die maximale Gleichzeitigkeit, sondern auch die Mindest- und Höchstanzahl von Containerinstanzen steuern. Weitere Informationen finden Sie in der SDK-Dokumentation.

7. Neue Überarbeitungen nach und nach veröffentlichen

Stellen Sie sich nun folgendes Szenario vor. Wir möchten den Prompt des Agents auf Folgendes aktualisieren :

# agent.py

...

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash-preview-05-20",
    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 Veröffentlichung 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

Wichtiger Hinweis:Aktualisieren Sie hier die Werte von YOUR_PROJECT_ID.

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.

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 ganz einfach ein Rollback auf die vorherigen Überarbeitungen durchführen, falls mit dem neuen Release etwas passiert.

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

from tracing import CloudTraceLoggingSpanExporter
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider, export

...

provider = TracerProvider()
processor = export.BatchSpanProcessor(CloudTraceLoggingSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

...

Hier initialisieren wir den Tracer und den Exporter. Die Details des Exporteurs können in tracing.py eingesehen werden . Hier erstellen wir einen benutzerdefinierten Exporter, da die Menge an Tracedaten, die in Cloud Trace exportiert werden können, begrenzt ist. Wir verwenden eine Implementierung von https://googlecloudplatform.github.io/agent-starter-pack/guide/observability.html für diese Tracing-Funktion.

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 wie unten dargestellt prüfen.

So haben wir jetzt eine gute Beobachtbarkeit und Informationen zu jeder Interaktion unseres Agenten mit dem Nutzer, um Probleme zu beheben. Probieren Sie 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:

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