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

1. Introducción

En este instructivo, se te guiará para implementar, administrar y supervisar un agente potente compilado 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 escalable y alojada en contenedores 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.

En este instructivo, exploraremos la integración perfecta del ADK con Cloud Run. Aprenderás a implementar tu agente y, luego, analizarás los aspectos prácticos de administrar tu aplicación en un entorno similar al de producción. Abordaremos cómo lanzar versiones nuevas de tu agente de forma segura 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 mediante una prueba de carga para observar las capacidades de escalamiento 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 seguimiento con Cloud Trace. Esto te proporcionará una vista detallada y de extremo a extremo de las solicitudes a medida que pasan por tu agente, lo que te permitirá identificar y abordar cualquier cuello de botella de rendimiento. Al final de este instructivo, tendrás una comprensión integral de cómo implementar, administrar y supervisar de manera eficaz tus agentes potenciados por 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 CloudSQL para usarla en el servicio de sesión de la base de datos del agente de ADK
2. Configura un agente de ADK básico
3. Configura el servicio de sesión de base de datos que usará el ejecutor de ADK
4. Implementa el agente en Cloud Run de forma inicial
5. Prueba de carga y cómo inspeccionar el ajuste de escala automático de Cloud Run
6. Implementa una revisión nueva del agente y aumenta gradualmente el tráfico a las revisiones nuevas
7. Configura el seguimiento en la nube y el seguimiento de ejecución del agente

Descripción general de la arquitectura

Requisitos previos

• Trabajar con Python de forma fluida
• Conocimientos básicos de la arquitectura 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 CloudSQL 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 para el lanzamiento gradual con Cloud Run
• Configura el seguimiento del agente de 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 se requiere conocimiento de Python para comprender los conceptos presentados.

2. Antes de comenzar

Selecciona el proyecto activo en la consola de Cloud

En este codelab, se supone que ya tienes un proyecto de Google Cloud con la facturación habilitada. Si aún no lo tienes, puedes seguir las instrucciones que se indican a continuación para comenzar.

1. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
2. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información sobre cómo verificar si la facturación está habilitada en un proyecto.

Prepara la base de datos de Cloud SQL

Necesitaremos una base de datos que el agente de ADK usará más adelante. Crear 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.

Después, tendremos que crear una nueva instancia de base de datos, hacer clic en Crear instancia y elegir PostgreSQL.

Es posible que también debas habilitar la API de Compute Engine si comienzas con un proyecto nuevo. Solo haz clic en Habilitar API si aparece este mensaje.

A continuación, elegiremos las especificaciones de la base de datos, la edición Enterprise con el parámetro predeterminado de la edición Sandbox.

Luego, establece el nombre de la instancia y la contraseña predeterminada para el usuario postgres aquí. Puedes configurar esto con las credenciales que quieras. Sin embargo, para este instructivo, usaremos "adk-deployment" para el nombre de la instancia y la contraseña.

Importante: El nombre de usuario y la contraseña son datos sensibles, así que asegúrate de que los demás no los conozcan.

Usemos us-central1 con una sola zona para este instructivo. Luego, podemos finalizar la creación de la base de datos y dejar que termine toda la configuración requerida haciendo clic en el botón Create Instance.

Ten paciencia, la creación de la base de datos tardará entre 5 y 10 minutos en completarse.

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

Configura un proyecto de Cloud en la terminal de Cloud Shell

1. Usarás Cloud Shell, un entorno de línea de comandos que se ejecuta en Google Cloud. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.

2. Una vez que te conectes a Cloud Shell, verifica que ya te hayas autenticado y que el proyecto esté configurado con tu ID con el siguiente comando:

gcloud auth list

3. En Cloud Shell, ejecuta el siguiente comando para confirmar que el comando gcloud conoce tu proyecto.

gcloud config list project

4. Si tu proyecto no está configurado, usa el siguiente comando para hacerlo:

gcloud config set project <YOUR_PROJECT_ID>

Como alternativa, también puedes ver el ID de PROJECT_ID en la consola.

Haz clic en él y verás todo tu proyecto y el ID del proyecto en el lado derecho.

5. Habilita las APIs requeridas con el siguiente comando. Este proceso puede tardar unos minutos, así que ten paciencia.

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

Operation "operations/..." finished successfully.

La alternativa al comando gcloud es buscar cada producto en la consola o usar este vínculo.

Si falta alguna API, puedes habilitarla durante el transcurso de la implementación.

Consulta la documentación para ver los comandos y el uso de gcloud.

Ve al 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 tareas de programación. Para ello, usaremos el editor de Cloud Shell.

1. Haz clic en el botón Open Editor para abrir el editor de Cloud Shell. Allí, podemos escribir nuestro código
2. Asegúrate de que el proyecto de Cloud Code esté configurado en la esquina inferior izquierda (barra de estado) del editor de Cloud Shell, como se destaca en la siguiente imagen, y que esté configurado en el proyecto activo de Google Cloud en el que tienes habilitada la facturación. Autorizar si se te solicita. Si ya seguiste el comando anterior, es posible que el botón también dirija directamente a tu proyecto activado en lugar del botón de acceso.

Ten paciencia. Es posible que debas esperar un momento después de inicializar el editor de Cloud Shell para que aparezca el botón Cloud Code - Sign In.

3. A continuación, clonaremos el directorio de trabajo de la plantilla de 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

4. Después, ve a la sección superior del editor de Cloud Shell y haz clic en File->Open Folder, busca el directorio username y el directorio deploy_and_manage_adk y, luego, haz clic en el botón OK. Esto hará que el directorio elegido sea 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.

Ahora, el editor de Cloud Shell debería verse de la siguiente manera:

A continuación, podemos configurar nuestro entorno de Python.

Configuración del entorno

Prepara el entorno virtual de Python

El siguiente paso es preparar el entorno de desarrollo. Tu directorio de trabajo de la terminal activa actual debe estar dentro del directorio de trabajo deploy_and_manage_adk. En este codelab, usaremos Python 3.12 y el administrador de proyectos de Python de uv para simplificar la necesidad de crear y administrar la versión de Python y el entorno virtual.

1. Si aún no abriste la terminal, haz clic en Terminal -> Nueva terminal o usa Ctrl + Mayúsculas + C para abrir una ventana de terminal en la parte inferior del navegador.

2. Descarga uv y, luego, instala Python 3.12 con el siguiente comando:

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

3. Ahora , inicialicemos el entorno virtual con uv. Ejecuta este comando.

uv sync --frozen

Se creará el directorio .venv y se instalarán las dependencias. Un adelanto rápido del archivo pyproject.toml te brindará información sobre las dependencias que se muestran de la siguiente manera:

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

Nota: Las dependencias de Python se declaran en pyproject.toml y tienen la versión bloqueada en el archivo uv.lock.

4. Para probar el entorno virtual, crea un archivo nuevo main.py y copia el siguiente código:

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

if __name__ == "__main__":
   main()

5. Luego, ejecuta el siguiente comando:

uv run main.py

Obtendrás un resultado como el que se muestra a continuación.

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

Esto demuestra que el proyecto de Python se está configurando correctamente.

Nota: No fue necesario crear un entorno virtual de forma manual ni activarlo, ya que uv ya lo controla todo. A partir de este punto, el comando estándar de Python (p.ej., python main.py) se reemplazará por uv run (p.ej., uv run main.py).

Configura archivos de configuración

Ahora, debemos configurar los archivos de configuración de este proyecto.

Cambia el nombre del archivo .env.example a .env y se mostrará el valor a continuación. Actualiza el valor de GOOGLE_CLOUD_PROJECT a tu 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: Actualiza los valores de GOOGLE_CLOUD_PROJECT con el ID de tu proyecto.

Para este codelab, usaremos los valores preconfigurados de GOOGLE_CLOUD_LOCATION y GOOGLE_GENAI_USE_VERTEXAI.. Por ahora, mantendremos SESSION_SERVICE_URI comentado.

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

3. Compila el agente del clima con 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 su ejecución de comandos de CLI. Estos son algunos de ellos :

• Configura la estructura del directorio del agente
• Prueba 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

Y 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 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 estructura de directorios, la importación de agentes dentro de init.py y la declaración de root_agent en agent.py son la estructura obligatoria que debe reconocer la CLI de ADK.

Explicación del código del ADK

Esta secuencia de comandos contiene la inicialización de nuestro agente, en la que inicializamos lo siguiente:

• 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, además, inspeccionar su comportamiento de forma local. El ADK nos permite tener una IU web de desarrollo para interactuar e inspeccionar lo que 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 como el 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 el área superior del editor de Cloud Shell y selecciona Vista previa en el puerto 8080.

Verás la siguiente página web, en la que puedes 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.

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

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

Recordatorio: Por ahora, vamos a finalizar el proceso adk web. Para ello, presiona CTRL + C.

4. La secuencia de comandos del servidor de backend

Para que el agente sea accesible como servicio, lo uniremos dentro de una app de FastAPI. Aquí, podemos configurar los servicios necesarios para admitir el agente, como preparar el servicio de sesión, memoria o artefacto 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
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)

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 usa para la IU de desarrollo web.
2. Para configurar el servicio de sesión, memoria o artefacto necesario, agrega 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 empresarial de backend. En la secuencia de comandos, agregamos un ejemplo de ruta de la funcionalidad de comentarios.
4. Habilita el seguimiento de nube para enviar seguimientos a Google Cloud Trace

5. Implementa en Cloud Run

Ahora, implementemos este servicio de agente en Cloud Run. A los efectos de esta demostración, este servicio se expondrá como un servicio público al que otras personas puedan acceder. Sin embargo, ten en cuenta que esta no es una práctica recomendada, ya que no es segura.

En este codelab, usaremos Dockerfile para implementar nuestro agente en Cloud Run. A continuación, se muestra el contenido del Dockerfile que se usará.

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

En este punto, ya tenemos todos los archivos necesarios para implementar nuestras aplicaciones en Cloud Run. Implementémoslas. Navega a la terminal de Cloud Shell y asegúrate de que el proyecto actual esté configurado en tu proyecto activo. De lo contrario, usa el comando gcloud configure para establecer el ID del proyecto:

gcloud config set project [PROJECT_ID]

Luego, ejecuta el siguiente comando para implementarlo en 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: Actualiza los valores de YOUR_DB_CONNECTION_NAME, YOUR_DEFAULT_USER_PASS y YOUR_PROJECT_ID aquí.

Ten en cuenta que proporcionamos SESSION_SERVICE_URI aquí como variables de entorno para el instructivo. Esto no se recomienda, ya que expondrá el nombre de usuario y la contraseña de la base de datos. Intenta usar un secreto para casos como este

Para obtener el valor de {YOUR_DB_CONNECTION_NAME}, puedes volver a ir a Cloud SQL y hacer clic en la instancia que creaste. En la página de la instancia, desplázate hacia abajo hasta la sección "Conéctate a esta instancia" y puedes copiar el nombre de la conexión para reemplazar el valor {YOUR_DB_CONNECTION_NAME}. Por ejemplo, consulta la imagen que se muestra a continuación.

Nota: Cuando se configure SESSION_SERVICE_URI, nuestro agente de ADK usará el URI del servicio para almacenar la información y el estado de la sesión. En este instructivo, usamos la conexión de socket Unix de PostgreSQL con el controlador pg8000.

Ten en cuenta que, en el ejemplo, usamos el usuario predeterminado postgres y la base de datos predeterminada postgres. Si usas los mismos valores con el instructivo, tu SESSION_SERVICE_URI debería verse de la siguiente manera:

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

Por lo tanto, solo debes reemplazar el ID del proyecto aquí.

Si se te solicita que confirmes la creación de un registro de artefactos para el repositorio de Docker, responde Y. Ten en cuenta que permitimos el acceso no autenticado porque esta es una aplicación de demostración. Se recomienda usar la autenticación adecuada para tus aplicaciones empresariales y de producción.

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

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

Usa la aplicación desde la ventana de incógnito o tu dispositivo móvil. Ya debería estar publicado.

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

Ahora, inspeccionaremos las capacidades de escalamiento automático de Cloud Run. En este caso, implementemos una revisión nueva y habilitemos las simultaneidades máximas por instancia. Ejecuta el siguiente comando

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

Nota importante: Actualiza los valores de YOUR_PROJECT_ID aquí.

Después, inspeccionemos el archivo load_test.py. Esta será la secuencia de comandos que usaremos para realizar las pruebas de carga con el framework locust. Esta secuencia de comandos hará lo siguiente :

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

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

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

La URL del servicio se mostrará junto a la información de la región. P. ej.,

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

Nota importante: Actualiza los valores de YOUR_SERVICE_URL aquí.

Nota: Esto simulará una rampa de solicitudes de usuarios en paralelo de 0 a 60 con una tasa de 5 usuarios por segundo durante un período de 120 segundos.

Cuando lo ejecutes, verás métricas como las siguientes. ( en este ejemplo, todas las solicitudes se realizan 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, volvamos a tu servicio implementado y veamos el panel. Se mostrará cómo Cloud Run escala automáticamente 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.

Nota: Puedes controlar no solo la simultaneidad máxima, sino también las instancias mínimas y máximas de contenedores. Consulta esta documentación del SDK para obtener más información.

7. Lanzamiento gradual de revisiones nuevas

Ahora, consideremos la siguiente situación. Queremos actualizar la instrucción del agente a la siguiente :

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

Luego, quieres lanzar revisiones nuevas, pero no quieres que todo el tráfico de solicitudes vaya directamente a la versión nueva. Podemos realizar un lanzamiento gradual con Cloud Run. Primero, debemos implementar una revisión nueva, pero con la marca –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

Nota importante: Actualiza los valores de YOUR_PROJECT_ID aquí.

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 entrega. Se mostrará el 0 por ciento del tráfico publicado.

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.

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

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

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

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

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

8. Registros de ADK

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

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

...

Aquí, inicializamos el generador de registros y el exportador. Los detalles del exportador se pueden inspeccionar en tracing.py . Aquí, creamos un exportador personalizado porque hay un límite en los datos de seguimiento que se pueden exportar al seguimiento de Cloud. Usamos una implementación de https://googlecloudplatform.github.io/agent-starter-pack/guide/observability.html para esta función de seguimiento.

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

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

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, observa las imágenes a continuación

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

Ya está, ahora tenemos una buena visibilidad y información sobre cada interacción de nuestro agente con el usuario para ayudar a depurar los problemas. No dudes en probar varias herramientas o flujos de trabajo.

9. Desafío

Prueba flujos de trabajo de varios agentes o agentes para ver cómo se comportan bajo cargas y cómo se ve el seguimiento

10. Limpia

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.