¡Bienvenido a la primera parte de la serie "Construyendo Agentes de IA con ADK"! En esta serie de codelabs prácticos, te embarcarás en un emocionante viaje para crear tu propio agente de IA inteligente utilizando el Agent Development Kit (ADK) de Google.

Comenzaremos con lo esencial, guiándote a través de la configuración de tu entorno de desarrollo y la creación de un agente conversacional fundamental. Al final de este codelab, habrás construido tu primera IA interactiva, lista para ser expandida en las partes posteriores de esta serie mientras la transformamos en un sofisticado Sistema Multi-Agente (MAS).

Puedes completar este codelab ya sea en tu entorno local o en Google Cloud. Para la experiencia más consistente, recomendamos usar Cloud Shell desde el entorno de Google Cloud. Cloud Shell también proporciona 5 GB de almacenamiento persistente en el directorio $HOME. Esto es útil para almacenar scripts, archivos de configuración o repositorios clonados.

Nota: Si eliges trabajar localmente, podrías requerir pasos adicionales de configuración, instalación y autenticación, que no están cubiertos por la sección de configuración del entorno de este laboratorio.

Prerrequisitos

• Comprensión de los conceptos de IA Generativa
• Competencia básica en programación Python
• Familiaridad con línea de comandos / terminal

Qué aprenderás

• Cómo configurar un entorno Python
• Cómo crear un Agente de Asistente Personal simple usando ADK
• Cómo ejecutar, probar y depurar el agente

Qué necesitarás

• Una computadora funcional y wifi confiable
• Un navegador, como Chrome, para acceder a Google Cloud Console
• Un Proyecto de Google Cloud con facturación habilitada
• Una mente curiosa y ganas de aprender

Los agentes de IA están revolucionando la forma en que interactuamos con la tecnología. Un agente de IA es un programa inteligente diseñado para actuar en tu nombre, similar a un asistente personal digital. Puede percibir su entorno, tomar decisiones y realizar acciones para lograr objetivos específicos de forma autónoma.

¿Qué es un agente de IA?

En esencia, un agente de IA utiliza un Modelo de Lenguaje Grande (LLM) como su "cerebro" para entender y razonar. Esto le permite:

• Procesar información de diversas fuentes (texto, imágenes, audio)
• Comprender el contexto y las intenciones del usuario
• Crear planes de acción
• Ejecutar tareas de forma autónoma
• Aprender y adaptarse con el tiempo

Agent Development Kit (ADK)

El ADK de Google es un framework que simplifica la creación de agentes de IA. Proporciona:

• Herramientas de desarrollo listas para usar
• Integración con modelos Gemini
• Interfaces de usuario predefinidas
• Capacidades de extensión y personalización

En este codelab, crearemos un agente asistente personal que te ayudará con tareas cotidianas.

Crear un Proyecto de Google Cloud

Este codelab asume que ya tienes un proyecto de Google Cloud con facturación habilitada. Si aún no lo tienes, sigue estos pasos:

Seleccionar o crear un proyecto

• Ve a Google Cloud Console.
• En la parte superior, haz clic en el selector de proyectos (junto al logo de Google Cloud).
• Elige un proyecto existente o crea uno nuevo.

Habilitar la facturación

• Asegúrate de que la facturación esté habilitada para el proyecto seleccionado.
• Consulta cómo verificarlo en la documentación de Facturación de Google Cloud.

Nota: La facturación debe estar habilitada incluso para el nivel gratuito, ya que es el mecanismo para rastrear uso. Solo se te cobrará si excedes los límites del nivel gratuito o usas servicios de pago.

Configurar Cloud Shell

Verifica que estás correctamente configurado en Cloud Shell, la interfaz de línea de comandos integrada en Google Cloud Console.

Iniciar Cloud Shell

En la esquina superior derecha de Google Cloud Console, haz clic en el ícono de terminal (>_) para activar Cloud Shell.

Autorizar acceso

Si se te solicita, haz clic en Autorizar para conceder a Cloud Shell los permisos necesarios sobre tu proyecto.

Verificar tu cuenta

Una vez cargado Cloud Shell, confirma que usas la cuenta correcta. Ejecuta:

gcloud auth list

Deberías ver algo similar:

Credentialed Accounts

ACTIVE: *
ACCOUNT: cuenta_actual@example.com

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

Cambiar de cuenta (si es necesario)

Si la cuenta activa no es la correcta para este codelab, cámbiala reemplazando por tu email real:

gcloud config set account <tu_cuenta_deseada@example.com>

Confirmar tu proyecto

Verifica que Cloud Shell usa el proyecto correcto. Ejecuta:

gcloud config list project

Busca la sección [core] y confirma que el ID coincide con el proyecto deseado:

[core]
project = <id-proyecto-actual>

Establecer tu proyecto (si es necesario)

Si no coincide, establece el proyecto correcto:

gcloud config set project <tu-id-proyecto-deseado>

Habilitar APIs requeridas

Antes de usar los servicios de Google Cloud, habilita las APIs necesarias para tu proyecto. En Cloud Shell, ejecuta:

gcloud services enable aiplatform.googleapis.com

Si la operación fue exitosa, verás Operation/... finished successfully en el terminal.

Antes de iniciar cualquier proyecto de Python, es una buena práctica crear un entorno virtual. Esto aísla las dependencias del proyecto, previniendo conflictos con otros proyectos o con los paquetes globales de Python del sistema. Dado que el Agent Development Kit (ADK) requiere Python 3.9 o superior, usaremos una herramienta como uv para gestionar tanto el entorno virtual como asegurar que se use la versión correcta de Python.

uv es una herramienta moderna, rápida y eficiente para gestionar proyectos y entornos de Python, combinando funcionalidades que tradicionalmente se encuentran en herramientas como pip, venv, pip-tools y pipx. Está escrita en Rust para mayor velocidad.

Aunque hay varios métodos para instalar uv, usaremos pip para obtenerlo desde PyPI, ya que Cloud Shell ya tiene pip disponible. Usamos uv porque es una herramienta extremadamente rápida y todo-en-uno que maneja tanto la instalación de paquetes (como pip) como los entornos virtuales (como venv), simplificando nuestro flujo de trabajo.

Instalar el paquete uv

pip install uv

Reiniciar el terminal de Cloud Shell

Después de la instalación, debes reiniciar el terminal de Cloud Shell para que el sistema pueda reconocer el nuevo comando uv.

1. Escribe exit en el terminal de Cloud Shell
2. Vuélvelo a abrir haciendo clic en el ícono del terminal (>_) en la esquina superior derecha

Verificar si uv se instaló correctamente

uv --version

Crear una nueva carpeta de proyecto para tu agente de IA

uv init ai-agents-adk
cd ai-agents-adk

Crear un entorno virtual con Python 3.12

uv venv --python 3.12

Instalar la librería Google ADK dentro de tu entorno virtual

uv add google-adk

Verificar si has instalado el paquete google-adk exitosamente

uv pip list | grep google-adk

Si ves una línea de salida con google-adk y su versión, estás listo para proceder al siguiente paso.

Agregar soporte para variables de entorno (.env)

Para cargar variables desde un archivo .env dentro de tu código Python, instala python-dotenv en el entorno y úsalo al inicio de tus scripts.

Instalar python-dotenv

uv add python-dotenv

Habilite las API necesarias

Haz clic en el siguiente botón para habilitar las APIs necesarias para este codelab en tu proyecto de Google Cloud: Vertex AI, Dataform y Compute Engine.

Habilita las APIs

Ahora que tu entorno de desarrollo está configurado y listo, es momento de establecer los fundamentos para tu agente de IA. El Agent Development Kit (ADK) simplifica este proceso, requiriendo solo unos pocos archivos esenciales para definir la lógica central y la configuración de tu agente.

Estos tres archivos trabajan juntos para hacer que tu agente sea descubrible, ejecutable y configurable:

• agent.py: Este es el corazón de tu agente. Contiene el código Python principal que define el comportamiento de tu agente, incluyendo su nombre, el modelo de lenguaje grande (LLM) que usa como su "cerebro", y las instrucciones centrales que guían sus respuestas.
• __init__.py: En Python, el archivo __init__.py marca un directorio como un paquete de Python. Para ADK, es crucial porque ayuda al framework a descubrir y cargar la definición de tu agente desde agent.py. En proyectos ADK simples, a menudo contiene una sola línea para importar tu módulo del agente, haciendo que tu agente sea accesible al ejecutor de ADK.
• .env: Este archivo (abreviatura de "environment") se usa para almacenar información sensible y variables de configuración que tu agente necesita, como claves API, IDs de proyecto y ubicaciones geográficas. Mantener estos detalles en un archivo .env separado es una buena práctica para seguridad y portabilidad, ya que previene codificar datos sensibles directamente en tu código. También te permite cambiar configuraciones fácilmente sin modificar la lógica principal de tu agente.

Usa los comandos a continuación para crear estos archivos dentro de una carpeta dedicada para tu agente asistente personal:

Crear el agente

uv run adk create personal_assistant

Una vez ejecutado el comando, se te pedirá elegir algunas opciones para configurar tu agente. Para el primer paso, elige la opción 1 para usar el modelo gemini-2.0-flash-001, un modelo rápido y eficiente perfecto para tareas conversacionales.

Choose a model for the root agent:
1. gemini-2.0-flash-001
2. Other models (fill later)
Choose model (1, 2): 1

Para el segundo paso, elige Vertex AI (opción 2), la poderosa plataforma de IA gestionada de Google Cloud, como proveedor de servicios backend.

1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

Finalmente, se te pedirá confirmar tu ID de proyecto de Google Cloud y región. Si los valores pre-llenados (current-project-id y current-region) son los que intentas usar, simplemente presiona Enter para cada pregunta.

Enter Google Cloud project ID [current-project-id]: 
Enter Google Cloud region [current-region]:

Deberías ver una salida similar en tu terminal.

Agent created in /home/<your-username>/ai-agent-adk/personal_assistant:
- .env
- __init__.py
- agent.py

Abrir el Editor

Ahora, haz clic en el botón Open Editor en la parte superior de tu ventana de Cloud Shell. Hacer clic en ese botón te llevará a la ventana del Editor, lo que hace mucho más fácil explorar el contenido de tus archivos. El cambio puede tomar un momento; si te quedas atascado en una pantalla de carga por más de unos minutos, intenta refrescar tu navegador.

Nota: Puedes usar un editor de línea de comandos como Vim, pero necesitarás conocer los comandos para abrir y salir de Vim por tu cuenta.

Una vez que la ventana del Editor esté completamente cargada, navega a la carpeta personal-assistant. Verás los archivos necesarios como se mencionó arriba (agent.py, __init__.py, y .env). Exploremos el contenido.

Si no ves el archivo .env en la carpeta, ve a la barra de menú en la parte superior, haz clic en View, y luego selecciona Toggle Hidden Files. Esta es una configuración común ya que los archivos .env a menudo están ocultos por defecto para prevenir exposición accidental.

Explorar el contenido de cada archivo

agent.py

Este archivo instancia tu agente usando la clase Agent de la librería google.adk.agents.

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.0-flash-001',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

• from google.adk.agents import Agent: Esta línea importa la clase Agent necesaria de la librería ADK.
• root_agent = Agent(...): Aquí, estás creando una instancia de tu agente de IA.
• name="personal_assistant": Un identificador único para tu agente. Así es como ADK reconocerá y se referirá a tu agente.
• model="gemini-2.5-flash": Este parámetro crucial especifica qué Modelo de Lenguaje Grande (LLM) usará tu agente como su "cerebro" subyacente para entender, razonar y generar respuestas. gemini-2.5-flash es un modelo rápido y eficiente adecuado para tareas conversacionales.
• description="...": Esto proporciona un resumen conciso del propósito o capacidades del agente. La descripción es más para entendimiento humano o para otros agentes en un sistema multi-agente para entender qué hace este agente particular. A menudo se usa para logging, depuración, o al mostrar información sobre el agente.
• instruction="...": Este es el prompt del sistema que guía el comportamiento de tu agente y define su personalidad. Le dice al LLM cómo debe actuar y cuál es su propósito principal. En este caso, establece al agente como un "asistente útil". Esta instrucción es clave para dar forma al estilo conversacional y capacidades del agente.

__init__.py

Este archivo es necesario para que Python reconozca personal-assistant como un paquete, permitiendo a ADK importar correctamente tu archivo agent.py.

from . import agent

• from . import agent: Esta línea realiza una importación relativa, diciéndole a Python que busque un módulo llamado agent (que corresponde a agent.py) dentro del paquete actual (personal-assistant). Esta línea simple asegura que cuando ADK trata de cargar tu agente personal-assistant, puede encontrar e inicializar el root_agent definido en agent.py. Incluso si está vacío, la presencia de __init__.py es lo que hace del directorio un paquete de Python.

.env

Este archivo contiene configuraciones específicas del entorno y credenciales sensibles.

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION

• GOOGLE_GENAI_USE_VERTEXAI: Esto le dice al ADK que intentas usar el servicio Vertex AI de Google para tus operaciones de IA Generativa. Esto es importante para aprovechar los servicios gestionados de Google Cloud y modelos avanzados.
• GOOGLE_CLOUD_PROJECT: Esta variable contendrá el identificador único de tu Proyecto de Google Cloud. ADK necesita esto para asociar correctamente tu agente con tus recursos en la nube y habilitar la facturación.
• GOOGLE_CLOUD_LOCATION: Esto especifica la región de Google Cloud donde están ubicados tus recursos de Vertex AI (ej. us-central1). Usar la ubicación correcta asegura que tu agente pueda comunicarse efectivamente con los servicios de Vertex AI en esa región.

Con los tres archivos en su lugar, estás listo para ejecutar el agente directamente desde la terminal. Para hacer esto, necesitas abrir la ventana de Terminal. ¡Hacer clic en Terminal en la barra de menú y luego elegir New Terminal hace el trabajo!

Una vez que la terminal esté disponible, puedes iniciar el agente usando el comando adk run. Como esta es una nueva ventana de terminal y estamos usando uv, primero necesitarás navegar a la carpeta ai-agent-adk y luego prefijar el comando adk run con uv run.

Escribe estos comandos en la terminal:

cd ai-agents-adk
uv run adk run personal_assistant

Si todo está configurado correctamente, verás una salida similar en tu terminal.

...
Running agent personal_assistant, type exit to exit.
[user]: hello. What can you do for me?
[personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as:
...

¡Adelante y conversa con el agente! Notarás que la salida a veces está formateada con Markdown, lo cual puede ser difícil de leer en la terminal. En el siguiente paso, usaremos la Development UI para una experiencia mucho más rica, similar a una aplicación de chat.

El Agent Development Kit también ofrece una forma conveniente de lanzar tu agente como una aplicación de chat usando su development UI. Simplemente usa el comando adk web en lugar de adk run.

Si aún estás en la sesión anterior, simplemente escribe exit en la terminal para cerrarla. Una vez que la sesión anterior esté cerrada, escribe el siguiente comando en la terminal:

uv run adk web

Deberías ver una salida similar en la terminal:

...
INFO:     Started server process [4978]
INFO:     Waiting for application startup.

+------------------------------------------------------+
| ADK Web Server started                               |
|                                                      |
| For local testing, access at http://localhost:8000.  |
+------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Tienes dos opciones para acceder a la development UI:

1. Ctrl + Clic en las URLs (ej. http://localhost:8000) directamente en tu terminal.
2. Haz clic en el botón Web Preview, luego selecciona Change Port. Ingresa el número de puerto (ej. 8000, o el número mostrado después de http://localhost:) y haz clic en Change and Preview para verlo.

Entonces verás la interfaz similar a una aplicación de chat aparecer en tu navegador. ¡Adelante y conversa con tu asistente personal a través de esta interfaz! Notarás que el formateo Markdown ahora se muestra correctamente, y esta UI también te permite depurar e investigar cada evento de mensajería, el estado del agente, las solicitudes del usuario y mucho más. ¡Feliz conversación!

Ahora, dentro de Google Cloud Shell, clona el repositorio del taller y revisa su contenido.

Clonar el repositorio

git clone https://github.com/alarcon7a/adk-agent-101-workshop.git
cd adk-agent-101-workshop

Ver los archivos

Lista los archivos del proyecto para familiarizarte con su estructura:

ls -la

Opcionalmente, abre el editor integrado de Cloud Shell para explorar carpetas y archivos con una UI:

cloudshell open-editor

Con esto tendrás el código del workshop listo para seguir los siguientes pasos en Cloud Shell.