Esegui il deployment, la gestione e l'osservazione di ADK Agent su Cloud Run

1. Introduzione

NOTE IMPORTANTI:

Questo tutorial richiede un progetto Google Cloud con un account di fatturazione attivo. Se non ne hai ancora uno, segui i passaggi riportati di seguito per ottenere un account di fatturazione di prova che può essere utilizzato per questo tutorial:

1. Apri finestra di navigazione in incognito
2. Vai a questo portale di utilizzo dell'account di fatturazione di prova.
3. Accedi utilizzando il tuo account Gmail personale ( le email di Google Workspace o di altri servizi non funzionano). )
4. Segui le istruzioni passo passo

Questo tutorial ti guiderà nel deployment, nella gestione e nel monitoraggio di un potente agente creato con l'Agent Development Kit (ADK) su Google Cloud Run. L'ADK ti consente di creare agenti in grado di gestire workflow complessi e multi-agente. Sfruttando Cloud Run, una piattaforma serverless completamente gestita, puoi eseguire il deployment del tuo agente come applicazione containerizzata scalabile senza preoccuparti dell'infrastruttura sottostante. Questa potente combinazione ti consente di concentrarti sulla logica di base del tuo agente, sfruttando al contempo l'ambiente solido e scalabile di Google Cloud.

In questo tutorial esploreremo l'integrazione perfetta dell'ADK con Cloud Run. Scoprirai come eseguire il deployment dell'agente e poi approfondirai gli aspetti pratici della gestione dell'applicazione in un ambiente simile a quello di produzione. Vedremo come implementare in modo sicuro nuove versioni dell'agente gestendo il traffico, in modo da poter testare nuove funzionalità con un sottoinsieme di utenti prima di un rilascio completo.

Inoltre, acquisirai esperienza pratica con il monitoraggio delle prestazioni del tuo agente. Simuleremo uno scenario reale eseguendo un test di carico per osservare le funzionalità di scalabilità automatica di Cloud Run in azione. Per ottenere informazioni più approfondite sul comportamento e sul rendimento del tuo agente, attiveremo la tracciabilità con Cloud Trace. In questo modo, avrai una visione end-to-end dettagliata delle richieste mentre attraversano l'agente, il che ti consentirà di identificare e risolvere eventuali colli di bottiglia delle prestazioni. Al termine di questo tutorial, avrai una comprensione completa di come eseguire il deployment, gestire e monitorare in modo efficace gli agenti basati sull'ADK su Cloud Run.

Nel codelab, seguirai un approccio passo passo come segue:

1. Crea un database PostgreSQL su Cloud SQL da utilizzare per il servizio di sessione del database dell'agente ADK
2. Configurare un agente ADK di base
3. Configura il servizio di sessione del database da utilizzare con ADK Runner
4. Esegui il deployment iniziale dell'agente in Cloud Run
5. Test di carico e ispezione della scalabilità automatica di Cloud Run
6. Esegui il deployment della nuova revisione dell'agente e aumenta gradualmente il traffico verso le nuove revisioni
7. Configura Cloud Trace e ispeziona la traccia di esecuzione dell'agente

Panoramica dell'architettura

Prerequisiti

• Avere familiarità con Python
• Conoscenza dell'architettura full-stack di base che utilizza il servizio HTTP

Cosa imparerai a fare

• Struttura dell'ADK e utilità locali
• Configura l'agente ADK con il servizio di sessione del database
• Configura PostgreSQL in Cloud SQL da utilizzare con il servizio di sessione del database
• Esegui il deployment dell'applicazione in Cloud Run utilizzando Dockerfile e configura le variabili di ambiente iniziali
• Configurare e testare la scalabilità automatica di Cloud Run con il test di carico
• Strategia di rilascio graduale con Cloud Run
• Configura la tracciabilità dell'agente ADK in Cloud Trace

Che cosa ti serve

• Browser web Chrome
• Un account Gmail
• Un progetto cloud con fatturazione abilitata

Questo codelab, progettato per sviluppatori di tutti i livelli (inclusi i principianti), utilizza Python nella sua applicazione di esempio. Tuttavia, la conoscenza di Python non è necessaria per comprendere i concetti presentati.

2. Prima di iniziare

Seleziona il progetto attivo in Cloud Console

Questo codelab presuppone che tu disponga già di un progetto Google Cloud con la fatturazione abilitata. Se non l'hai ancora fatto, puoi seguire le istruzioni riportate di seguito per iniziare.

1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.

Prepara il database Cloud SQL

Avremo bisogno di un database da utilizzare in un secondo momento dall'agente ADK. Creiamo un database PostgreSQL su Cloud SQL. Innanzitutto, vai alla barra di ricerca nella sezione superiore della console Cloud e digita "cloud sql". Quindi, fai clic sul prodotto Cloud SQL.

Dopodiché, dobbiamo creare una nuova istanza del database, fare clic su Crea istanza e scegliere PostgreSQL.

Potresti anche dover abilitare l'API Compute Engine se inizi con un nuovo progetto. Fai clic su Abilita API se viene visualizzato questo prompt.

Successivamente, sceglieremo le specifiche del database, selezioneremo la versione Enterprise con il preset della versione Sandbox.

Dopodiché, imposta il nome dell'istanza e la password predefinita per l'utente postgres qui. Puoi configurarlo con le credenziali che preferisci, ma per questo tutorial utilizzeremo "adk-deployment" sia per il nome dell'istanza sia per la password.

Importante: Nome utente e password sono dati sensibili, assicurati di mantenerli segreti.

Utilizziamo us-central1 con una singola zona per questo tutorial. Possiamo finalizzare la creazione del database e lasciare che completi tutta la configurazione richiesta facendo clic sul pulsante Crea istanza.

Abbi pazienza,la creazione del database richiederà circa 5-10 minuti.

Mentre attendiamo il completamento dell'operazione, possiamo continuare con la sezione successiva.

Configura il progetto cloud nel terminale Cloud Shell

1. Utilizzerai Cloud Shell, un ambiente a riga di comando in esecuzione in Google Cloud. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.

2. Una volta eseguita la connessione a Cloud Shell, verifica di essere già autenticato e che il progetto sia impostato sul tuo ID progetto utilizzando il seguente comando:

gcloud auth list

3. Esegui questo comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto.

gcloud config list project

4. Se il progetto non è impostato, utilizza il seguente comando per impostarlo:

gcloud config set project <YOUR_PROJECT_ID>

In alternativa, puoi anche visualizzare l'ID PROJECT_ID nella console.

Fai clic e vedrai tutti i tuoi progetti e l'ID progetto sul lato destro.

5. Abilita le API richieste tramite il comando mostrato di seguito. L'operazione potrebbe richiedere alcuni minuti.

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

Se il comando viene eseguito correttamente, dovresti visualizzare un messaggio simile a quello mostrato di seguito:

Operation "operations/..." finished successfully.

L'alternativa al comando gcloud è tramite la console, cercando ogni prodotto o utilizzando questo link.

Se manca un'API, puoi sempre abilitarla durante l'implementazione.

Consulta la documentazione per i comandi e l'utilizzo di gcloud.

Vai all'editor di Cloud Shell e configura la directory di lavoro dell'applicazione

Ora possiamo configurare l'editor di codice per svolgere alcune attività di programmazione. Per questo utilizzeremo l'editor di Cloud Shell

1. Fai clic sul pulsante Apri editor per aprire un editor di Cloud Shell in cui puoi scrivere il codice
2. Assicurati che il progetto Cloud Code sia impostato nell'angolo in basso a sinistra (barra di stato) dell'editor di Cloud Shell, come evidenziato nell'immagine seguente, e che sia impostato sul progetto Google Cloud attivo in cui hai attivato la fatturazione. Autorizza, se richiesto. Se hai già seguito il comando precedente, il pulsante potrebbe anche puntare direttamente al progetto attivato anziché al pulsante di accesso.

Sii paziente. Potrebbe essere necessario un po' di tempo dopo l'inizializzazione di Cloud Shell Editor prima che venga visualizzato il pulsante Cloud Code - Sign In.

3. Successivamente, cloniamo la directory di lavoro del modello per questo codelab da GitHub eseguendo il seguente comando. Verrà creata la directory di lavoro nella directory deploy_and_manage_adk

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

4. Dopodiché, vai alla sezione superiore dell'editor di Cloud Shell e fai clic su File->Apri cartella, individua la directory username e la directory deploy_and_manage_adk, poi fai clic sul pulsante OK. In questo modo, la directory scelta diventerà la directory di lavoro principale. In questo esempio, il nome utente è alvinprayuda, quindi il percorso della directory è mostrato di seguito

Ora, Cloud Shell Editor dovrebbe avere il seguente aspetto

Ora possiamo configurare l'ambiente Python.

Configurazione dell'ambiente

Prepara l'ambiente virtuale Python

Il passaggio successivo consiste nel preparare l'ambiente di sviluppo. La directory di lavoro del terminale attivo corrente deve trovarsi all'interno della directory di lavoro deploy_and_manage_adk. In questo codelab utilizzeremo Python 3.12 e uv python project manager per semplificare la necessità di creare e gestire la versione di Python e l'ambiente virtuale.

1. Se non hai ancora aperto il terminale, aprilo facendo clic su Terminale -> Nuovo terminale o utilizza Ctrl + Maiusc + C, che aprirà una finestra del terminale nella parte inferiore del browser.

2. Scarica uv e installa Python 3.12 con il seguente comando

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

3. Ora inizializziamo l'ambiente virtuale utilizzando uv. Esegui questo comando

uv sync --frozen

Verranno create la directory .venv e installate le dipendenze. Una rapida occhiata al file pyproject.toml ti fornirà informazioni sulle dipendenze visualizzate in questo modo

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

Nota: le dipendenze Python sono dichiarate all'interno di pyproject.toml e la versione è bloccata all'interno del file uv.lock.

4. Per testare l'ambiente virtuale, crea un nuovo file main.py e copia il seguente codice

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

if __name__ == "__main__":
   main()

5. Quindi, esegui questo comando:

uv run main.py

Otterrai un output simile a quello mostrato di seguito

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

Ciò dimostra che il progetto Python è in fase di configurazione corretta.

Nota:non è stato necessario creare manualmente un ambiente virtuale o attivarlo perché uv gestisce già tutto. Da questo punto in poi, il comando Python standard (ad es. python main.py) verrà sostituito con uv run (ad es. uv run main.py).

File di configurazione dell'installazione

Ora dobbiamo configurare i file di configurazione per questo progetto.

Rinomina il file .env.example in .env e verrà visualizzato il valore riportato di seguito. Aggiorna il valore GOOGLE_CLOUD_PROJECT con il tuo project-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

Nota importante:aggiorna i valori di GOOGLE_CLOUD_PROJECT con il tuo ID progetto

Per questo codelab, utilizzeremo i valori preconfigurati per GOOGLE_CLOUD_LOCATION e GOOGLE_GENAI_USE_VERTEXAI.. Per ora, manterremo SESSION_SERVICE_URI commentato.

Ora possiamo passare al passaggio successivo, esaminare la logica dell'agente e implementarla.

3. Crea l'agente meteo con ADK e Gemini 2.5

Introduzione alla struttura delle directory ADK

Iniziamo esplorando cosa offre l'ADK e come creare l'agente. La documentazione completa dell'ADK è disponibile in questo URL . L'ADK ci offre molte utilità nell'esecuzione dei comandi della CLI. Alcuni di questi sono :

• Configura la struttura delle directory dell'agente
• Prova rapidamente l'interazione tramite l'input e l'output della CLI
• Configura rapidamente l'interfaccia web dell'interfaccia utente di sviluppo locale

Ora controlliamo la struttura dell'agente nella directory weather_agent

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

Se ispezioni i file init.py e agent.py, vedrai questo codice

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

Nota:la struttura delle directory, l'importazione dell'agente all'interno di init.py e la dichiarazione root_agent in agent.py sono la struttura obbligatoria per essere riconosciuta dalla CLI ADK.

ADK Spiegazione del codice

Questo script contiene l'inizializzazione dell'agente, in cui inizializziamo quanto segue:

• Imposta il modello da utilizzare su gemini-2.5-flash
• Fornisci lo strumento get_weather per supportare la funzionalità dell'agente come agente meteo

Esegui la UI web

Ora possiamo interagire con l'agente e ispezionare il suo comportamento a livello locale. L'ADK ci consente di avere un'interfaccia utente web di sviluppo per interagire e ispezionare ciò che accade durante l'interazione. Esegui questo comando per avviare il server dell'interfaccia utente di sviluppo locale

uv run adk web --port 8080

Verrà generato un output simile al seguente esempio, il che significa che possiamo già accedere all'interfaccia web

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)

Ora, per verificarlo, fai clic sul pulsante Anteprima web nella parte superiore di Cloud Shell Editor e seleziona Anteprima sulla porta 8080.

Visualizzerai la seguente pagina web in cui potrai selezionare gli agenti disponibili nel pulsante a discesa in alto a sinistra ( nel nostro caso dovrebbe essere weather_agent) e interagire con il bot. Nella finestra a sinistra vedrai molte informazioni sui dettagli del log durante il runtime dell'agente.

Ora prova a interagire con l'app. Nella barra a sinistra, possiamo esaminare la traccia di ogni input, in modo da capire quanto tempo impiega ogni azione intrapresa dall'agente prima di formare la risposta finale.

Questa è una delle funzionalità di osservabilità integrate nell'ADK, che al momento ispezioniamo localmente. Più avanti vedremo come viene integrato in Cloud Trace, in modo da avere una traccia centralizzata di tutte le richieste

Promemoria Per ora interrompiamo il processo adk web. Puoi premere Ctrl+C per interromperlo.

4. Lo script del server di backend

Per rendere l'agente accessibile come servizio, lo inseriremo in un'app FastAPI. Qui possiamo configurare i servizi necessari per supportare l'agente, ad esempio preparando il servizio Session, Memory o Artifact per la produzione. Ecco il codice di server.py che verrà utilizzato

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)

Spiegazione del codice del server

Questi sono gli elementi definiti nello script server.py:

1. Converti il nostro agente in un'app FastAPI utilizzando il metodo get_fast_api_app. In questo modo erediteremo la stessa definizione di route utilizzata per l'interfaccia utente di sviluppo web.
2. Configura il servizio Session, Memory o Artifact necessario aggiungendo gli argomenti delle parole chiave al metodo get_fast_api_app. In questo tutorial, se configuriamo la variabile di ambiente SESSION_SERVICE_URI, il servizio di sessione la utilizzerà, altrimenti utilizzerà la sessione in memoria
3. Possiamo aggiungere una route personalizzata per supportare altre logiche di business di backend. Nello script aggiungiamo un esempio di route della funzionalità di feedback.
4. Abilita il tracciamento cloud per inviare la traccia a Google Cloud Trace

5. Deployment in Cloud Run

Ora eseguiamo il deployment di questo servizio agente su Cloud Run. Ai fini di questa demo, questo servizio verrà esposto come servizio pubblico accessibile ad altri. Tuttavia, tieni presente che non si tratta di best practice, in quanto non è sicuro

In questo codelab utilizzeremo Dockerfile per eseguire il deployment del nostro agente su Cloud Run. Di seguito sono riportati i contenuti del Dockerfile che verranno utilizzati

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

A questo punto, abbiamo già tutti i file necessari per eseguire il deployment delle nostre applicazioni in Cloud Run. Eseguiamolo. Vai al terminale Cloud Shell e assicurati che il progetto attuale sia configurato sul tuo progetto attivo. In caso contrario, devi utilizzare il comando gcloud configure per impostare l'ID progetto:

gcloud config set project [PROJECT_ID]

Quindi, esegui questo comando per eseguirne il deployment in Cloud Run.

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

Nota importante:aggiorna i valori di YOUR_DB_CONNECTION_NAME, YOUR_DEFAULT_USER_PASS e YOUR_PROJECT_ID qui.

Tieni presente inoltre che qui forniamo SESSION_SERVICE_URI come variabili di ambiente ai fini del tutorial. Questa operazione non è consigliata perché esporrà il nome utente e la password del database. Prova a utilizzare un secret per casi come questo

Per ottenere il valore di {YOUR_DB_CONNECTION_NAME}, puoi tornare a Cloud SQL e fare clic sull'istanza che hai creato. All'interno della pagina dell'istanza, scorri verso il basso fino alla sezione "Connetti a questa istanza" e puoi copiare il nome della connessione per sostituire il valore {YOUR_DB_CONNECTION_NAME}. Ad esempio, guarda l'immagine mostrata di seguito.

Nota:quando viene configurato SESSION_SERVICE_URI, il nostro agente ADK utilizzerà l'URI per il servizio per archiviare le informazioni e lo stato della sessione. In questo tutorial utilizziamo la connessione socket Unix PostgreSQL con il driver pg8000.

Nell'esempio viene utilizzato l'utente predefinito postgres e il database predefinito postgres. Se utilizzi gli stessi valori del tutorial, SESSION_SERVICE_URI dovrebbe essere simile a questo:

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

Pertanto, devi sostituire solo l'ID progetto qui

Se ti viene chiesto di confermare la creazione di un registro degli artefatti per il repository Docker, rispondi Y. Tieni presente che qui consentiamo l'accesso non autenticato perché si tratta di un'applicazione demo. Ti consigliamo di utilizzare l'autenticazione appropriata per le applicazioni aziendali e di produzione.

Una volta completato il deployment, dovresti ricevere un link simile a quello riportato di seguito:

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

Continua a utilizzare l'applicazione dalla finestra di navigazione in incognito o dal tuo dispositivo mobile. Dovrebbe essere già disponibile.

6. Ispezione della scalabilità automatica di Cloud Run con il test di carico

Ora esamineremo le funzionalità di scalabilità automatica di Cloud Run. Per questo scenario, eseguiamo il deployment di una nuova revisione abilitando il numero massimo di concorrenze per istanza. Esegui questo comando

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

Nota importante: aggiorna i valori di YOUR_PROJECT_ID qui.

Dopodiché, esaminiamo il file load_test.py. Questo sarà lo script che utilizzeremo per eseguire il test di carico utilizzando il framework locust. Questo script eseguirà le seguenti operazioni :

1. user_id e session_id randomizzati
2. Crea session_id per user_id
3. Colpisci l'endpoint "/run_sse" con user_id e session_id creati

Se non l'hai fatto, dovrai comunicarci l'URL del servizio di cui è stato eseguito il deployment. Vai alla console Cloud Run e fai clic sul servizio weather-agent.

Quindi, trova il servizio weather-agent e fai clic.

L'URL del servizio verrà visualizzato accanto alle informazioni sulla regione. Ad es.

Quindi esegui questo comando per eseguire il test di carico

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

Nota importante:aggiorna i valori di YOUR_SERVICE_URL qui.

Nota:verrà simulato l'aumento graduale delle richieste parallele degli utenti da 0 a 60 con una velocità di 5 utenti al secondo per un periodo di 120 secondi

Se lo esegui, vedrai visualizzate metriche come queste. ( In this example all reqs success )

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  

Vediamo cosa è successo in Cloud Run. Vai di nuovo al servizio di cui hai eseguito il deployment e visualizza la dashboard. In questo modo, vedrai come Cloud Run scala automaticamente l'istanza per gestire le richieste in entrata. Poiché limitiamo la concorrenza massima a 10 per istanza, l'istanza Cloud Run tenterà di regolare automaticamente il numero di container per soddisfare questa condizione.

Nota:puoi controllare non solo la concorrenza massima, ma anche le istanze di container minime e massime. Per informazioni dettagliate, consulta la documentazione dell'SDK.

7. Rilasciare gradualmente le nuove revisioni

Ora, consideriamo lo scenario seguente. Vogliamo aggiornare il prompt dell'agente con il seguente testo :

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

Poi, vuoi rilasciare nuove revisioni, ma non vuoi che tutto il traffico delle richieste vada direttamente alla nuova versione. Possiamo eseguire il rilascio graduale con Cloud Run. Innanzitutto, dobbiamo eseguire il deployment di una nuova revisione, ma con il flag –no-traffic. Salva lo script dell'agente precedente ed esegui questo comando

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

Nota importante: aggiorna i valori di YOUR_PROJECT_ID qui

Al termine, riceverai un log simile a quello della procedura di deployment precedente, con la differenza del numero di traffico servito. Verrà visualizzato lo 0% del traffico servito.

A questo punto, vai alla pagina di prodotto Cloud Run e trova l'istanza di cui è stato eseguito il deployment. Digita cloud run nella barra di ricerca e fai clic sul prodotto Cloud Run.

Quindi, trova il servizio weather-agent e fai clic.

Vai alla scheda Revisioni e vedrai l'elenco delle revisioni implementate.

Vedrai che le nuove revisioni implementate vengono pubblicate al 0%. Da qui puoi fare clic sul pulsante con tre puntini (⋮) e scegliere Gestisci traffico.

Nella nuova finestra popup, puoi modificare la percentuale di traffico indirizzato alle revisioni.

Dopo un po' di tempo, il traffico verrà indirizzato proporzionalmente in base alle configurazioni delle percentuali. In questo modo, possiamo facilmente eseguire il rollback alle revisioni precedenti se si verifica un problema con la nuova release.

8. Tracciamento ADK

Gli agenti creati con ADK supportano già la tracciabilità utilizzando l'incorporamento di OpenTelemetry. Abbiamo Cloud Trace per acquisire le tracce e visualizzarle. Esaminiamo il file server.py per capire come abilitarlo nel servizio di cui è stato eseguito il deployment in precedenza

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

...

Qui inizializziamo il tracer e l'esportatore. I dettagli dell'esportatore possono essere esaminati in tracing.py . Qui creiamo un esportatore personalizzato perché esiste un limite ai dati di traccia che possono essere esportati in Cloud Trace. Per questa funzionalità di tracciamento, utilizziamo un'implementazione di https://googlecloudplatform.github.io/agent-starter-pack/guide/observability.html.

Prova ad accedere alla UI di sviluppo web del servizio e a chattare con l'agente. Dopodiché, vai alla barra di ricerca della console Google Cloud, digita "Esplora tracce" e scegli il prodotto Esplora tracce.

Nella pagina dell'esploratore di tracce, vedrai che la nostra conversazione con la traccia dell'agente è stata inviata. Puoi visualizzarlo nella sezione Nome span e filtrare lo span specifico del nostro agente ( denominato agent_run [weather_agent]).

Quando gli intervalli sono già filtrati, puoi anche esaminare direttamente ogni traccia. Mostrerà la durata dettagliata di ogni azione intrapresa dall'agente. Ad esempio, guarda le immagini qui sotto

In ogni sezione, puoi esaminare i dettagli negli attributi come mostrato di seguito.

Ecco fatto. Ora abbiamo una buona osservabilità e informazioni su ogni interazione del nostro agente con l'utente per aiutarci a eseguire il debug dei problemi. Non esitare a provare vari strumenti o flussi di lavoro.

9. La sfida

Prova i workflow multi-agente o basati su agenti per vedere come funzionano sotto carico e come appare la traccia

10. Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo codelab, segui questi passaggi:

1. Nella console Google Cloud, vai alla pagina Gestisci risorse.
2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
3. Nella finestra di dialogo, digita l'ID progetto, quindi fai clic su Chiudi per eliminare il progetto.
4. In alternativa, puoi andare a Cloud Run nella console, selezionare il servizio di cui hai appena eseguito il deployment ed eliminarlo.