Crea agentes de IA con el ADK: agente de analista de datos

1. Antes de comenzar

LEA ESTA INFORMACIÓN:

En este instructivo, se requiere un proyecto de Google Cloud con una cuenta de facturación activa.

Para los asistentes al taller presencial: Sigue las instrucciones específicas de configuración y facturación que te proporcione el instructor.

Para usuarios de autoaprendizaje: Sigue estos pasos para canjear una prueba:

• Abre una ventana de incógnito en tu navegador.
• Navega a este portal de canje.
• Accede con tu cuenta personal de Gmail.
• Sigue las instrucciones paso a paso del portal.

Te damos la bienvenida a la cuarta parte de la serie "Crea agentes de IA con el ADK". En este codelab práctico, combinarás lo que aprendiste en sesiones anteriores para crear un agente de analista de datos. Este agente se diseñará para analizar datos, generar estadísticas valiosas y automatizar aspectos clave del flujo de trabajo de análisis de datos.

Le permitirás a tu agente explorar los archivos subidos y conectarlo a bases de datos de nivel empresarial, como Google Cloud BigQuery, con las potentes herramientas incluidas en el ADK.

También puedes acceder a este codelab a través de la siguiente URL acortada: goo.gle/adk-data-analyst

Requisitos previos

• Comprensión básica de los conceptos de IA generativa
• Dominio básico de la programación en Python y comodidad para usar la línea de comandos
• Conocimiento de los conceptos de los codelabs anteriores de esta serie: "Los fundamentos" y "Potenciación con herramientas"

Qué aprenderás

• Cómo compilar un agente de analista de datos funcional con el framework del ADK
• Son métodos para permitir que un agente analice datos de documentos subidos.
• Cómo conectar tu agente a una base de datos de BigQuery para realizar análisis de datos a nivel empresarial
• Técnicas para definir la lógica central de tu agente, incluidos su propósito y sus instrucciones

Requisitos

• Una computadora que funcione y una conexión a Internet confiable
• Un navegador, como Chrome, para acceder a la consola de Google Cloud
• Una mente curiosa y ganas de aprender

2. Introducción

En el mundo actual impulsado por los datos, la capacidad de analizar grandes cantidades de información de forma rápida y precisa es más importante que nunca. Sin embargo, el proceso de extracción de estadísticas significativas a menudo requiere una profunda experiencia técnica en áreas como SQL, lo que crea un cuello de botella que puede ralentizar la toma de decisiones. ¿Qué pasaría si pudieras superar esta brecha e interactuar con conjuntos de datos complejos con la misma facilidad con la que mantienes una conversación?

Aquí es donde los agentes de IA están cambiando las reglas del juego. Al actuar como una interfaz inteligente entre tú y tus datos, los agentes de IA pueden comprender preguntas en lenguaje natural, traducirlas en consultas técnicas y proporcionar estadísticas prácticas en segundos.

En este codelab, te adentrarás en el futuro del análisis de datos creando un agente de analista de datos práctico con el Kit de desarrollo de agentes (ADK). Comenzaremos por crear un agente básico y, luego, mejoraremos sus capacidades de forma progresiva. Primero, le enseñarás a tu agente a analizar datos no estructurados de los documentos subidos. Luego, lo conectarás a un potente almacén de datos de nivel empresarial, Google Cloud BigQuery, para consultar y analizar un conjunto de datos de atención médica a gran escala y del mundo real.

Al final de este instructivo, no solo tendrás un asistente de IA funcional, sino también una comprensión sólida de cómo crear agentes que puedan automatizar tareas de datos rutinarias, acelerar el análisis y democratizar el acceso a estadísticas críticas para ti y tu equipo.

3. Configura los servicios de Google Cloud

Crea un proyecto de Google Cloud

Para mantener todo el trabajo de este codelab organizado y separado de otros proyectos, comenzarás por crear un proyecto nuevo de Google Cloud.

1. Navega a console.cloud.google.com/projectcreate.
2. Ingresa la información requerida:

• Nombre del proyecto: Puedes ingresar el nombre que desees (p. ej., genai-workshop).
• Ubicación: Déjala como Sin organización.
• Cuenta de facturación: Si aparece esta opción, selecciona "Cuenta de facturación de prueba de Google Cloud Platform" o tu propia cuenta de facturación si lo prefieres. Si no ves esta opción, puedes continuar con el siguiente paso.

3. Copia el ID del proyecto generado, ya que lo necesitarás más adelante.

4. Si todo está bien, haz clic en el botón Crear.

Configura Cloud Shell

Una vez que se haya creado tu proyecto correctamente, sigue estos pasos para configurar Cloud Shell.

1. Inicia Cloud Shell

Navega a shell.cloud.google.com. Si aparece una ventana emergente que solicita autorización, haz clic en Autorizar.

2. Configura el ID del proyecto

Reemplaza replace-with-your-project-id por el ID del proyecto real del paso de creación del proyecto anterior. Ejecuta el siguiente comando en la terminal de Cloud Shell para establecer el ID del proyecto correcto.

gcloud config set project replace-with-your-project-id

Ahora deberías ver que se seleccionó el proyecto correcto en la terminal de Cloud Shell. El ID del proyecto seleccionado se destaca en amarillo.

3. Habilita las APIs obligatorias

Para usar los servicios de Google Cloud, primero debes activar sus respectivas APIs para tu proyecto. Ejecuta los siguientes comandos en la terminal de Cloud Shell para habilitar los servicios de este codelab:

gcloud services enable \
 aiplatform.googleapis.com \
 bigquery.googleapis.com

Si la operación se realizó correctamente, verás el mensaje Operation/... finished successfully impreso en la terminal.

4. Crea un entorno virtual de Python.

A continuación, crea un entorno aislado de Python para administrar las dependencias de tu proyecto.

Nota: Usaremos uv para crear nuestro entorno virtual en lugar del paquete venv estándar. Es un administrador de proyectos y paquetes de Python increíblemente rápido escrito en Rust.

Si te interesa, puedes obtener más información en la documentación oficial sobre uv.

1. Crea el directorio del proyecto y navega a él:

mkdir -p ai-agents-adk && cd ai-agents-adk

2. Crea y activa un entorno virtual:

uv venv --python 3.12
source .venv/bin/activate

Verás el prefijo (ai-agents-adk) en el prompt de la terminal, lo que indica que el entorno virtual está activo.

3. Página de instalación del ADK

uv pip install google-adk --no-cache

Nota: Si cierras el terminal por accidente, deberás ir a la carpeta ai-agents-adk y volver a ejecutar source .venv/bin/activate.

5. Crea un agente inicial

Una vez que tu entorno esté listo, es hora de crear tu agente de IA con un simple comando de ADK.

1. Crear un agente

En tu terminal, ejecuta el siguiente comando:

adk create data_analyst_agent

2. Configura tu agente

Se te pedirá que configures tu agente. Realice las siguientes selecciones:

• Elige un modelo: Selecciona 1. gemini-2.5-flash.
• Elige un backend: Selecciona 2. Vertex AI.
• Ingresa el ID del proyecto de Google Cloud: Presiona Intro para confirmar el ID del proyecto correcto.
• Enter Google Cloud region: Presiona Intro para usar el valor predeterminado us-central1.

3. Inicia el servidor web de desarrollo

Una vez que se cree el agente, ejecuta el siguiente comando para iniciar el servidor web de desarrollo:

adk web

Puedes presionar Ctrl y hacer clic o presionar Cmd y hacer clic en el vínculo (es decir, http://localhost:8000) en la terminal o puedes

• Haz clic en el botón Vista previa en la Web.
• Selecciona Cambiar puerto.
• Ingresa el número de puerto (p. ej., 8000).
• Haz clic en Cambiar y obtener vista previa.

Luego, verás la IU similar a una aplicación de chat en tu navegador.

4. Chatea con tu agente

¡Chatea con tu agente a través de esta interfaz! Di algo como "Hola, ¿qué puedes hacer?".

6. Analiza datos de un documento

En esta sección, subirás un documento al agente y le harás preguntas sobre su contenido.

1. Resume el documento

Sigue estos pasos para obtener un resumen del documento:

1. Descarga el archivo sobre la estrategia de atención médica de Google.
2. Haz clic en el botón Subir archivo en la IU de tu agente y selecciona el archivo que acabas de descargar.
3. En la interfaz de chat, pídele al agente que resuma el archivo: "Dame un resumen de este archivo".
4. Presiona Intro.

Deberías recibir un resumen conciso del contenido del documento.

2. Haz preguntas más detalladas

Ahora, intenta hacer preguntas más detalladas para profundizar en el documento:

• ¿Cuáles son las principales enfermedades a las que Google apunta actualmente con sus iniciativas de IA y datos?
• ¿Cómo planea Google mejorar la interoperabilidad de los datos de atención médica y desglosar los silos de datos?
• ¿Cómo se utiliza Google Cloud para ayudar a las empresas y los investigadores del sector de la salud?
• ¿Qué nuevas áreas de enfermedades podría explorar Google a continuación (p.ej., EPOC, cáncer, salud mental)?

3. Haz preguntas adicionales

También puedes hacer preguntas de seguimiento, como averiguar el número de referencia de la página para realizar una investigación más a fondo:

• ¿Dónde viste información relacionada con la diabetes?
• Dirígeme a las páginas pertinentes sobre enfermedades.
• ¿Dónde están los gráficos interesantes que debería consultar?

Desafío: Busca un documento propio que quieras que analice el agente y súbelo. Hazle preguntas al agente sobre su contenido.

7. Combina las estadísticas del documento con la búsqueda web en vivo

Ahora el agente es un experto en el documento, pero un analista potente también necesita acceso a información externa y actual. Démosle a nuestro agente la capacidad de buscar en la Web.

1. En la terminal de Cloud Shell, presiona Ctrl + C para detener el servidor web.
2. Abre el archivo data_analyst_agent/agent.py en el editor de Cloud Shell ejecutando este comando:

cloudshell edit data_analyst_agent/agent.py

3. Modifica el archivo para importar y agregar la herramienta google_search:

from google.adk.agents.llm_agent import Agent
from google.adk.tools import google_search

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction="""
        First, check the uploaded files for an answer. 
        If the information is not in the files, use your tools to search the web. 
        Answer user questions to the best of your ability.
    """,
    tools=[
        google_search
    ]
)

NOTA: También se actualizó la instrucción para guiar al agente sobre cuándo usar la herramienta de Búsqueda de Google.

4. Guarda el archivo y reinicia el servidor web en tu terminal escribiendo adk web.
5. En la IU del agente, vuelve a subir el archivo GoogleHealthStrategy.pdf.
6. Ahora, haz una pregunta que requiera el contexto del documento y la información externa:

The document discusses Google's strategy in healthcare. What are three other major tech companies that are also investing heavily in healthcare AI, and what are their primary focus areas?

Ahora, el agente sintetizará información del documento y de una búsqueda en vivo de Google para brindarte una respuesta integral. Puedes intentar hacer algunas preguntas:

• El documento menciona el uso de la IA para la retinopatía diabética. ¿Cuáles son algunas de las tecnologías más recientes aprobadas por la FDA en esta área que se anunciaron en el último año?
• El archivo menciona asociaciones. ¿Puedes encontrar artículos de noticias o comunicados de prensa recientes sobre las colaboraciones más recientes de Google en el sector de la atención médica?

Desafío: Intenta hacer preguntas similares sobre un documento propio. Algo que use un documento local y los resultados de Internet.

8. Analiza datos de atención médica con BigQuery

Subir documentos individuales no es escalable. En una situación del mundo real, los datos residen en sistemas empresariales como Google Cloud BigQuery.

Actualmente, los desarrolladores que crean aplicaciones basadas en agentes a menudo deben crear y mantener sus propias herramientas personalizadas. Este proceso manual es lento, riesgoso y genera una sobrecarga significativa. Obliga a los desarrolladores a encargarse de todo, desde la autenticación hasta el control de errores, en lugar de enfocarse en la innovación.

El Kit de desarrollo de agentes (ADK) incluye herramientas propias para la interacción con BigQuery. Para este análisis en particular, usaremos el conjunto de datos de utilización de Medicare disponible públicamente que proporcionan los Centros de Servicios de Medicare y Medicaid (CMS).

Primero, conectemos nuestro agente a un conjunto de datos masivo de atención médica pública.

1. En la terminal de Cloud Shell, presiona Ctrl + C para detener el servidor web.
2. Abre el archivo data_analyst_agent/agent.py en el editor de Cloud Shell ejecutando este comando en la terminal:

cloudshell edit data_analyst_agent/agent.py

3. Reemplaza todo el contenido del archivo por el siguiente código para configurar el potente BigQueryToolset:

import google.auth
from google.adk.agents.llm_agent import Agent
from google.adk.tools import google_search
from google.adk.tools.agent_tool import AgentTool
from google.adk.tools.bigquery import (
    BigQueryToolset,
    BigQueryCredentialsConfig
)
from google.adk.tools.bigquery.config import (
    BigQueryToolConfig,
    WriteMode
)

# Automatically get credentials from the gcloud environment
application_default_credentials, _ = google.auth.default()
credentials_config = BigQueryCredentialsConfig(
    credentials=application_default_credentials
)

# Configure the BigQuery tool
tool_config = BigQueryToolConfig(
    write_mode=WriteMode.ALLOWED,
    application_name='data_analyst_agent'
)

# Create the toolset with the specified configurations
bigquery_toolset = BigQueryToolset(
    credentials_config=credentials_config, bigquery_tool_config=tool_config
)

# Create an agent with google search tool as a search specialist
google_search_agent = Agent(
    model='gemini-2.5-flash',
    name='google_search_agent',
    description='A search agent that uses google search to get latest information about current events, weather, or business hours.',
    instruction='Use google search to answer user questions about real-time, logistical information.',
    tools=[google_search],
)

# Define the final agent with its instructions and tools
root_agent = Agent(
    model="gemini-2.5-flash",
    name="bigquery_agent",
    description=(
        "Agent to answer questions about BigQuery data and execute SQL queries."
    ),
    instruction="""
        You are an expert data analyst agent with access to BigQuery tools.
        When a user asks about a dataset, first use your tools to understand its schema.
        Then, use this knowledge to construct and execute SQL queries to answer the user's questions.
        Always confirm with the user if their question is ambiguous (e.g., for which year?).
    """,
    tools=[
        AgentTool(google_search_agent),
        bigquery_toolset
    ],
)

4. Guarda el archivo y reinicia el servidor web en tu terminal escribiendo adk web.
5. Ahora puedes pedirle a tu agente que analice el conjunto de datos públicos de Medicare. Comienza por explorar los datos:

Look into the cms_medicare dataset in the bigquery-public-data project. What can you tell me about it?

El agente usará sus herramientas para inspeccionar el conjunto de datos y proporcionar una lista de las tablas disponibles. A partir de ahí, puedes profundizar con preguntas analíticas específicas. El agente puede hacer preguntas aclaratorias para asegurarse de que sus consultas sean precisas.

Para algunas preguntas, deberás proporcionar el ID del proyecto al agente para que pueda usarlo y crear una consulta. Por ejemplo:

Estos son algunos ejemplos de instrucciones analíticas que puedes probar:

• Según la tabla inpatient_charges_2015, ¿cuáles son los 5 procedimientos principales (definiciones de DRG) según la cantidad total de altas?
• ¿Cuál es el pago total promedio por "REEMPLAZO DE ARTICULACIÓN PRINCIPAL" en California (CA)?
• ¿Qué estado tiene los cargos cubiertos promedio más altos para ese mismo procedimiento?

Con esto concluye este codelab. Solo exploraste la superficie de lo que puedes lograr con los agentes de datos potenciados por sistemas de datos empresariales. No dudes en hacerle a tu agente las preguntas que tengas sobre el conjunto de datos cms_medicare.

Desafío: Busca otro conjunto de datos públicos en BigQuery y usa tu agente para explorarlo. También puedes crear tu propio conjunto de datos con tus propios datos y analizarlos de forma privada.

9. Realiza una limpieza (opcional)

Nota: Si planeas continuar con la serie, NO NECESITAS realizar este paso. Si asistes a este codelab en persona con un instructor, él te brindará más instrucciones sobre qué hacer.

Para evitar que se apliquen cargos en el futuro, puedes borrar los recursos que usaste en este codelab.

1. Detén el agente

En la terminal de Cloud Shell, presiona Ctrl + C para detener el proceso de adk web.

2. Borra los archivos del proyecto

Para quitar el código del agente de tu entorno de Cloud Shell, ejecuta lo siguiente en la terminal:

cd ~ && rm -rf ai-agents-adk

3. Inhabilita las APIs

Para inhabilitar las APIs que habilitaste antes, ejecuta lo siguiente en la terminal:

gcloud services disable \
 aiplatform.googleapis.com \
 bigquery.googleapis.com

4. Cierra el proyecto

Si quieres borrar todo el proyecto de Google Cloud, sigue la guía para cerrar proyectos.

10. Conclusión

¡Felicitaciones! Creaste correctamente un agente de analista de datos con el framework del Kit de desarrollo de agentes (ADK). Este agente es capaz de analizar datos de diversas fuentes, generar estadísticas y ayudar a automatizar partes del flujo de trabajo de análisis de datos.

Para continuar tu recorrido de aprendizaje, explora estos recursos:

• Lee la entrada de blog oficial: Anunciamos el conjunto de herramientas de BigQuery para agentes de IA
• Explora la documentación: Visita la documentación oficial del Kit de desarrollo de agentes (ADK) para conocer las nuevas funciones y las guías avanzadas.
• Explora el código: Consulta el repositorio de GitHub del ADK.
• Descubre más datos: Explora el catálogo de conjuntos de datos públicos de Google Cloud.