Agente de ciencia de datos con estado en Agent Engine

1. Descripción general

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

El agente usa 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. Esto funciona de forma local y cuando se implementa.
• Memory Bank: Cuando se implementa, el agente recuerda las preferencias y el contexto del usuario en las 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 de ADK con BigQueryToolset para el acceso a datos reales
• Cómo configurar Memory Bank para la persistencia entre sesiones
• Cómo implementar tu agente en Agent Engine con adk deploy
• Cómo otorgar permisos de IAM para la cuenta de servicio del agente implementado
• Cómo probar la persistencia de la memoria y la observabilidad

Requisitos

• Un proyecto de Google Cloud con la facturación habilitada.
• SDK de Google Cloud (gcloud CLI)
• Un navegador web, como Chrome
• uv (administrador de paquetes de Python)
• Python 3.12+ (instalado automáticamente por uv si es necesario)

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

Este codelab está destinado a desarrolladores de nivel intermedio que tengan cierta familiaridad con Python y Google Cloud.

Este codelab toma aproximadamente 30 minutos en completarse (incluidos 5 a 10 minutos para la implementación).

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

2. Configura tu entorno

Cómo crear un proyecto de Google Cloud

1. En la consola de Google Cloud, en la página del selector de proyectos, 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.

Configura las variables de entorno

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True

Habilita las APIs

gcloud services enable \
  aiplatform.googleapis.com \
  bigquery.googleapis.com \
  telemetry.googleapis.com \
  --project=$GOOGLE_CLOUD_PROJECT

• API de AI Platform (aiplatform.googleapis.com): Hosting de Agent Engine
• API de BigQuery (bigquery.googleapis.com): Consultas de SQL en conjuntos de datos públicos y privados
• API de Telemetry (telemetry.googleapis.com): Seguimientos 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 los pasos posteriores, espera un momento y vuelve a intentarlo.

Crea un entorno virtual y, luego, instala el ADK

uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install google-adk google-auth

El paquete google-adk incluye la herramienta de CLI adk que usarás para probar y, luego, implementar el agente.

3. Crea el agente

Crea un directorio de proyecto de agente nuevo. Todos los comandos posteriores deben ejecutarse desde este directorio de trabajo (el superior de data_science_agent/):

mkdir data_science_agent

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

./
  data_science_agent/
    __init__.py
    agent.py
    requirements.txt    # created in the Deploy step
    .env                # created in the Deploy step

Ahora crearás __init__.py y agent.py, y, luego, agregarás requirements.txt y .env en el paso de implementación.

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. El entorno de ejecución de Agent Engine 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.tools.bigquery import BigQueryCredentialsConfig
from google.adk.tools.bigquery import BigQueryToolset
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
import google.auth

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
if not PROJECT_ID:
    raise ValueError(
        "GOOGLE_CLOUD_PROJECT environment variable is required. "
        "Set it with: export 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 the Agent Engine 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 Engine 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-2.5-pro",
    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 paso a paso:

1. BigQueryToolset 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 a LLM buscando en Memory Bank contenido relacionado con el mensaje del usuario. La devolución de llamada _save_memory conserva 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 une el agente raíz en una aplicación implementable que Agent Engine 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 de SQL y que recuerde las preferencias del usuario.

4. Implementa en Agent Engine

Crea un archivo requirements.txt en el directorio data_science_agent:

google-adk>=1.26.0
google-genai>=1.27.0
google-auth>=2.0.0
python-dotenv>=1.1.0
opentelemetry-instrumentation-fastapi
opentelemetry-instrumentation-google-genai
opentelemetry-instrumentation-httpx
opentelemetry-instrumentation-grpc

• google-adk y google-genai: El framework de ADK y el cliente de Gemini
• google-auth: Autenticación de Google Cloud
• python-dotenv: Carga el archivo .env al inicio
• Los cuatro paquetes opentelemetry-instrumentation-* habilitan las funciones de observabilidad que explorarás más adelante. Instrumentan las solicitudes HTTP de FastAPI, las llamadas al modelo de Gemini y la comunicación interna de gRPC/HTTP para que los seguimientos aparezcan en la pestaña Seguimientos de Agent Engine.

No agregues google-cloud-aiplatform[agent-engines] a tu requirements.txt. La CLI de implementación del ADK agrega automáticamente esta dependencia durante la implementación. Si la vuelves a declarar con una versión diferente, se pueden producir conflictos de versión del paquete de OpenTelemetry que interrumpan la instrumentación de forma silenciosa, lo que hace que los seguimientos no aparezcan en la pestaña Seguimientos.

Crea un archivo .env en el directorio data_science_agent para habilitar la telemetría en el agente implementado:

GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

• GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY: Activa la canalización de OpenTelemetry en el entorno de ejecución de Agent Engine.
• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT: Registra las entradas de instrucciones completas y las respuestas del agente, lo que es útil para la depuración.

El parámetro 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, configúralo como false o asegúrate de tener políticas de manejo de datos adecuadas.

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

adk deploy agent_engine \
  --project=$GOOGLE_CLOUD_PROJECT \
  --region=$GOOGLE_CLOUD_LOCATION \
  --display_name="Data Science Agent" \
  --trace_to_cloud \
  --otel_to_cloud \
  data_science_agent

Marcar	Objetivo
--project / --region	Proyecto y región de Google Cloud de destino
--display_name	Nombre legible por humanos que se muestra en la consola de Cloud
--trace_to_cloud	Habilita el exportador de Cloud Trace para los intervalos del agente
--otel_to_cloud	Habilita la canalización de instrumentación de OpenTelemetry

La implementación suele tardar entre 5 y 10 minutos. Cuando se complete, verás el siguiente mensaje: Created agent engine: projects/.../reasoningEngines/

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

Es posible que la URL que imprime adk deploy sea incorrecta. Si el vínculo no funciona, navega a la página de Agent Engine en la consola de Cloud y haz clic en tu agente.

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

• Memory Bank: PreloadMemoryTool se conecta a Memory Bank de Agent Engine y _save_memory conserva 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 a la cuenta de servicio de Agent Engine. Cuando se implementa, el agente se ejecuta como una cuenta de servicio administrada por Google (no tus credenciales personales), por lo que necesita permisos explícitos para ejecutar consultas de SQL.

PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_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 $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.jobUser"

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

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

Si omites este paso, el agente implementado mostrará errores 403 cuando ejecute consultas de 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 de Agent Engine en la consola de Google Cloud. Haz clic en tu agente implementado para abrir Agent Engine Playground.

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

Prueba las capacidades de BigQuery:

1. "List the tables in bigquery-public-data.hacker_news"
   • Resultado esperado: El agente llama a list_table_ids y muestra nombres de tablas, incluido full.
2. "Find the number of posts per year in bigquery-public-data.hacker_news.full"
   • Resultado esperado: El agente llama a execute_sql con una consulta de SQL y muestra una tabla de años y recuentos de publicaciones.
3. "What was the year-over-year percentage change in posts?"
   • Resultado esperado: El agente llama a execute_sql con una consulta en SQL que calcula el cambio porcentual y muestra los resultados.

7. Prueba la persistencia de la memoria

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

1. "Remember that my favorite dataset is bigquery-public-data.hacker_news"
2. "What tables does it have?"

Espera unos segundos para que la memoria persista (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 el botón "+ New Session" en la barra lateral de Playground y, luego, pregunta lo siguiente:

3. "What is my favorite dataset?"

El agente debería recordar bigquery-public-data.hacker_news, aunque esta sea una sesión nueva sin historial de conversaciones. Esto funciona por los siguientes motivos:

• _save_memory conserva cada sesión en Memory Bank a través de callback_context.add_session_to_memory().
• PreloadMemoryTool recupera las memorias pertinentes antes de cada llamada a LLM.
• Memory Bank hace coincidir el contenido de forma semántica, no solo por palabra 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 hasta tu agente implementado y haz clic en la pestaña Seguimientos.

Deberías ver una tabla de sesiones en la que se enumeran 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 cualquier error.

Haz clic en una sesión para inspeccionar los detalles de su seguimiento, incluidos los siguientes:

• Un gráfico 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 (alternar en la parte superior) para ver intervalos individuales en todas las sesiones.

Los seguimientos pueden tardar entre 1 y 2 minutos en aparecer después de que se completa una consulta. Si aún no ves ningún seguimiento, espera un momento y actualiza la página.

Cómo funciona el seguimiento

Cuando implementas con --trace_to_cloud y --otel_to_cloud, el entorno de ejecución de Agent Engine 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. Usa los cuatro paquetes de instrumentación de tu requirements.txt para capturar intervalos de bibliotecas clave (FastAPI, Gemini, httpx, gRPC). El entorno de ejecución instrumenta google-genai de forma explícita, mientras que los demás contribuyen a través del descubrimiento automático de OpenTelemetry.
3. Agrupa y exporta intervalos a la API de Telemetry, donde la pestaña Seguimientos los lee.

La imagen base de Agent Engine proporciona el SDK y el exportador de OpenTelemetry, pero no incluye los paquetes de instrumentación. Por este motivo, tu requirements.txt debe enumerar los cuatro. Sin ellos, no se crean intervalos y no aparecen seguimientos.

Solución de problemas

Si no aparece ningún seguimiento 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=$GOOGLE_CLOUD_PROJECT | grep telemetry
2. Verifica si hay advertencias en Cloud Logging : Ve a Logging > Explorador de registros y busca "telemetry enabled but proceeding without". Si ves una advertencia sobre la instrumentación de GenAI, falta opentelemetry-instrumentation-google-genai en tu requirements.txt.
3. No agregues google-cloud-aiplatform[agent-engines] a tu requirements.txt. La CLI de implementación del ADK la agrega automáticamente. Si la vuelves a declarar con una versión diferente, se pueden producir conflictos de paquetes de OpenTelemetry y se puede interrumpir la instrumentación de forma silenciosa.

9. Limpieza

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

Borra el agente implementado de la página de Agent Engine 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 los costos.

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

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

De forma opcional, limpia tu entorno local:

deactivate
rm -rf .venv data_science_agent

10. Felicitaciones

Compilaste un agente de ciencia de datos con estado y lo implementaste en Agent Engine.

Qué aprendiste

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

Próximos pasos

• Consulta tus propios conjuntos de datos privados de BigQuery otorgando acceso a tus datos a la cuenta de servicio de Agent Engine.
• Agrega la ejecución de código para ejecutar el 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 Engine
• Documentación de Memory Bank
• Guía de implementación de Agent Engine