Crea agentes basados en IA con el ADK: conceptos básicos

1. Antes de comenzar

Te damos la bienvenida a la primera parte de la serie "Cómo crear agentes de IA con ADK". En esta serie de codelabs prácticos, te embarcarás en un emocionante viaje para crear tu propio agente inteligente de IA con el Agent Development Kit (ADK) de Google.

Comenzaremos con lo más básico y te guiaremos para que configures tu entorno de desarrollo y crees un agente conversacional fundamental. Al final de este codelab, habrás compilado tu primera IA interactiva, lista para expandirse en las partes posteriores de esta serie a medida que la transformemos en un sofisticado sistema multiagente (MAS).

Puedes completar este codelab en tu entorno local o en Google Cloud. Para obtener la experiencia más coherente, te recomendamos que uses 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 secuencias de comandos, archivos de configuración o repositorios clonados.

Nota: Si decides trabajar de forma local, es posible que necesites pasos adicionales de configuración, instalación y autenticación, que no se incluyen en la sección de configuración del entorno de este lab.

Requisitos previos

• Comprensión de los conceptos de la IA generativa
• Conocimiento básico de programación en Python
• Conocimiento de la línea de comandos o terminal

Qué aprenderás

• Cómo configurar un entorno de Python
• Cómo crear un agente de asistente personal simple con el ADK
• Cómo ejecutar, probar y depurar el agente

Requisitos

• Una computadora que funcione y una red Wi-Fi confiable
• Un navegador, como Chrome, para acceder a la consola de Google Cloud
• Un proyecto de Google Cloud con la facturación habilitada
• Una mente curiosa y ganas de aprender

2. Introducción

El mundo de la IA generativa (GenAI) evoluciona rápidamente, y los agentes de IA son un tema candente en la actualidad. Un agente de IA es un programa informático inteligente diseñado para actuar en tu nombre, de manera similar a un asistente personal. Puede percibir su entorno digital, tomar decisiones y realizar acciones para alcanzar objetivos específicos sin control humano directo. Piensa en ella como una entidad autónoma y proactiva que puede aprender y adaptarse para realizar tareas.

En esencia, un agente de IA usa un modelo de lenguaje grande (LLM) como su "cerebro" para comprender y razonar. Esto le permite procesar información de diversas fuentes, como texto, imágenes y sonidos. Luego, el agente usa esta comprensión para crear un plan y ejecutar una serie de tareas para alcanzar un objetivo predefinido.

Ahora puedes crear fácilmente tus propios agentes de IA, incluso sin tener experiencia profunda, gracias a los frameworks listos para usar, como el Kit de desarrollo de agentes (ADK). Comenzaremos este recorrido creando un agente asistente personal para ayudarte con tus tareas. Comencemos.

3. Configura los servicios de Google Cloud

Crea un proyecto de Google Cloud

En este codelab, se supone que ya creaste un proyecto de Google Cloud con la facturación habilitada. Si aún no tienes un proyecto, sigue estos pasos para crear uno:

Selecciona o crea un proyecto de Google Cloud

• Navega a la consola de Google Cloud.
• En la parte superior, haz clic en el menú desplegable del selector de proyectos (junto al logotipo de Google Cloud).
• Elige un proyecto existente o crea uno nuevo.

Habilitar facturación

• Asegúrate de que la facturación esté habilitada para el proyecto de Google Cloud que seleccionaste.
• Para saber cómo verificar si la facturación está habilitada en un proyecto, sigue las instrucciones de la documentación de Facturación de Google Cloud.

Nota: La facturación debe estar habilitada incluso para los servicios del nivel gratuito, ya que es el mecanismo que usa Google Cloud para hacer un seguimiento del uso de recursos. Dicho esto, solo se te cobrará si tu uso supera los límites del nivel gratuito o si usas servicios pagados.

Configura Cloud Shell

Ahora, asegúrate de que la configuración sea correcta en Cloud Shell, una práctica interfaz de línea de comandos directamente en Google Cloud Console.

Iniciar Cloud Shell

En la esquina superior derecha de la consola de Google Cloud, verás un ícono que parece una terminal (>_). Haz clic en él para activar Cloud Shell.

Autorizar acceso

Si se te solicita, haz clic en Autorizar para otorgarle a Cloud Shell los permisos necesarios para interactuar con tu proyecto de Google Cloud.

Verifica tu cuenta:

Una vez que se cargue Cloud Shell, confirmemos que estás usando la cuenta de Google Cloud correcta. Ejecuta el siguiente comando:

gcloud auth list

Deberías ver un resultado de comando similar en la terminal:

Credentialed Accounts

ACTIVE: *
ACCOUNT: [e-mail]

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

Cambia de cuenta (si es necesario):

Si la cuenta activa no es la que quieres usar para este codelab, cambia a la cuenta correcta con este comando y reemplaza <[e-mail]> por tu correo electrónico real que usarás para este lab:

gcloud config set account <[e-mail]

Confirma tu proyecto

A continuación, verifiquemos que Cloud Shell esté configurado para usar el proyecto de Google Cloud correcto. Ejecuta lo siguiente:

gcloud config list project

Verás una lista de configuración. Busca la sección [core] y asegúrate de que el valor del proyecto coincida con el ID del proyecto de Google Cloud que deseas usar para este codelab:

[core]
project = <current-project-id>

Configura tu proyecto (si es necesario)

Si el valor de project ID es incorrecto, configúralo en el proyecto que desees con el siguiente comando:

gcloud config set project <your-desired-project-id>

Habilita las APIs obligatorias

Para usar los servicios de Google Cloud, primero debes activar sus respectivas APIs para tu proyecto. Ejecutar los siguientes comandos en la terminal de Cloud Shell habilita todos los servicios que necesitarás para este Codelab:

gcloud services enable aiplatform.googleapis.com

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

4. Crea un entorno virtual de Python.

Antes de comenzar cualquier proyecto de Python, es una buena práctica crear un entorno virtual. Esto aísla las dependencias del proyecto y evita conflictos con otros proyectos o con los paquetes globales de Python del sistema. Dado que el Kit de desarrollo de agentes (ADK) requiere Python 3.9 o una versión posterior, usaremos una herramienta como uv para administrar el entorno virtual y garantizar que se use la versión correcta de Python.

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

Cloud Shell ya tiene uv disponible, por lo que podemos comenzar de inmediato.

Verifica si uv está instalado correctamente

uv --version

Crea una carpeta de proyecto nueva para tu agente de IA

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

Crea un entorno virtual con Python 3.12

uv venv --python 3.12

Instala la biblioteca del ADK de Google en tu entorno virtual

uv add google-adk

Verifica si instalaste el paquete google-adk correctamente

uv pip list | grep google-adk

Si ves una línea de salida con google-adk y su versión, puedes continuar con el siguiente paso.

5. Crea un agente

Ahora que tu entorno de desarrollo está configurado y listo, es momento de sentar las bases de tu agente de IA. El Agent Development Kit (ADK) simplifica este proceso, ya que solo requiere algunos archivos esenciales para definir la lógica y la configuración centrales de tu agente.

Estos tres archivos funcionan en conjunto para que tu agente se pueda descubrir, ejecutar y configurar:

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

Usa los siguientes comandos para crear estos archivos en una carpeta dedicada para tu agente asistente personal:

uv run adk create personal_assistant

Una vez que se ejecute el comando, se te pedirá que elijas algunas opciones para configurar tu agente. En el primer paso, elige la opción 1 para usar el modelo gemini-2.5-flash, un modelo rápido y eficiente perfecto para tareas de conversación.

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

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

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

Por último, se te pedirá que confirmes el ID y la región de tu proyecto de Google Cloud. Si los valores completados previamente (current-project-id y current-region) son los que deseas usar, solo presiona Intro para cada pregunta.

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

Deberías ver un resultado similar en tu terminal.

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

Ahora, haz clic en el botón Abrir editor en la parte superior de la ventana de Cloud Shell. Si haces clic en ese botón, se abrirá la ventana del Editor, que te permitirá explorar el contenido de tus archivos con mayor facilidad. El cambio puede tardar un momento. Si te quedas atascado en una pantalla de carga durante más de unos minutos, intenta actualizar el navegador.

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

Una vez que se cargue por completo la ventana del editor, navega a la carpeta personal-assistant. Verás los archivos necesarios como se mencionó anteriormente (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 Ver y, luego, selecciona Alternar archivos ocultos. Este es un parámetro de configuración común, ya que los archivos .env suelen estar ocultos de forma predeterminada para evitar la exposición accidental.

Exploremos el contenido de cada archivo.

agent.py

Este archivo crea una instancia de tu agente con la clase Agent de la biblioteca google.adk.agents.

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.5-flash',
    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 biblioteca del ADK.
• root_agent = Agent(...): Aquí, creas una instancia de tu agente de IA.
• name="personal_assistant": Es un identificador único para tu agente. Así es como el 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 comprender, razonar y generar respuestas. gemini-2.5-flash es un modelo rápido y eficiente adecuado para tareas de conversación.
• description="...": Proporciona un resumen conciso del propósito o las capacidades del agente. La descripción es más para que los humanos comprendan o para que otros agentes en un sistema multiagente comprendan lo que hace este agente en particular. Se suele usar para el registro, la depuración o cuando se muestra información sobre el agente.
• instruction="...": Es la instrucción del sistema que guía el comportamiento del agente y define su arquetipo. Le indica 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 definir el estilo y las capacidades de conversación del agente.

init.py

Este archivo es necesario para que Python reconozca personal-assistant como un paquete, lo que permite que el ADK importe correctamente tu archivo agent.py.

from . import agent

• from . import agent: Esta línea realiza una importación relativa, lo que le indica a Python que busque un módulo llamado agent (que corresponde a agent.py) dentro del paquete actual (personal-assistant). Esta simple línea garantiza que, cuando el ADK intente cargar tu agente personal-assistant, pueda encontrar e inicializar el root_agent definido en agent.py. Incluso si está vacío, la presencia de __init__.py es lo que convierte el directorio en 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: Indica al ADK que tienes la intención de usar el servicio de Vertex AI de Google para tus operaciones de IA generativa. Esto es importante para aprovechar los servicios administrados y los modelos avanzados de Google Cloud.
• GOOGLE_CLOUD_PROJECT: Esta variable contendrá el identificador único de tu proyecto de Google Cloud. El ADK necesita esta información para asociar correctamente tu agente con tus recursos de Cloud y habilitar la facturación.
• GOOGLE_CLOUD_LOCATION: Especifica la región de Google Cloud en la que se encuentran tus recursos de Vertex AI (p.ej., us-central1). Usar la ubicación correcta garantiza que tu agente pueda comunicarse de manera eficaz con los servicios de Vertex AI en esa región.

6. Ejecuta el agente en la terminal

Con los tres archivos en su lugar, ya puedes ejecutar el agente directamente desde la terminal. Para ello, debes abrir la ventana de Terminal. Haz clic en Terminal en la barra de menú y, luego, elige Nueva terminal.

Una vez que la terminal esté disponible, puedes iniciar el agente con el comando adk run. Como se trata de una nueva ventana de terminal y estamos usando uv, primero deberás navegar a la carpeta ai-agent-adk y, luego, agregar el prefijo uv run al comando adk run.

Escribe estos comandos en la terminal:

cd ai-agents-adk
uv run adk run personal_assistant

Si todo está configurado correctamente, verás un resultado 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, chatea con el agente! Notarás que, a veces, el resultado se formatea con Markdown, lo que puede dificultar su lectura en la terminal. En el siguiente paso, usaremos la IU de desarrollo para una experiencia mucho más enriquecida, similar a la de una aplicación de chat.

7. Ejecuta el agente en la IU de desarrollo

El Kit de desarrollo de agentes también ofrece una forma conveniente de lanzar tu agente como una aplicación de chat con su IU de desarrollo. Simplemente usa el comando adk web en lugar de adk run..

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

uv run adk web

Deberías ver un resultado 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 IU de desarrollo:

1. Abrir con Terminal

• Ctrl + clic o Cmd + clic en las URLs (p.ej., http://localhost:8000) desde la terminal.

2. Abre la Vista previa en la Web.

• 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. ¡Adelante! Chatea con tu asistente personal a través de esta interfaz. Notarás que el formato de Markdown ahora se muestra correctamente, y esta IU también te permite depurar e investigar cada evento de mensajería, el estado del agente, las solicitudes del usuario y mucho más. ¡Que disfrutes de tus chats!

8. Limpieza

Como este codelab no involucra ningún producto de ejecución prolongada, basta con detener las sesiones de agentes activos (p.ej., la instancia adk web en tu terminal) presionando Ctrl + C en la terminal.

Precaución: NO continúes con estos pasos si planeas seguir con la serie de codelabs, ya que te harán repetir algunas acciones en el próximo codelab.

Borra las carpetas y los archivos del proyecto del agente

Si solo deseas quitar el código de tu entorno de Cloud Shell, usa los siguientes comandos:

cd ~
rm -rf ai-agents-adk

Inhabilita la API de Vertex AI

Para inhabilitar la API de Vertex AI que habilitaste antes, ejecuta este comando:

gcloud services disable aiplatform.googleapis.com

Cierra todo el proyecto de Google Cloud

Si deseas cerrar por completo tu proyecto de Google Cloud, consulta la guía oficial para obtener instrucciones detalladas.

9. Conclusión

¡Felicitaciones! Creaste correctamente un agente asistente personal simple con el Kit de desarrollo de agentes (ADK).

Como habrás notado, este agente asistente personal aún no es muy capaz (por ejemplo, no puede acceder a Internet para obtener la información más reciente). En el próximo codelab de esta serie sobre "Cómo compilar agentes de IA con el ADK", aprenderás a potenciar tu agente asistente personal con funciones y herramientas. ¡Nos vemos!