Agente de ciencia de datos con estado en Agent Runtime

1. Descripción general

En este codelab, crearás un agente de ciencia de datos que consulta datos reales de conjuntos de datos públicos de BigQuery y recuerda tus preferencias en diferentes sesiones. Luego, lo implementarás en Agent Runtime, un servicio completamente administrado de Google Cloud que controla la infraestructura, el escalamiento y la administración de sesiones.

El agente utiliza tres capacidades principales que se activan de forma progresiva:

• BigQuery Toolset: El agente explora esquemas y ejecuta consultas de SQL en conjuntos de datos reales de BigQuery, lo que funciona tanto de forma local como cuando se implementa.
• Memory Bank: Cuando se implementa, el agente recuerda las preferencias y el contexto del usuario en sesiones desconectadas.
• Observabilidad: Cloud Trace captura los pasos de razonamiento, las llamadas a herramientas y las latencias del agente a través de la instrumentación de OpenTelemetry.

Qué aprenderás

• Cómo crear un agente del ADK con BigQueryToolset para acceder a datos reales
• Cómo configurar Memory Bank para la persistencia entre sesiones
• Cómo implementar tu agente en Agent Runtime con adk deploy
• Cómo otorgar permisos de IAM a la cuenta de servicio del agente implementado
• Cómo probar la persistencia y la observabilidad de la memoria

Requisitos

• Un proyecto de Google Cloud con la facturación habilitada.
• Un navegador web, como Chrome
• Si ejecutas el código en tu propia máquina en lugar de Cloud Shell, necesitarás el SDK de Google Cloud (CLI de gcloud), uv (administrador de paquetes de Python) y Python 3.12 o versiones posteriores (uv lo instala automáticamente si es necesario).

El ADK (Kit de desarrollo de agentes) es el framework de Google para crear agentes de IA. En este codelab, se usa el ADK para crear un agente y, luego, implementarlo en Agent Runtime.

Este codelab está dirigido a desarrolladores intermedios que tienen cierta familiaridad con Python y Google Cloud.

Este codelab tarda aproximadamente 35 minutos en completarse (incluidos entre 5 y 10 minutos para la implementación).

Los recursos creados en este codelab deberían costar menos de USD 5.

2. Configura tu entorno

Crea un proyecto de Google Cloud

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 para verificar si la facturación está habilitada en un proyecto.

Configura tu proyecto

Abre el editor de Cloud Shell en el proyecto de GCP que creaste.

Luego, crea una Terminal > Terminal nueva y ejecuta el siguiente comando para configurar tu proyecto. Los comandos posteriores leerán el ID del proyecto desde este parámetro de configuración.

gcloud config set project <INSERT_YOUR_GCP_PROJECT_HERE>

Habilita las APIs

En la terminal, ejecuta el siguiente comando.

gcloud services enable \
  aiplatform.googleapis.com \
  bigquery.googleapis.com \
  telemetry.googleapis.com \
  --project=$(gcloud config get project)

• aiplatform.googleapis.com: Aloja tu agente en Agent Runtime, incluidas las sesiones de Gemini Enterprise y Memory Bank, y entrega el modelo de Gemini.
• API de BigQuery (bigquery.googleapis.com): Consultas en SQL en conjuntos de datos públicos y privados
• API de Telemetry (telemetry.googleapis.com): Registros de OpenTelemetry para la observabilidad del agente

La habilitación de la API puede tardar hasta un minuto en propagarse. Si ves errores de "API no habilitada" en pasos posteriores, espera un momento y vuelve a intentarlo.

Instala el ADK.

En la terminal, ejecuta los siguientes comandos para crear una carpeta para este codelab y, luego, instalar el ADK y sus dependencias:

mkdir -p ~/adk-deploy-scale
cd ~/adk-deploy-scale
uv init --bare
uv add google-adk google-auth google-cloud-bigquery "google-cloud-aiplatform[agent_engines]"

uv crea un entorno aislado de Python para este codelab, por lo que no necesitas activar nada. Agrega el prefijo uv run a los comandos de Python.

El paquete google-adk incluye la herramienta de CLI de adk que usarás para probar e implementar el agente. adk deploy usa google-cloud-aiplatform para crear tu agente en Agent Runtime, y google-cloud-bigquery es la biblioteca cliente detrás de las herramientas de BigQuery del ADK.

3. Crea el agente

En la carpeta ~/adk-deploy-scale, crea el directorio del agente. Ejecuta todos los comandos posteriores desde ~/adk-deploy-scale (el elemento superior de data_science_agent/):

mkdir data_science_agent

Luego, ejecuta el siguiente comando para crear data_science_agent/.env con tu proyecto, la región en la que implementarás el agente y la configuración del agente implementado. adk deploy lee este archivo, por lo que estos parámetros de configuración seguirán funcionando si abres una terminal nueva.

cat > ~/adk-deploy-scale/data_science_agent/.env <<EOF
GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_ENTERPRISE=True
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
EOF

• GOOGLE_CLOUD_PROJECT y GOOGLE_CLOUD_LOCATION: Tu ID del proyecto (completado desde gcloud) y la región en la que se ejecuta el agente
• GOOGLE_GENAI_USE_ENTERPRISE: Tiene llamadas al ADK a través de Gemini en tu proyecto de Google Cloud
• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT: Registra las entradas de instrucciones completas y las respuestas del agente, lo que resulta útil para la depuración.

El parámetro de configuración OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT registra todo el contenido de las instrucciones del usuario y las respuestas del agente en Cloud Logging. Esto es útil para la depuración, pero puede capturar datos sensibles o IIP. En producción, establece este parámetro en false o asegúrate de tener políticas de manejo de datos adecuadas.

La estructura de directorio final se verá de la siguiente manera:

adk-deploy-scale/
  data_science_agent/
    .env
    __init__.py
    agent.py
    requirements.txt    # created in the Deploy step

Ahora crearás __init__.py y agent.py, y, luego, agregarás requirements.txt en el paso Implementar.

Crea data_science_agent/__init__.py. Este archivo es necesario para que el ADK pueda descubrir y cargar tu agente:

from . import agent  # noqa: F401 — required by `adk eval` and `adk web`

Crea data_science_agent/agent.py:

Este agente se conecta a BigQuery para la extracción de datos y conserva las sesiones en Memory Bank.

La memoria se activa automáticamente cuando se implementa. Agent Runtime establece la variable de entorno GOOGLE_CLOUD_AGENT_ENGINE_ID, que no está presente cuando se ejecuta de forma local.

from __future__ import annotations

import os

from google.adk.agents import LlmAgent
from google.adk.agents.callback_context import CallbackContext
from google.adk.apps import App
from google.adk.integrations.bigquery import BigQueryCredentialsConfig
from google.adk.integrations.bigquery import BigQueryToolset
from google.adk.models import Gemini
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
from google.genai import types
import google.auth

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
if not PROJECT_ID:
    raise ValueError(
        "GOOGLE_CLOUD_PROJECT environment variable is required. "
        "Add it to data_science_agent/.env: GOOGLE_CLOUD_PROJECT=<your-project-id>"
    )

credentials, _ = google.auth.default()
bq_toolset = BigQueryToolset(credentials_config=BigQueryCredentialsConfig(credentials=credentials))

# GOOGLE_CLOUD_AGENT_ENGINE_ID is set automatically by Agent Runtime.
agent_engine_id = os.getenv("GOOGLE_CLOUD_AGENT_ENGINE_ID")


async def _save_memory(callback_context: CallbackContext) -> None:
    """Persist the session to Memory Bank after each agent run.

    Only activates on Agent Runtime, where Memory Bank is available.
    """
    if agent_engine_id:
        await callback_context.add_session_to_memory()


root_agent = LlmAgent(
    name="data_science_agent",
    model=Gemini(
        model="gemini-3.8-flash",
        # gemini-3.8-flash is served from the global endpoint. The agent
        # itself runs in GOOGLE_CLOUD_LOCATION (us-central1).
        client_kwargs={"location": "global"},
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    instruction=(
        "You are an expert Data Science Agent. "
        "Your goal is to query enterprise BigQuery datasets, analyze the data, "
        "and summarize your findings. "
        f"When executing SQL queries, use project_id `{PROJECT_ID}` as the "
        "billing project unless the user specifies a different one. "
        "Present results clearly with formatted numbers. "
        "Remember user preferences like preferred regions, date ranges, "
        "or analysis formats across conversations."
    ),
    tools=[bq_toolset, PreloadMemoryTool()],
    after_agent_callback=_save_memory,
)

app = App(
    name="data_science_agent",
    root_agent=root_agent,
)

Veamos qué hace este código:

1. BigQueryToolset le proporciona al agente herramientas como execute_sql, list_table_ids y get_table_info. Puede explorar esquemas y consultar cualquier conjunto de datos al que tenga acceso el llamador.
2. PreloadMemoryTool recupera automáticamente las memorias pertinentes antes de cada llamada al LLM buscando en Memory Bank contenido relacionado con el mensaje del usuario. La devolución de llamada _save_memory persiste la sesión en Memory Bank después de cada ejecución del agente, de modo que el agente pueda recordar el contexto en sesiones futuras.
3. App encapsula el agente raíz en una aplicación implementable que Agent Runtime puede entregar. El name debe coincidir con el nombre del directorio (data_science_agent). adk web lo usa para ubicar y cargar el agente.
4. La instrucción le indica al agente que use el proyecto de facturación para las consultas en SQL y que recuerde las preferencias del usuario.
5. Gemini con client_kwargs={"location": "global"} envía llamadas al modelo al extremo global, donde gemini-3.8-flash está disponible. El agente en sí se ejecuta en us-central1: adk deploy establece GOOGLE_CLOUD_LOCATION en el agente implementado en la región en la que realizas la implementación, por lo que la ubicación del modelo se establece en el código.

4. Implementa en Agent Runtime

Crea un archivo requirements.txt en el directorio data_science_agent:

google-adk
google-genai
google-auth
google-cloud-bigquery
python-dotenv
opentelemetry-instrumentation-google-genai
opentelemetry-instrumentation-httpx
opentelemetry-instrumentation-grpc

• google-adk y google-genai: ADK y el cliente de Gemini
• google-auth: Autenticación de Google Cloud
• google-cloud-bigquery: Es la biblioteca cliente de BigQuery que usa BigQueryToolset. El ADK no lo instala de forma predeterminada.
• python-dotenv: Carga el archivo .env durante el inicio.
• Los tres paquetes opentelemetry-instrumentation-* habilitan las funciones de observabilidad que explorarás más adelante. Instrumentan las llamadas al modelo de Gemini y la comunicación interna de gRPC/HTTP para que los registros aparezcan en la pestaña Registros de tu agente.

No agregues google-cloud-aiplatform a tu requirements.txt, aunque lo hayas instalado de forma local. adk deploy lo agrega por ti (junto con la versión del ADK con la que implementas), pero solo cuando tu requirements.txt aún no lo incluye. Si lo declaras tú mismo, es posible que se produzcan conflictos de versiones de paquetes de OpenTelemetry que interrumpan la instrumentación de forma silenciosa, lo que provocará que los seguimientos no aparezcan en la pestaña Traces.

adk deploy también lee el archivo data_science_agent/.env que creaste antes y establece su configuración en el agente implementado.

Implementa el agente. El último argumento data_science_agent es el directorio que contiene el código del agente:

uv run adk deploy agent_engine \
  --project=$(gcloud config get project) \
  --region=us-central1 \
  --display_name="Data Science Agent" \
  --otel_to_cloud \
  data_science_agent

Cerca del inicio, el resultado muestra dos líneas amarillas, Ignoring GOOGLE_CLOUD_PROJECT in .env ... y Ignoring GOOGLE_CLOUD_LOCATION in .env .... Se esperan: Las marcas --project y --region tienen prioridad sobre los mismos valores en .env.

Marcar	Objetivo
--project/--region	Proyecto y región de Google Cloud de destino
--display_name	Nombre legible que se muestra en la consola de Cloud
--otel_to_cloud	Exporta los registros y los seguimientos de OpenTelemetry a Google Cloud y activa la telemetría (GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true) en el agente implementado.

La implementación suele tardar entre 5 y 10 minutos. Cuando se complete, el resultado mostrará el nombre del recurso de tu agente (projects/.../reasoningEngines/) y un vínculo para verlo en la consola de Cloud.

Mientras esperas, revisa la documentación de Memory Bank para obtener más información sobre cómo funciona la memoria entre sesiones.

Si el vínculo que imprimió adk deploy no funciona, abre la página Implementaciones en la consola de Cloud y haz clic en tu agente.

Cuando se implementa en Agent Runtime, se activan automáticamente dos capacidades:

• Memory Bank: adk deploy conecta el agente a Sessions y Memory Bank en su instancia de Agent Runtime. PreloadMemoryTool lee desde Memory Bank y _save_memory persiste las sesiones automáticamente.
• Observabilidad: Cloud Trace captura los pasos de razonamiento, las llamadas a herramientas y las latencias del agente.

5. Otorga permisos de BigQuery

Debes otorgar acceso a BigQuery al agente de servicio de Agent Runtime (el agente de servicio de AI Platform Reasoning Engine). Cuando se implementa, el agente se ejecuta como esta cuenta de servicio administrada por Google (no con tus credenciales personales), por lo que necesita permisos explícitos para ejecutar consultas SQL.

PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get project) \
  --format='value(projectNumber)')

SA="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"

# Required to execute SQL queries
gcloud projects add-iam-policy-binding $(gcloud config get project) \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.jobUser"

# Required to read table metadata and data
gcloud projects add-iam-policy-binding $(gcloud config get project) \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.dataViewer"

Cada comando imprime Updated IAM policy for project [...] cuando se ejecuta correctamente.

Si omites este paso, el agente implementado devolverá errores 403 cuando ejecute consultas en SQL. El rol bigquery.jobUser es necesario en el proyecto de facturación (tu proyecto), no en el proyecto de datos.

Nota: bigquery.dataViewer otorga acceso de lectura a todos los conjuntos de datos de tu proyecto. Para el uso en producción, considera otorgar este rol a nivel del conjunto de datos.

6. Prueba el agente implementado

Abre la página Implementaciones en la consola de Google Cloud. Haz clic en el agente implementado y, luego, en la pestaña Zona de pruebas.

Cada consulta puede tardar entre 10 y 30 segundos en completarse, ya que el agente razona, llama a herramientas y devuelve resultados.

Prueba las capacidades de BigQuery:

1. "Enumera las tablas en bigquery-public-data.hacker_news"
   • Esperado: El agente llama a list_table_ids y devuelve nombres de tablas, incluido full.
2. "Busca la cantidad de publicaciones por año en bigquery-public-data.hacker_news.full".
   • Esperado: El agente llama a execute_sql con una consulta en SQL y devuelve una tabla de años y recuentos de publicaciones.
3. "¿Cuál fue el cambio porcentual interanual en las publicaciones?"
   • Esperado: El agente llama a execute_sql con una consulta en SQL que calcula el cambio porcentual y devuelve los resultados.

7. Cómo probar la persistencia de la memoria

En Playground, enséñale al agente una preferencia:

1. "Recuerda que mi conjunto de datos favorito es bigquery-public-data.hacker_news".
2. "¿Qué tablas tiene?"

Espera unos segundos para que persista la memoria (la devolución de llamada _save_memory se ejecuta después de que responde el agente).

Ahora, inicia una sesión nueva haciendo clic en Nueva sesión en Playground y, luego, pregunta lo siguiente:

3. "¿Cuál es mi conjunto de datos favorito?"

El agente debe recordar bigquery-public-data.hacker_news, aunque se trate de una sesión completamente nueva sin historial de conversaciones. Esto funciona por los siguientes motivos:

• _save_memory persiste cada sesión en Memory Bank a través de callback_context.add_session_to_memory()
• PreloadMemoryTool recupera recuerdos pertinentes antes de cada llamada al LLM
• Memory Bank relaciona el contenido de forma semántica, no solo por palabras clave

Si el agente no recuerda tu preferencia, espera 10 segundos y vuelve a intentarlo en otra sesión nueva. La persistencia de la memoria es asíncrona y puede tardar un momento en completarse.

8. Explora la observabilidad

En la consola de Cloud, navega al agente implementado y haz clic en la pestaña Registros.

Deberías ver una tabla de sesiones que enumera las sesiones de las consultas de prueba que ejecutaste en los pasos anteriores. En la tabla, se muestran las métricas de resumen de cada sesión: duración promedio, llamadas al modelo, llamadas a herramientas, uso de tokens y errores.

Haz clic en una sesión para inspeccionar los detalles del registro, incluidos los siguientes:

• Un grafo acíclico dirigido (DAG) de sus intervalos, que muestra el desglose paso a paso del razonamiento del agente, las llamadas a herramientas (consultas de BigQuery) y las latencias
• Entradas y salidas para cada intervalo (habilitadas a través de la variable de entorno OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT en .env)
• Atributos de metadatos, como IDs de intervalo, IDs de seguimiento y sincronización

También puedes cambiar a la vista de intervalo (el botón de activación se encuentra en la parte superior) para ver los intervalos individuales en todas las sesiones.

Es posible que los registros tarden entre 1 y 2 minutos en aparecer después de que se complete una búsqueda. Si aún no ves ningún registro, espera un momento y actualiza la página.

Cómo funciona el rastreo

Cuando realizas la implementación con --otel_to_cloud, adk deploy compila un contenedor que ejecuta el servidor de la API del ADK con OpenTelemetry activado. En Agent Runtime, el servidor inicializa una canalización de OpenTelemetry que hace lo siguiente:

1. Crea un TracerProvider con un exportador de OTLP que envía intervalos a telemetry.googleapis.com
2. Registra los propios intervalos del ADK para las ejecuciones del agente, las llamadas al modelo y las llamadas a herramientas, y usa los tres paquetes de instrumentación de tu requirements.txt para agregar intervalos de bibliotecas clave (Gemini, httpx, gRPC).
3. Agrupa y exporta intervalos a la API de Telemetry, donde la pestaña Traces los lee.

El contenedor implementado incluye el ADK y el SDK y el exportador de OpenTelemetry, pero no incluye los paquetes de instrumentación. Por eso, tu requirements.txt enumera los tres. Sin ellos, el servidor de la API del ADK registra una advertencia y omite esos intervalos.

Solución de problemas

Si no aparecen seguimientos después de unos minutos, haz lo siguiente:

1. Verifica que la API de Telemetry esté habilitada: La habilitaste en el paso de configuración. Verificar con: gcloud services list --enabled --project=$(gcloud config get project) | grep telemetry
2. Verifica si hay advertencias en Cloud Logging: Ve a Logging > Explorador de registros y busca "proceeding without" o "GoogleGenAiSdkInstrumentor". Una advertencia que nombra una instrumentación (GenAI, HTTPX o gRPC) significa que falta el paquete opentelemetry-instrumentation-* coincidente en tu requirements.txt.
3. No agregues google-cloud-aiplatform a tu requirements.txt. adk deploy lo agrega automáticamente. Si lo declaras por tu cuenta, es posible que se generen conflictos de paquetes de OpenTelemetry y que la instrumentación se interrumpa de forma silenciosa.

9. Limpieza

Para evitar cargos continuos, borra los recursos que creaste durante este codelab.

Borra el agente implementado de la página Implementaciones en la consola de Cloud. Selecciona tu agente y haz clic en Borrar.

Las consultas de BigQuery en este codelab usaron conjuntos de datos públicos, que no generan cargos de almacenamiento. Los roles de IAM que otorgaste permanecen en el proyecto, pero no tienen impacto en el costo.

Si creaste un proyecto específicamente para este codelab, puedes borrar todo el proyecto:

gcloud projects delete <YOUR_PROJECT_ID>

De manera opcional, limpia tu entorno local:

cd ~
rm -rf ~/adk-deploy-scale

10. Felicitaciones

Creaste un agente de ciencia de datos con estado y lo implementaste en Agent Runtime.

Qué aprendiste

• Cómo crear un agente del ADK con BigQueryToolset para acceder a datos reales
• Cómo habilitar la memoria persistente con Memory Bank usando PreloadMemoryTool y after_agent_callback
• Cómo otorgar permisos de IAM a la cuenta de servicio del agente implementado
• Cómo realizar la implementación en Agent Runtime y habilitar la observabilidad con Cloud Trace

Próximos pasos

• Consulta tus propios conjuntos de datos privados de BigQuery otorgando acceso a tus datos al agente de servicio de Agent Runtime
• Agrega Ejecución de código para ejecutar análisis de Python en una zona de pruebas segura
• Configura paneles de observabilidad de Cloud Trace para supervisar tu agente en producción
• Publica los resultados en Google Workspace con las herramientas de MCP

Documentos de referencia

• Documentación del ADK
• Documentación de Agent Runtime
• Documentación de Memory Bank
• Guía de implementación de Agent Runtime