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

1. Introduzione

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

5e38fc5607fb4543.jpeg

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
  • Configura e testa 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. 🚀 Preparazione della configurazione di sviluppo del workshop

Passaggio 1: seleziona Progetto attivo nella console Cloud

Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud (vedi la sezione in alto a sinistra della console).

9803a4534597d962.png

Fai clic e vedrai l'elenco di tutti i tuoi progetti, come in questo esempio:

5b60dbeab4f9b524.png

Il valore indicato dal riquadro rosso è l'ID PROGETTO e verrà utilizzato in tutto il tutorial.

Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Per verificarlo, fai clic sull'icona a forma di hamburger ☰ nella barra in alto a sinistra, che mostra il menu di navigazione, e trova il menu Fatturazione.

db49b5267c00cc33.png

Se vedi "Account di fatturazione della prova di Google Cloud Platform" sotto il titolo Fatturazione / Panoramica ( sezione in alto a sinistra della console cloud), il tuo progetto è pronto per essere utilizzato per questo tutorial. In caso contrario, torna all'inizio di questo tutorial e riscatta l'account di fatturazione di prova

7f607aa026552bf5.png

Passaggio 2: 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.

1005cb65520eb3fc.png

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

7f2ad19bc246895d.png

ead4a98e7a8d8a39.png

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

724cf67681535679.png

Successivamente, scegliamo le specifiche del database, selezioniamo la versione Enterprise con il preset della versione Sandbox.

24aa9defed93a3ef.png

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

f9db3a2a923e988f.png

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.

773e2ea11d97369d.png

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

Passaggio 3: acquisisci familiarità con Cloud Shell

Utilizzerai Cloud Shell per la maggior parte dei tutorial. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud. Se ti viene chiesto di autorizzare, fai clic su Autorizza.

1829c3759227c19b.png

b8fe7df5c3c2b919.png

Una volta connesso a Cloud Shell, dobbiamo verificare se la shell ( o il terminale) è già autenticata con il nostro account

gcloud auth list

Se vedi il tuo Gmail personale come nell'esempio di output riportato di seguito, va tutto bene.

Credentialed Accounts

ACTIVE: *
ACCOUNT: alvinprayuda@gmail.com

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

In caso contrario, prova ad aggiornare il browser e assicurati di fare clic su Autorizza quando richiesto ( l'operazione potrebbe essere interrotta a causa di un problema di connessione).

Successivamente, dobbiamo anche verificare se la shell è già configurata con l'ID PROGETTO corretto. Se vedi un valore tra parentesi prima dell'icona $ nel terminale (nella schermata riportata di seguito, il valore è "adk-cloudrun-deployment-476504"), questo valore mostra il progetto configurato per la sessione shell attiva.

5ccbc0cf16feaa0.png

Se il valore mostrato è già corretto, puoi saltare il comando successivo. Tuttavia, se non è corretto o è mancante, esegui il seguente comando

gcloud config set project <YOUR_PROJECT_ID>

Poi, clona 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

Passaggio 4: familiarizza con l'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

Fai clic sul pulsante Apri editor per aprire un editor di Cloud Shell b16d56e4979ec951.png.

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

ee00d484ff2f8351.png

b1fbf2dcd99c468b.png

Ora, la directory di lavoro dell'editor di Cloud Shell dovrebbe essere simile a questa ( all'interno di deploy_and_manage_adk)

4068b1443241bfa1.png

Ora apri il terminale per l'editor. Puoi farlo facendo clic su Terminale -> Nuovo terminale nella barra dei menu oppure utilizzando Ctrl + Maiusc + C. Si aprirà una finestra del terminale nella parte inferiore del browser.

55361099b2f56c79.png

Il terminale attivo corrente deve trovarsi nella 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. Questo pacchetto uv è già preinstallato su Cloud Shell.

Esegui questo comando per installare le dipendenze richieste nell'ambiente virtuale nella directory .venv

uv sync --frozen

Ora dobbiamo abilitare le API richieste tramite il comando mostrato di seguito. L'operazione potrebbe richiedere qualche istante.

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.

Successivamente, dovremo configurare i file di configurazione per questo progetto.

Rinomina il file .env.example in .env

cp .env.example .env

Apri il file .env e aggiorna il valore GOOGLE_CLOUD_PROJECT con il tuo project-id.

# .env

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

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

Per questo codelab, utilizzeremo i valori preconfigurati per GOOGLE_CLOUD_LOCATION e GOOGLE_GENAI_USE_VERTEXAI.. Per ora, manterremo DB_CONNECTION_NAME 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 input/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 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 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 localmente. 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.

e7c9f56c2463164.png

Vedrai la seguente pagina web in cui puoi 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.

d95b1e057315fee2.png

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.

39c0a06ace937683.png

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

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


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

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 nei parametri arg get_fast_api_app per inviare la traccia a Google Cloud Trace
  5. Esegui il servizio FastAPI utilizzando uvicorn

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

5e38fc5607fb4543.jpeg

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]

Ora dobbiamo rivisitare il file .env, aprirlo e vedrai che dobbiamo annullare il commento della variabile DB_CONNECTION_NAME e riempirla con il valore corretto

# 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

Per ottenere il valore di DB_CONNECTION_NAME, puoi tornare a Cloud SQL e fare clic sull'istanza che hai creato. Vai alla barra di ricerca nella sezione superiore della console Cloud e digita "Cloud SQL". Quindi, fai clic sul prodotto Cloud SQL.

1005cb65520eb3fc.png

Dopodiché vedrai l'istanza creata in precedenza. Fai clic su di essa.

ca69aefd116c0b23.png

Nella pagina dell'istanza, scorri verso il basso fino alla sezione "Connetti a questa istanza" e puoi copiare il Nome connessione per sostituire il valore di DB_CONNECTION_NAME.

5d7d6c6f17e559c1.png

Dopodiché, apri il file .env e modifica la variabile DB_CONNECTION_NAME. Il file env dovrebbe essere simile all'esempio seguente

# 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

Dopodiché, esegui lo script di deployment

bash deploy_to_cloudrun.sh

Se ti viene chiesto di confermare la creazione di un registro degli artefatti per il repository Docker, rispondi Y.

Mentre attendiamo il processo di deployment, diamo un'occhiata a 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

Questo script caricherà la variabile .env, quindi eseguirà il comando di deployment.

Se dai un'occhiata più da vicino, abbiamo bisogno di un solo comando gcloud run deploy per fare tutto il necessario per eseguire il deployment di un servizio: creare l'immagine, eseguire il push nel registro, eseguire il deployment del servizio, impostare il criterio IAM, creare la revisione e persino instradare il traffico. In questo esempio, forniamo già il Dockerfile, quindi questo comando lo utilizzerà per creare l'app

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. Nella sezione precedente, abbiamo impostato la concorrenza massima su 10 ( flag --concurrency 10). Pertanto, possiamo aspettarci che Cloud Run tenti di scalare la sua istanza quando eseguiamo test di carico che superano questo numero.

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.

f5cc953cc422de6d.png

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

ddd0df8544aa2bfb.png

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

41b1276616379ee8.png

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

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é stiamo limitando la concorrenza massima a 10 per istanza, l'istanza Cloud Run tenterà di regolare automaticamente il numero di container per soddisfare questa condizione.

1ad41143eb9d95df.png

7. 🚀 Rilascio graduale di nuove revisioni

Ora, consideriamo lo scenario seguente. Vogliamo aggiornare il prompt dell'agente. Apri weather_agent/agent.py e sovrascrivilo con il seguente codice:

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

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

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

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

A questo punto, vai alla pagina del 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.

f5cc953cc422de6d.png

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

ddd0df8544aa2bfb.png

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

8519c5a59bc7efa6.png

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

d4d224e20813c303.png

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

6df497c3d5847f14.png

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 lo abilitiamo nel servizio di cui è stato eseguito il deployment in precedenza

# server.py

...

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

...

app: FastAPI = get_fast_api_app(**app_args)

...

Qui passiamo l'argomento trace_to_cloud a True. Se esegui il deployment con altre opzioni, puoi consultare questa documentazione per ulteriori dettagli su come attivare la tracciabilità in Cloud Trace da varie opzioni di deployment.

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.

4353c0f8982361ab.png

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

c4336d117a3d2f6a.png

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

76a56dff77979037.png

1a3ce0a803d6061a.png

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

2c87b6d67b0164a8.png

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

Prova i workflow multi-agente o con 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.