Ta strona została przetłumaczona przez Cloud Translation API.

Wdrażanie, zarządzanie i monitorowanie usługi ADK Agent w Cloud Run

1. Wprowadzenie

Z tego samouczka dowiesz się, jak wdrażać, zarządzać i monitorować zaawansowanego agenta utworzonego za pomocą zestawu Agent Development Kit (ADK) w Google Cloud Run. ADK umożliwia tworzenie agentów zdolnych do wykonywania złożonych przepływów pracy z udziałem wielu agentów. Korzystając z Cloud Run, w pełni zarządzanej platformy bezserwerowej, możesz wdrożyć agenta jako skalowalną aplikację skonteneryzowaną bez konieczności przejmowania się infrastrukturą bazową. To połączenie umożliwia skupienie się na podstawowej logice agenta przy jednoczesnym korzystaniu z solidnego i skalowalnego środowiska Google Cloud.

W tym samouczku omówimy bezproblemową integrację ADK z Cloud Run. Dowiesz się, jak wdrożyć agenta, a potem poznasz praktyczne aspekty zarządzania aplikacją w środowisku produkcyjnym. Omówimy, jak bezpiecznie wdrażać nowe wersje agenta, zarządzając ruchem i umożliwiając testowanie nowych funkcji na podzbiorze użytkowników przed pełnym udostępnieniem.

Dodatkowo zdobędziesz praktyczne doświadczenie w monitorowaniu skuteczności agenta. Przeprowadzimy test obciążenia, aby zasymulować rzeczywistą sytuację i zaobserwować działanie funkcji automatycznego skalowania Cloud Run. Aby uzyskać bardziej szczegółowe informacje o zachowaniu i skuteczności agenta, włączymy śledzenie za pomocą Cloud Trace. Dzięki temu uzyskasz szczegółowy, kompleksowy wgląd w żądania podczas ich przesyłania przez agenta, co pozwoli Ci identyfikować i usuwać wszelkie wąskie gardła wydajności. Po ukończeniu tego samouczka będziesz mieć pełną wiedzę o tym, jak skutecznie wdrażać agentów opartych na ADK w Cloud Run, zarządzać nimi i je monitorować.

W ramach ćwiczeń z programowania będziesz wykonywać kolejne czynności:

Utwórz bazę danych PostgreSQL w Cloud SQL, która będzie używana w usłudze sesji bazy danych agenta ADK.
Konfigurowanie podstawowego agenta ADK
Konfigurowanie usługi sesji bazy danych do używania przez narzędzie ADK Runner
Początkowe wdrożenie agenta w Cloud Run
Testowanie obciążenia i sprawdzanie autoskalowania Cloud Run
Wdrażanie nowej wersji agenta i stopniowe zwiększanie ruchu kierowanego do nowych wersji
Konfigurowanie śledzenia w chmurze i sprawdzanie śledzenia działania agenta

Omówienie architektury

Wymagania wstępne

wygodna praca z Pythonem,
Znajomość podstawowej architektury pełnego stosu z użyciem usługi HTTP

Czego się nauczysz

Struktura ADK i lokalne narzędzia
Konfigurowanie agenta ADK za pomocą usługi sesji bazy danych
Konfigurowanie PostgreSQL w CloudSQL na potrzeby usługi sesji bazy danych
Wdrażanie aplikacji w Cloud Run przy użyciu pliku Dockerfile i konfigurowanie początkowych zmiennych środowiskowych
Konfigurowanie i testowanie autoskalowania Cloud Run za pomocą testów obciążeniowych
Strategia stopniowego wdrażania w Cloud Run
Konfigurowanie śledzenia agenta ADK w Cloud Trace

Czego potrzebujesz

przeglądarki Chrome,
konto Gmail,
Projekt w chmurze z włączonymi płatnościami

Ten przewodnik, przeznaczony dla deweloperów na wszystkich poziomach zaawansowania (w tym dla początkujących), wykorzystuje w przykładowej aplikacji język Python. Znajomość Pythona nie jest jednak wymagana do zrozumienia przedstawionych koncepcji.

2. 🚀 Przygotowywanie konfiguracji programistycznej warsztatów

Krok 1. Wybierz aktywny projekt w Cloud Console

W konsoli Google Cloud na stronie selektora projektów wybierz lub utwórz projekt Google Cloud (patrz lewa górna sekcja konsoli).

Kliknij go, a zobaczysz listę wszystkich projektów, jak w tym przykładzie:

Wartość wskazana przez czerwone pole to IDENTYFIKATOR PROJEKTU. Będzie ona używana w całym samouczku.

Sprawdź, czy w projekcie Cloud włączone są płatności. Aby to sprawdzić, kliknij ikonę menu ☰ na pasku w lewym górnym rogu, aby wyświetlić menu nawigacyjne, a następnie znajdź menu Płatności.

Jeśli pod tytułem „Konto rozliczeniowe wersji próbnej Google Cloud Platform” w sekcji Płatności / Podsumowanie ( w lewym górnym rogu konsoli Google Cloud ) widzisz „Konto rozliczeniowe wersji próbnej Google Cloud Platform”, Twój projekt jest gotowy do użycia w tym samouczku. Jeśli nie, wróć na początek tego samouczka i skorzystaj z konta rozliczeniowego w wersji próbnej.

Krok 2. Przygotuj bazę danych Cloud SQL

Później agent ADK będzie korzystać z bazy danych. Utwórzmy bazę danych PostgreSQL w Cloud SQL. Najpierw otwórz pasek wyszukiwania w górnej części konsoli Cloud i wpisz „cloud sql”. Następnie kliknij usługę Cloud SQL.

Następnie musimy utworzyć nową instancję bazy danych. Kliknij Utwórz instancję i wybierz PostgreSQL.

Jeśli zaczynasz od nowego projektu, może być też konieczne włączenie interfejsu Compute Engine API. W tym celu kliknij Włącz interfejs API, gdy pojawi się odpowiedni komunikat.

Następnie wybierzemy specyfikacje bazy danych, wybierając wersję Enterprise z gotowym ustawieniem Tryb piaskownicy.

Następnie ustaw nazwę instancji i hasło domyślne użytkownika postgres. Możesz skonfigurować to za pomocą dowolnych danych logowania, ale na potrzeby tego samouczka użyjemy nazwy instancji „adk-deployment” i hasła „ADK-deployment123”.

W tym samouczku użyjemy regionu us-central1 z jedną strefą. Możemy wtedy dokończyć tworzenie bazy danych i pozwolić jej na ukończenie wszystkich wymaganych ustawień, klikając przycisk Utwórz instancję.

Podczas oczekiwania na zakończenie tego procesu możemy przejść do następnej sekcji.

Krok 3. Zapoznaj się z Cloud Shell

W większości samouczków będziesz używać Cloud Shell. Kliknij Aktywuj Cloud Shell u góry konsoli Google Cloud. Jeśli pojawi się prośba o autoryzację, kliknij Autoryzuj.

Po połączeniu z Cloud Shell musimy sprawdzić, czy powłoka ( lub terminal) jest już uwierzytelniona na naszym koncie.

gcloud auth list

Jeśli widzisz swój osobisty adres Gmail, jak w przykładzie poniżej, wszystko jest w porządku.

Credentialed Accounts

ACTIVE: *
ACCOUNT: alvinprayuda@gmail.com

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

Jeśli nie, spróbuj odświeżyć przeglądarkę i kliknąć Autoryzuj, gdy pojawi się odpowiedni komunikat ( może to zostać przerwane z powodu problemu z połączeniem).

Następnie musimy sprawdzić, czy powłoka jest już skonfigurowana z prawidłowym IDENTYFIKATOREM PROJEKTU. Jeśli w terminalu przed ikoną $ widzisz wartość w nawiasach ( ) ( na zrzucie ekranu poniżej wartość to "adk-cloudrun-deployment-476504"), oznacza to, że w aktywnej sesji powłoki skonfigurowany jest projekt.

Jeśli wyświetlana wartość jest już prawidłowa, możesz pominąć następne polecenie. Jeśli jednak jest nieprawidłowy lub go brakuje, uruchom to polecenie:

gcloud config set project <YOUR_PROJECT_ID>

Następnie skopiuj katalog roboczy szablonu na potrzeby tego laboratorium z GitHuba, wykonując to polecenie: W katalogu deploy_and_manage_adk zostanie utworzony katalog roboczy.

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

Krok 4. Zapoznaj się z edytorem Cloud Shell i skonfiguruj katalog roboczy aplikacji

Teraz możemy skonfigurować edytor kodu, aby wykonywać różne czynności związane z kodowaniem. W tym celu użyjemy edytora Cloud Shell.

Kliknij przycisk Otwórz edytor. Spowoduje to otwarcie edytora Cloud Shell .

Następnie przejdź do górnej sekcji edytora Cloud Shell i kliknij File->Open Folder (Plik –>Otwórz folder), znajdź katalog username (nazwa użytkownika) i katalog deploy_and_manage_adk,a potem kliknij OK. Spowoduje to ustawienie wybranego katalogu jako głównego katalogu roboczego. W tym przykładzie nazwa użytkownika to alvinprayuda, więc ścieżka do katalogu jest widoczna poniżej.

Twój katalog roboczy edytora Cloud Shell powinien teraz wyglądać tak ( w katalogu deploy_and_manage_adk):

Teraz otwórz terminal edytora. Możesz to zrobić, klikając na pasku menu Terminal -> Nowy terminal lub używając skrótu Ctrl + Shift + C. W dolnej części przeglądarki otworzy się okno terminala.

Aktywny terminal powinien znajdować się w katalogu roboczym deploy_and_manage_adk. W tym samouczku użyjemy Pythona 3.12 i menedżera projektów Pythona uv, aby uprościć tworzenie wersji Pythona i środowiska wirtualnego oraz zarządzanie nimi. Pakiet uv jest już wstępnie zainstalowany w Cloud Shell.

Uruchom to polecenie, aby zainstalować wymagane zależności w środowisku wirtualnym w katalogu .venv.

uv sync --frozen

Teraz musimy włączyć wymagane interfejsy API za pomocą polecenia pokazanego poniżej. To może chwilę potrwać.

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

Po pomyślnym wykonaniu polecenia powinien wyświetlić się komunikat podobny do tego poniżej:

Operation "operations/..." finished successfully.

Następnie musimy skonfigurować pliki konfiguracyjne dla tego projektu.

Zmień nazwę pliku .env.example na .env.

cp .env.example .env

Otwórz plik .env i zmień wartość GOOGLE_CLOUD_PROJECT na identyfikator projektu.

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

Na potrzeby tego laboratorium wybierzemy wstępnie skonfigurowane wartości dla GOOGLE_CLOUD_LOCATION i GOOGLE_GENAI_USE_VERTEXAI.. Na razie pozostawimy DB_CONNECTION_NAME jako komentarz.

Teraz możemy przejść do następnego kroku, czyli sprawdzić logikę agenta i wdrożyć go.

3. 🚀 Tworzenie agenta pogodowego za pomocą ADK i Gemini 2.5

Wprowadzenie do struktury katalogów ADK

Zacznijmy od poznania możliwości ADK i sposobu tworzenia agenta. Pełną dokumentację pakietu ADK znajdziesz pod tym adresem URL . ADK oferuje wiele narzędzi w ramach wykonywania poleceń CLI. Oto niektóre z nich :

Konfigurowanie struktury katalogów agenta
Szybkie wypróbowanie interakcji za pomocą danych wejściowych i wyjściowych interfejsu wiersza poleceń
Szybkie konfigurowanie lokalnego interfejsu internetowego

Sprawdźmy teraz strukturę agenta w katalogu weather_agent.

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

Jeśli sprawdzisz pliki init.py i agent.py, zobaczysz ten kod:

# __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 Wyjaśnienie kodu

Ten skrypt zawiera inicjację agenta, w której inicjujemy te elementy:

Ustaw model, który ma być używany, na gemini-2.5-flash
Udostępnij narzędzie get_weather, aby obsługiwać funkcje agenta, np. agenta pogodowego.

Uruchamianie interfejsu internetowego

Teraz możemy wchodzić w interakcje z agentem i sprawdzać jego działanie lokalnie. ADK umożliwia nam korzystanie z interfejsu internetowego do programowania, który pozwala wchodzić w interakcje i sprawdzać, co się dzieje podczas interakcji. Aby uruchomić lokalny serwer interfejsu programistycznego, wykonaj to polecenie:

uv run adk web --port 8080

Pojawią się dane wyjściowe podobne do tych poniżej. Oznacza to, że możemy już uzyskać dostęp do interfejsu internetowego.

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)

Aby to sprawdzić, kliknij przycisk Podgląd w przeglądarce w górnej części edytora Cloud Shell i wybierz Podejrzyj na porcie 8080.

Wyświetli się strona internetowa, na której w lewym górnym rogu możesz wybrać dostępnych agentów ( w naszym przypadku powinien to być weather_agent) i interagować z botem. W oknie po lewej stronie zobaczysz wiele informacji o szczegółach logu podczas działania agenta.

Teraz spróbuj wejść z nim w interakcję. Na pasku po lewej stronie możemy sprawdzić ślad każdego wejścia, aby dowiedzieć się, ile czasu zajmuje każda czynność wykonywana przez agenta przed sformułowaniem ostatecznej odpowiedzi.

Jest to jedna z funkcji obserwacji wbudowanych w ADK. Obecnie sprawdzamy ją lokalnie. Później zobaczymy, jak jest to zintegrowane z Cloud Tracing, abyśmy mieli scentralizowane śledzenie wszystkich żądań.

4. 🚀 Wdrażanie w Cloud Run

Teraz wdróżmy tę usługę agenta w Cloud Run. Na potrzeby tej wersji demonstracyjnej usługa będzie udostępniana jako usługa publiczna, do której dostęp będą miały inne osoby. Pamiętaj jednak, że nie jest to sprawdzona metoda, ponieważ nie zapewnia bezpieczeństwa.

W tym samouczku użyjemy pliku Dockerfile, aby wdrożyć agenta w Cloud Run. Na tym etapie mamy już wszystkie potrzebne pliki ( Dockerfile i server.py), aby wdrożyć aplikacje w Cloud Run. Omówimy to szczegółowo w dalszej części.

Teraz wdróżmy najpierw usługę. Otwórz terminal Cloud Shell i sprawdź, czy bieżący projekt jest skonfigurowany jako aktywny. Jeśli nie, użyj polecenia gcloud configure, aby ustawić identyfikator projektu:

gcloud config set project [PROJECT_ID]

Teraz musimy ponownie otworzyć plik .env i usunąć komentarz przy zmiennej DB_CONNECTION_NAME oraz wypełnić ją prawidłową wartością.

# 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

Aby uzyskać wartość DB_CONNECTION_NAME, możesz ponownie otworzyć Cloud SQL i kliknąć utworzoną instancję. Otwórz pasek wyszukiwania w górnej części konsoli Cloud i wpisz „cloud sql”. Następnie kliknij usługę Cloud SQL.

Następnie zobaczysz utworzoną wcześniej instancję. Kliknij ją.

Na stronie instancji przewiń w dół do sekcji „Połącz się z tą instancją” i skopiuj Nazwę połączenia, aby zastąpić wartość DB_CONNECTION_NAME.

Następnie otwórz plik .env i zmodyfikuj zmienną DB_CONNECTION_NAME. Plik env powinien wyglądać podobnie do przykładu poniżej.

# 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

Następnie uruchom skrypt wdrażania.

bash deploy_to_cloudrun.sh

Jeśli pojawi się prośba o potwierdzenie utworzenia repozytorium Artifact Registry dla Dockera, wpisz Y.

Podczas oczekiwania na zakończenie procesu wdrażania przyjrzyjmy się skryptowi deploy_to_cloudrun.sh.

#!/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

Ten skrypt wczyta zmienną .env, a następnie uruchomi polecenie wdrożenia.

Jeśli przyjrzysz się bliżej, zobaczysz, że do wykonania wszystkich czynności niezbędnych do wdrożenia usługi wystarczy jedno polecenie gcloud run deploy: utworzenie obrazu, przesłanie go do rejestru, wdrożenie usługi, ustawienie zasad IAM, utworzenie wersji, a nawet kierowanie ruchem. W tym przykładzie udostępniamy już plik Dockerfile, więc to polecenie zostanie użyte do utworzenia aplikacji.

Po zakończeniu wdrażania powinien pojawić się link podobny do tego poniżej:

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

Po uzyskaniu tego adresu URL możesz używać aplikacji w oknie incognito lub na urządzeniu mobilnym i uzyskać dostęp do interfejsu programisty agenta. Podczas oczekiwania na wdrożenie w następnej sekcji przyjrzymy się szczegółowo usłudze, którą właśnie wdrażamy.

5. 💡 Plik Dockerfile i skrypt serwera backendu

Aby udostępnić agenta jako usługę, umieścimy go w aplikacji FastAPI, która będzie uruchamiana za pomocą polecenia Dockerfile. Poniżej znajduje się zawartość pliku 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"]

Możemy tu skonfigurować niezbędne usługi, które będą obsługiwać agenta, np. przygotować usługi Session, Memory lub Artifact do użytku produkcyjnego. Oto kod pliku server.py, który będzie używany:

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)

Wyjaśnienie kodu serwera

Oto elementy zdefiniowane w skrypcie server.py:

Przekształć agenta w aplikację FastAPI za pomocą metody get_fast_api_app. W ten sposób odziedziczymy tę samą definicję trasy, która jest używana w interfejsie programowania aplikacji internetowych.
Skonfiguruj niezbędną usługę sesji, pamięci lub artefaktów, dodając argumenty słów kluczowych do metody get_fast_api_app. Jeśli w tym samouczku skonfigurujemy zmienną środowiskową SESSION_SERVICE_URI, usługa sesji będzie jej używać. W przeciwnym razie będzie używać sesji w pamięci.
Możemy dodać niestandardową ścieżkę, aby obsługiwać inną logikę biznesową backendu. W skrypcie dodajemy przykładową ścieżkę funkcji opinii.
Włącz śledzenie w chmurze w parametrach argumentu get_fast_api_app, aby wysyłać logi do Cloud Trace.
Uruchamianie usługi FastAPI za pomocą uvicorn

Jeśli wdrożenie zostało już zakończone, spróbuj wejść w interakcję z agentem w interfejsie internetowym dla programistów, otwierając adres URL Cloud Run.

6. 🚀 Sprawdzanie autoskalowania Cloud Run za pomocą testów obciążenia

Teraz sprawdzimy możliwości automatycznego skalowania Cloud Run. W tym scenariuszu wdróżmy nową wersję, włączając maksymalną liczbę równoczesnych żądań na instancję. W poprzedniej sekcji ustawiliśmy maksymalną współbieżność na 10 ( flaga --concurrency 10). Możemy więc oczekiwać, że Cloud Run spróbuje skalować instancję, gdy przeprowadzimy test obciążenia, który przekroczy tę liczbę.

Przyjrzyjmy się plikowi load_test.py. Będzie to skrypt, którego użyjemy do przeprowadzenia testu obciążeniowego za pomocą platformy locust. Ten skrypt wykona te działania :

Losowe wartości user_id i session_id
Utwórz identyfikator sesji dla identyfikatora użytkownika.
Wyślij żądanie do punktu końcowego „/run_sse” z utworzonymi identyfikatorami user_id i session_id.

Jeśli nie podasz adresu URL wdrożonej usługi, będziemy musieli go poznać. Otwórz konsolę Cloud Run i kliknij usługę weather-agent.

Następnie znajdź usługę weather-agent i kliknij ją.

Adres URL usługi będzie wyświetlany obok informacji o regionie. np.

Następnie uruchom to polecenie, aby przeprowadzić test obciążenia:

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

Po uruchomieniu tego polecenia zobaczysz wyświetlone dane, takie jak te poniżej. ( W tym przykładzie wszystkie żądania zakończyły się powodzeniem)

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

Sprawdźmy teraz, co się stało w Cloud Run. Wróć do wdrożonej usługi i wyświetl panel. Pokazuje to, jak Cloud Run automatycznie skaluje instancję w celu obsługi żądań przychodzących. Ograniczamy maksymalną liczbę współbieżnych żądań do 10 na instancję, więc instancja Cloud Run automatycznie dostosuje liczbę kontenerów, aby spełnić ten warunek.

7. 🚀 Stopniowe wdrażanie nowych wersji

Rozważmy teraz ten scenariusz. Chcemy zaktualizować prompt agenta. Otwórz plik weather_agent/agent.py i zastąp go tym kodem:

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

Chcesz wdrożyć nowe wersje, ale nie chcesz, aby cały ruch z żądaniami był kierowany bezpośrednio do nowej wersji. W Cloud Run możemy przeprowadzić stopniowe wdrażanie. Najpierw musimy wdrożyć nową wersję, ale z flagą –no-traffic. Zapisz poprzedni skrypt agenta i uruchom to polecenie:

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

Po zakończeniu otrzymasz podobny dziennik jak w przypadku poprzedniego procesu wdrażania, z tą różnicą, że będzie zawierał liczbę obsłużonych żądań. Wyświetli się informacja o 0% obsłużonego ruchu.

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

Następnie przejdźmy na stronę usługi Cloud Run i znajdźmy wdrożoną instancję. Na pasku wyszukiwania wpisz „Cloud Run” i kliknij usługę Cloud Run.

Następnie znajdź usługę weather-agent i kliknij ją.

Otwórz kartę Wersje, na której zobaczysz listę wdrożonych wersji.

Nowa wdrożona wersja będzie obsługiwać 0% ruchu. Kliknij przycisk z 3 kropkami (⋮) i wybierz Zarządzaj ruchem.

W nowo otwartym okienku możesz edytować odsetek ruchu kierowanego do poszczególnych wersji.

Po pewnym czasie ruch będzie kierowany proporcjonalnie na podstawie konfiguracji procentowych. Dzięki temu w razie problemów z nową wersją możemy łatwo przywrócić poprzednie wersje.

8. 🚀 Śledzenie ADK

Agenty utworzone za pomocą platformy ADK obsługują już śledzenie za pomocą otwartej telemetrii. Mamy Cloud Trace, aby rejestrować ślady i je wizualizować. Przyjrzyjmy się plikowi server.py, aby zobaczyć, jak włączyć tę funkcję w usłudze, którą wcześniej wdrożyliśmy.

# server.py

...

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

...

app: FastAPI = get_fast_api_app(**app_args)

...

W tym przypadku przekazujemy argument trace_to_cloud do funkcji True. Jeśli wdrażasz usługę za pomocą innych opcji, więcej informacji o włączaniu śledzenia w Cloud Trace w przypadku różnych opcji wdrażania znajdziesz w tej dokumentacji.

Spróbuj uzyskać dostęp do interfejsu internetowego usługi i porozmawiać z agentem. Następnie na pasku wyszukiwania w konsoli Google Cloud wpisz „Eksplorator logów czasu” i wybierz usługę Eksplorator logów czasu.

Na stronie eksploratora śladów zobaczysz, że ślad naszej rozmowy z agentem został przesłany. W sekcji Nazwa zakresu możesz zobaczyć zakresy i odfiltrować ten, który jest specyficzny dla naszego agenta ( ma nazwę agent_run [weather_agent]).

Gdy zakresy są już przefiltrowane, możesz też bezpośrednio sprawdzić każdy ślad. Wyświetla szczegółowy czas trwania każdego działania podjętego przez agenta. Na przykład spójrz na obrazy poniżej.

W każdej sekcji możesz sprawdzić szczegóły w atrybutach, jak pokazano poniżej.

Gotowe. Mamy teraz dobrą widoczność i informacje o każdej interakcji agenta z użytkownikiem, które pomogą nam rozwiązywać problemy. Możesz wypróbować różne narzędzia i procesy.

9. 🎯 Wyzwanie

Wypróbuj przepływy pracy z wieloma agentami lub oparte na agentach, aby sprawdzić, jak działają pod obciążeniem i jak wygląda ślad.

10. 🧹 Czyszczenie

Aby uniknąć obciążenia konta Google Cloud opłatami za zasoby użyte w tym laboratorium, wykonaj te czynności:

W konsoli Google Cloud otwórz stronę Zarządzanie zasobami.
Z listy projektów wybierz projekt do usunięcia, a potem kliknij Usuń.
W oknie wpisz identyfikator projektu i kliknij Wyłącz, aby usunąć projekt.
Możesz też otworzyć Cloud Run w konsoli, wybrać wdrożoną usługę i ją usunąć.