Implementa, administra y observa el agente de ADK en Cloud Run

1. Introducción

En este instructivo, se explica cómo implementar, administrar y supervisar un agente potente creado con el Kit de desarrollo de agentes (ADK) en Google Cloud Run. El ADK te permite crear agentes capaces de realizar flujos de trabajo complejos de varios agentes. Si aprovechas Cloud Run, una plataforma sin servidores completamente administrada, puedes implementar tu agente como una aplicación alojada en contenedores y escalable sin preocuparte por la infraestructura subyacente. Esta potente combinación te permite enfocarte en la lógica principal de tu agente y, al mismo tiempo, beneficiarte del entorno sólido y escalable de Google Cloud.

A lo largo de este instructivo, exploraremos la integración perfecta del ADK con Cloud Run. Aprenderás a implementar tu agente y, luego, te sumergirás en los aspectos prácticos de la administración de tu aplicación en un entorno similar al de producción. Abordaremos cómo lanzar de forma segura versiones nuevas de tu agente administrando el tráfico, lo que te permitirá probar funciones nuevas con un subconjunto de usuarios antes de un lanzamiento completo.

Además, obtendrás experiencia práctica en la supervisión del rendimiento de tu agente. Simularemos una situación real realizando una prueba de carga para observar las capacidades de ajuste de escala automático de Cloud Run en acción. Para obtener estadísticas más detalladas sobre el comportamiento y el rendimiento de tu agente, habilitaremos el registro con Cloud Trace. Esto proporcionará una vista detallada de extremo a extremo de las solicitudes a medida que viajan a través de tu agente, lo que te permitirá identificar y abordar cualquier cuello de botella de rendimiento. Al final de este instructivo, comprenderás cómo implementar, administrar y supervisar de manera eficaz tus agentes potenciados por el ADK en Cloud Run.

En el codelab, seguirás un enfoque paso a paso de la siguiente manera:

  1. Crea una base de datos de PostgreSQL en Cloud SQL para usarla en el servicio de sesión de la base de datos del agente del ADK
  2. Configura un agente básico del ADK
  3. Configura el servicio de sesión de la base de datos para que lo use el ejecutor del ADK
  4. Implementa inicialmente el agente en Cloud Run
  5. Realiza pruebas de carga y examina el ajuste de escala automático de Cloud Run
  6. Implementa una revisión nueva del agente y aumenta gradualmente el tráfico hacia las revisiones nuevas
  7. Configura el registro de seguimiento en la nube y, luego, inspecciona el registro de seguimiento de la ejecución del agente

Descripción general de la arquitectura

5cdb729288bf43de.jpeg

Requisitos previos

  • Comodidad para trabajar con Python
  • Conocimiento de la arquitectura básica de pila completa con el servicio HTTP

Qué aprenderás

  • Estructura del ADK y utilidades locales
  • Configura el agente de ADK con el servicio de sesión de la base de datos
  • Configura PostgreSQL en Cloud SQL para que lo use el servicio de sesión de la base de datos
  • Implementa la aplicación en Cloud Run con Dockerfile y configura las variables de entorno iniciales
  • Configura y prueba el ajuste de escala automático de Cloud Run con pruebas de carga
  • Estrategia de lanzamiento gradual con Cloud Run
  • Configura el registro del agente del ADK en Cloud Trace

Requisitos

  • Navegador web Chrome
  • Una cuenta de Gmail
  • Un proyecto de Cloud con la facturación habilitada

Este codelab, diseñado para desarrolladores de todos los niveles (incluidos los principiantes), usa Python en su aplicación de ejemplo. Sin embargo, no es necesario tener conocimientos de Python para comprender los conceptos que se presentan.

2. 🚀 Preparación de la configuración de desarrollo del taller

Paso 1: Selecciona el proyecto activo en la consola de Cloud

En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud (consulta la sección superior izquierda de la consola).

9803a4534597d962.png

Haz clic en él y verás una lista de todos tus proyectos, como en este ejemplo:

5b60dbeab4f9b524.png

El valor que se indica con el cuadro rojo es el ID DEL PROYECTO, y se usará en todo el instructivo.

Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Para verificarlo, haz clic en el ícono de hamburguesa ☰ en la barra superior izquierda, que muestra el menú de navegación, y busca el menú Facturación.

db49b5267c00cc33.png

Si ves "Cuenta de facturación de la prueba de Google Cloud Platform" debajo del título Facturación / Descripción general ( sección superior izquierda de tu consola de Cloud), tu proyecto está listo para usarse en este instructivo. De lo contrario, vuelve al inicio de este instructivo y canjea la cuenta de facturación de prueba.

7f607aa026552bf5.png

Paso 2: Prepara la base de datos de Cloud SQL

Más adelante, necesitaremos una base de datos para que la utilice el agente de ADK. Creemos una base de datos de PostgreSQL en Cloud SQL. Primero, navega a la barra de búsqueda en la sección superior de la consola de Cloud y escribe "Cloud SQL". Luego, haz clic en el producto Cloud SQL.

1005cb65520eb3fc.png

Después, deberemos crear una instancia de base de datos nueva. Para ello, haz clic en Crear instancia y elige PostgreSQL.

7f2ad19bc246895d.png

ead4a98e7a8d8a39.png

También es posible que debas habilitar la API de Compute Engine si comienzas con un proyecto nuevo. Para ello, haz clic en Habilitar API si aparece este mensaje.

724cf67681535679.png

A continuación, elegiremos las especificaciones de la base de datos y seleccionaremos la edición Enterprise con el ajuste predeterminado de edición Sandbox.

24aa9defed93a3ef.png

Después de eso, establece el nombre de la instancia y la contraseña predeterminada para el usuario postgres aquí. Puedes configurar esto con las credenciales que desees. Sin embargo, para este instructivo, usaremos "adk-deployment" como nombre de instancia y "ADK-deployment123" como contraseña.

f9db3a2a923e988f.png

Usemos us-central1 con una sola zona para este instructivo. Podemos finalizar la creación de nuestra base de datos y dejar que complete toda la configuración necesaria haciendo clic en el botón Crear instancia.

773e2ea11d97369d.png

Mientras esperamos a que termine, podemos continuar con la siguiente sección.

Paso 3: Familiarízate con Cloud Shell

Usarás Cloud Shell durante la mayor parte de los instructivos. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud. Si se te solicita autorización, haz clic en Autorizar.

1829c3759227c19b.png

b8fe7df5c3c2b919.png

Una vez que te conectes a Cloud Shell, deberemos verificar si el shell ( o la terminal) ya se autenticó con nuestra cuenta.

gcloud auth list

Si ves tu Gmail personal como en el siguiente ejemplo de resultado, todo está bien.

Credentialed Accounts

ACTIVE: *
ACCOUNT: alvinprayuda@gmail.com

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

Si no es así, intenta actualizar el navegador y asegúrate de hacer clic en Autorizar cuando se te solicite ( es posible que se interrumpa debido a un problema de conexión).

A continuación, también debemos verificar si la shell ya está configurada con el ID DEL PROYECTO correcto que tienes. Si ves que hay un valor dentro de ( ) antes del ícono $ en la terminal ( en la captura de pantalla a continuación, el valor es "adk-cloudrun-deployment-476504"), este valor muestra el proyecto configurado para tu sesión de shell activa.

5ccbc0cf16feaa0.png

Si el valor que se muestra ya es correcto, puedes omitir el siguiente comando. Sin embargo, si no es correcto o falta, ejecuta el siguiente comando:

gcloud config set project <YOUR_PROJECT_ID>

Luego, clona el directorio de trabajo de la plantilla para este codelab desde GitHub. Para ello, ejecuta el siguiente comando. Se creará el directorio de trabajo en el directorio deploy_and_manage_adk.

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

Paso 4: Familiarízate con el editor de Cloud Shell y configura el directorio de trabajo de la aplicación

Ahora, podemos configurar nuestro editor de código para hacer algunas cosas de programación. Usaremos el editor de Cloud Shell para esto.

Haz clic en el botón Abrir editor para abrir un editor de Cloud Shell b16d56e4979ec951.png.

Luego, ve a la sección superior del editor de Cloud Shell y haz clic en File->Open Folder, busca tu directorio de nombre de usuario y el directorio deploy_and_manage_adk y, luego, haz clic en el botón Aceptar. Esto convertirá el directorio elegido en el directorio de trabajo principal. En este ejemplo, el nombre de usuario es alvinprayuda, por lo que la ruta de acceso del directorio se muestra a continuación.

ee00d484ff2f8351.png

b1fbf2dcd99c468b.png

Ahora, tu directorio de trabajo del editor de Cloud Shell debería verse de la siguiente manera ( dentro de deploy_and_manage_adk):

4068b1443241bfa1.png

Ahora, abre la terminal del editor. Para ello, haz clic en Terminal -> New Terminal en la barra de menú o usa Ctrl + Mayúsculas + C. Se abrirá una ventana de terminal en la parte inferior del navegador.

55361099b2f56c79.png

Tu terminal activa actual debe estar dentro del directorio de trabajo deploy_and_manage_adk. Usaremos Python 3.12 en este codelab y uv python project manager para simplificar la necesidad de crear y administrar la versión de Python y el entorno virtual. Este paquete uv ya está preinstalado en Cloud Shell.

Ejecuta este comando para instalar las dependencias requeridas en el entorno virtual del directorio .venv.

uv sync --frozen

Ahora, deberemos habilitar las APIs requeridas con el siguiente comando. Este proceso podría tardar un poco.

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

Si el comando se ejecuta correctamente, deberías ver un mensaje similar al que se muestra a continuación:

Operation "operations/..." finished successfully.

A continuación, deberemos configurar los archivos de configuración para este proyecto.

Cambia el nombre del archivo .env.example por .env.

cp .env.example .env

Abre el archivo .env y actualiza el valor de GOOGLE_CLOUD_PROJECT a tu 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

Para este codelab, usaremos los valores preconfigurados para GOOGLE_CLOUD_LOCATION y GOOGLE_GENAI_USE_VERTEXAI.. Por ahora, mantendremos DB_CONNECTION_NAME como comentario.

Ahora podemos pasar al siguiente paso: inspeccionar la lógica del agente y, luego, implementarlo.

3. 🚀 Crea el agente del clima con el ADK y Gemini 2.5

Introducción a la estructura de directorios del ADK

Comencemos por explorar lo que ofrece el ADK y cómo compilar el agente. Puedes acceder a la documentación completa del ADK en esta URL . El ADK nos ofrece muchas utilidades dentro de la ejecución de su comando de CLI. Algunos de ellos son los siguientes :

  • Configura la estructura del directorio del agente
  • Probar rápidamente la interacción a través de la entrada y salida de la CLI
  • Configura rápidamente la interfaz web de la IU de desarrollo local

Ahora, revisemos la estructura del agente en el directorio weather_agent.

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

Si inspeccionas init.py y agent.py, verás este código

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

Explicación del código del ADK

Este script contiene la inicialización de nuestro agente, en la que inicializamos los siguientes elementos:

  • Configura el modelo que se usará en gemini-2.5-flash
  • Proporciona la herramienta get_weather para admitir la funcionalidad del agente como agente meteorológico.

Ejecuta la IU web

Ahora, podemos interactuar con el agente y analizar su comportamiento de forma local. El ADK nos permite tener una IU web de desarrollo para interactuar y ver qué sucede durante la interacción. Ejecuta el siguiente comando para iniciar el servidor de la IU de desarrollo local:

uv run adk web --port 8080

Se generará un resultado similar al siguiente ejemplo, lo que significa que ya podemos acceder a la interfaz 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)

Ahora, para verificarlo, haz clic en el botón Vista previa en la Web en la parte superior del editor de Cloud Shell y selecciona Vista previa en el puerto 8080.

e7c9f56c2463164.png

Verás la siguiente página web en la que podrás seleccionar los agentes disponibles en el botón desplegable de la parte superior izquierda ( en nuestro caso, debería ser weather_agent) y, luego, interactuar con el bot. En la ventana de la izquierda, verás mucha información sobre los detalles del registro durante el tiempo de ejecución del agente.

d95b1e057315fee2.png

Ahora, intenta interactuar con él. En la barra izquierda, podemos inspeccionar el registro de cada entrada para comprender cuánto tiempo tarda cada acción que realiza el agente antes de formar la respuesta final.

39c0a06ace937683.png

Esta es una de las funciones de observabilidad integradas en el ADK. Actualmente, la inspeccionamos de forma local. Más adelante, veremos cómo se integra esto en Cloud Trace para que tengamos un registro centralizado de todas las solicitudes.

4. 🚀 Implementación en Cloud Run

Ahora, implementemos este servicio de agente en Cloud Run. Para los fines de esta demostración, este servicio se expondrá como un servicio público al que pueden acceder otras personas. Sin embargo, ten en cuenta que esta no es la mejor práctica, ya que no es segura.

5cdb729288bf43de.jpeg

En este codelab, usaremos Dockerfile para implementar nuestro agente en Cloud Run. En este punto, ya tenemos todos los archivos necesarios ( el Dockerfile y el server.py) para implementar nuestras aplicaciones en Cloud Run. Hablaremos de esto en detalle más adelante.

Ahora, implementemos el servicio primero. Para ello, navega a la terminal de Cloud Shell y asegúrate de que el proyecto actual esté configurado en tu proyecto activo. Si no es así, debes usar el comando gcloud config para establecer el ID del proyecto:

gcloud config set project [PROJECT_ID]

Ahora, debemos volver a visitar el archivo .env, abrirlo y verás que debemos quitar el comentario de la variable DB_CONNECTION_NAME y completarla con el valor correcto.

# 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

Para obtener el valor de DB_CONNECTION_NAME, puedes volver a Cloud SQL y hacer clic en la instancia que creaste. Navega a la barra de búsqueda en la sección superior de la consola de Cloud y escribe "Cloud SQL". Luego, haz clic en el producto Cloud SQL.

1005cb65520eb3fc.png

Después, verás la instancia creada anteriormente. Haz clic en ella.

ca69aefd116c0b23.png

En la página de la instancia, desplázate hacia abajo hasta la sección "Conéctate a esta instancia" y podrás copiar el Nombre de la conexión para sustituir el valor de DB_CONNECTION_NAME.

5d7d6c6f17e559c1.png

Luego, abre el archivo .env y modifica la variable DB_CONNECTION_NAME. Tu archivo .env debería verse como el siguiente ejemplo:

# 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

Después de eso, ejecuta la secuencia de comandos de implementación.

bash deploy_to_cloudrun.sh

Si se te solicita que confirmes la creación de un registro de artefactos para el repositorio de Docker, responde Y.

Mientras esperamos el proceso de implementación, veamos el archivo 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

Esta secuencia de comandos cargará tu variable .env y, luego, ejecutará el comando de implementación.

Si observas con más detalle, solo necesitamos un comando gcloud run deploy para hacer todo lo necesario si quieres implementar un servicio: compilar la imagen, enviar al registro, implementar el servicio, configurar la política de IAM, crear la revisión y hasta enrutar el tráfico. En este ejemplo, ya proporcionamos el Dockerfile, por lo que este comando lo utilizará para compilar la app.

Una vez que se complete la implementación, deberías obtener un vínculo similar al siguiente:

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

Después de obtener esta URL, puedes usar tu aplicación desde la ventana de incógnito o tu dispositivo móvil y acceder a la IU para desarrolladores del agente. Mientras esperas la implementación, inspeccionemos el servicio detallado que acabamos de implementar en la siguiente sección.

5. 💡 El Dockerfile y el script del servidor de backend

Para que el agente sea accesible como servicio, lo encapsularemos en una app de FastAPI que se ejecutará en el comando Dockerfile. A continuación, se muestra el contenido del 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"]

Aquí podemos configurar los servicios necesarios para admitir el agente, como preparar los servicios Session, Memory o Artifact para fines de producción. Este es el código de server.py que se usará

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)

Explicación del código del servidor

Estos son los elementos que se definen en la secuencia de comandos server.py:

  1. Convierte nuestro agente en una app de FastAPI con el método get_fast_api_app. De esta manera, heredaremos la misma definición de ruta que se utiliza para la IU de desarrollo web.
  2. Configura el servicio de sesión, memoria o artefacto necesario agregando los argumentos de palabras clave al método get_fast_api_app. En este instructivo, si configuramos la variable de entorno SESSION_SERVICE_URI, el servicio de sesión la usará. De lo contrario, usará la sesión en memoria.
  3. Podemos agregar una ruta personalizada para admitir otra lógica comercial de backend. En la secuencia de comandos, agregamos un ejemplo de ruta de funcionalidad de comentarios.
  4. Habilita el seguimiento de nube en los parámetros de argumentos get_fast_api_app para enviar el registro a Google Cloud Trace.
  5. Ejecuta el servicio de FastAPI con Uvicorn

Ahora, si tu implementación ya finalizó, intenta interactuar con el agente desde la IU para desarrolladores web accediendo a la URL de Cloud Run.

6. 🚀 Inspecciona el ajuste de escala automático de Cloud Run con pruebas de carga

Ahora, inspeccionaremos las capacidades de escalado automático de Cloud Run. Para este caso, implementaremos una revisión nueva y habilitaremos la máxima simultaneidad por instancia. En la sección anterior, establecimos la simultaneidad máxima en 10 ( marca --concurrency 10). Por lo tanto, podemos esperar que Cloud Run intente escalar su instancia cuando realicemos una prueba de carga que supere este número.

Inspeccionemos el archivo load_test.py. Esta será la secuencia de comandos que usaremos para realizar la prueba de carga con el framework de locust. Esta secuencia de comandos hará lo siguiente :

  1. user_id y session_id aleatorios
  2. Crea session_id para el user_id
  3. Llama al extremo "/run_sse" con el user_id y el session_id creados.

Si no la recuerdas, necesitaremos saber la URL del servicio implementado. Ve a la consola de Cloud Run y haz clic en tu servicio weather-agent.

f5cc953cc422de6d.png

Luego, busca tu servicio weather-agent y haz clic en él.

ddd0df8544aa2bfb.png

La URL del servicio se mostrará justo al lado de la información de la región. P. ej.,

41b1276616379ee8.png

Luego, ejecuta el siguiente comando para realizar la prueba de carga:

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

Si ejecutas este comando, verás métricas como las que se muestran a continuación. ( En este ejemplo, todas las solicitudes se completaron correctamente).

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

Luego, veamos qué sucedió en Cloud Run. Vuelve a tu servicio implementado y consulta el panel. Esto mostrará cómo Cloud Run ajusta automáticamente la escala de la instancia para controlar las solicitudes entrantes. Como limitamos la simultaneidad máxima a 10 por instancia, la instancia de Cloud Run intentará ajustar la cantidad de contenedores para satisfacer esta condición automáticamente.

1ad41143eb9d95df.png

7. 🚀 Lanzamiento gradual de revisiones nuevas

Ahora, veamos la siguiente situación. Queremos actualizar la instrucción del agente. Abre weather_agent/agent.py y reemplázalo por el siguiente código:

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

Luego, quieres lanzar revisiones nuevas, pero no quieres que todo el tráfico de solicitudes vaya directamente a la versión nueva. Podemos hacer lanzamientos graduales con Cloud Run. Primero, debemos implementar una revisión nueva, pero con el parámetro –no-traffic. Guarda la secuencia de comandos del agente anterior y ejecuta el siguiente comando:

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

Cuando termines, recibirás un registro similar al del proceso de implementación anterior, con la diferencia de la cantidad de tráfico que se atendió. Se mostrará el 0% del tráfico publicado.

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

A continuación, ve a la página del producto de Cloud Run y busca tu instancia implementada. Escribe Cloud Run en la barra de búsqueda y haz clic en el producto Cloud Run.

f5cc953cc422de6d.png

Luego, busca tu servicio weather-agent y haz clic en él.

ddd0df8544aa2bfb.png

Ve a la pestaña Revisiones y verás la lista de revisiones implementadas.

8519c5a59bc7efa6.png

Verás que las nuevas revisiones implementadas publican el 0% del tráfico. Desde aquí, puedes hacer clic en el botón de kebab (⋮) y elegir Administrar tráfico.

d4d224e20813c303.png

En la ventana emergente nueva, puedes editar el porcentaje de tráfico que se dirige a cada revisión.

6df497c3d5847f14.png

Después de esperar un tiempo, el tráfico se dirigirá de forma proporcional según los porcentajes de configuración. De esta manera, podemos revertir fácilmente a las revisiones anteriores si sucede algo con la nueva versión.

8. 🚀 Registro de ADK

Los agentes compilados con el ADK ya admiten el seguimiento con la incorporación de OpenTelemetry. Tenemos Cloud Trace para capturar esos seguimientos y visualizarlos. Inspeccionemos server.py para ver cómo lo habilitamos en nuestro servicio implementado anteriormente.

# server.py

...

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

...

app: FastAPI = get_fast_api_app(**app_args)

...

Aquí, pasamos el argumento trace_to_cloud a True. Si realizas la implementación con otras opciones, puedes consultar esta documentación para obtener más detalles sobre cómo habilitar el registro en Cloud Trace desde varias opciones de implementación.

Intenta acceder a la IU web de desarrollo de tu servicio y chatea con el agente. Luego, ve a la barra de búsqueda de la consola de Cloud, escribe "explorador de seguimiento" y elige el producto Explorador de seguimiento.

4353c0f8982361ab.png

En la página del explorador de registros, verás que se envió el registro de nuestra conversación con el agente. Puedes ver en la sección Nombre del tramo y filtrar el tramo específico de nuestro agente ( se llama agent_run [weather_agent]).

c4336d117a3d2f6a.png

Cuando los intervalos ya están filtrados, también puedes inspeccionar cada registro directamente. Se mostrará la duración detallada de cada acción que realice el agente. Por ejemplo, mira las imágenes a continuación.

76a56dff77979037.png

1a3ce0a803d6061a.png

En cada sección, puedes inspeccionar los detalles de los atributos, como se muestra a continuación.

2c87b6d67b0164a8.png

Listo. Ahora tenemos buena observabilidad e información sobre cada interacción de nuestro agente con el usuario para ayudar a depurar problemas. No dudes en probar diferentes herramientas o flujos de trabajo.

9. 🎯 Desafío

Prueba flujos de trabajo multiagente o basados en agentes para ver cómo se desempeñan bajo cargas y cómo se ve el registro.

10. 🧹 Limpieza

Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en este codelab:

  1. En la consola de Google Cloud, ve a la página Administrar recursos.
  2. En la lista de proyectos, elige el proyecto que deseas borrar y haz clic en Borrar.
  3. En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrarlo.
  4. Como alternativa, puedes ir a Cloud Run en la consola, seleccionar el servicio que acabas de implementar y borrarlo.