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 Kit de desarrollo de agentes (ADK) de Google.

Comenzaremos con lo más básico y te guiaremos para configurar tu entorno de desarrollo y crear 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 transformamos 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 IA generativa
• Dominio básico de la programación en Python
• Conocimientos de la línea de comandos o la 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
• Una mente curiosa y ganas de aprender

Canjea una cuenta de facturación de prueba

Nota: No es necesario que realices este paso si ya tienes una cuenta de facturación. Si asistes a este codelab en persona con un instructor, este te proporcionará la información necesaria.

Para completar este codelab, también necesitas una cuenta de facturación de Google Cloud activa. Si aún no tienes una, sigue estos pasos para canjear una cuenta de facturación de prueba:

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

2. Introducción

El mundo de la IA generativa (IA generativa) 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 forma 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 construyendo un agente asistente personal para ayudarte con tus tareas. Comencemos.

3. Configura los servicios de Google Cloud

Crea un proyecto de Google Cloud

Comienza por crear un proyecto de Google Cloud nuevo para que las actividades de este codelab se aíslen solo dentro de este proyecto nuevo.

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 ves esta opción, selecciona Cuenta de facturación de prueba de Google Cloud Platform. No te preocupes si no ves esta opción. Solo continúa 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 y, si ves una ventana emergente que te pide que autorices, haz clic en Autorizar.

2. Configura el ID del proyecto

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

gcloud config set project <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 API 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

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.

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 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) antes de la solicitud 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

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

Con tu entorno listo, es hora de crear la base de tu agente de IA. El ADK requiere algunos archivos para definir la lógica y la configuración de tu agente:

• agent.py: Contiene el código principal de Python del agente, que define su nombre, el LLM que usa y las instrucciones principales.
• __init__.py: Marca el directorio como un paquete de Python, lo que ayuda al ADK a descubrir y cargar la definición de tu agente.
• .env: Almacena información sensible y variables de configuración, como la clave de API, el ID del proyecto y la ubicación.

Este comando creará un directorio nuevo llamado personal_assistant que contiene los tres archivos esenciales.

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

Después, debes verificar que el ID del proyecto que se muestra entre corchetes […] esté configurado correctamente. Si es así, presiona Intro. De lo contrario, ingresa el ID del proyecto correcto en el siguiente mensaje:

Enter Google Cloud project ID [your-project-id]:

Por último, presiona Intro en la siguiente pregunta para usar us-central1 como la región de este codelab.

Enter Google Cloud region [us-central1]:

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

6. Explora los códigos de agentes

Para ver los archivos creados, abre la carpeta ai-agents-adk en el editor de Cloud Shell.

• Haz clic en File > Open Folder… en el menú superior.
• Busca y selecciona la carpeta ai-agents-adk.
• Haz clic en Aceptar.

Si no aparece la barra de menú superior, también puedes hacer clic en el ícono de carpetas y elegir Abrir carpeta.

Nota: Puedes usar un editor de línea de comandos como Vim, pero deberás conocer los comandos para 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).

El archivo .env suele estar oculto de forma predeterminada. Para que sea visible en el Editor de Cloud Shell, haz lo siguiente:

• ve a la barra de menú en la parte superior,
• Haz clic en Ver.
• selecciona Toggle Hidden Files.

Explora 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="root_agent": 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 la comprendan los humanos o para que otros agentes de un sistema multiagente entiendan 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 conversacionales 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 hace que el directorio sea 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.

7. Ejecuta el agente en la terminal

Con los tres archivos en su lugar, ya puedes ejecutar el agente directamente desde la terminal. Para ello, ejecuta el siguiente comando adk run en la terminal:

adk run personal_assistant

Si todo está configurado correctamente, verás un resultado similar en tu terminal. Por el momento, no te preocupes por las advertencias. Si ves [user]:, puedes continuar.

...
Running agent personal_assistant, type exit to exit.
[user]: 
...

¡Adelante, chatea con el agente! Escribe algo como "hola. ¿Qué puedes hacer por mí?" y deberías recibir una respuesta.

...
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:
...

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.

Solución de problemas

Es necesario habilitar la facturación para usar este método de la API

Si recibes un mensaje que dice {‘message': ‘This API method requires billing to be enabled'}, haz lo siguiente:

1. Verifica si usas el ID del proyecto correcto en el archivo .env
2. Ve a la página de la cuenta de facturación vinculada y comprueba si la cuenta de facturación ya está vinculada.
3. De lo contrario, elige Cuenta de facturación de prueba de Google Cloud Platform en la opción.

No se usó la API de Vertex AI en el proyecto

Si recibes un mensaje de error que contiene {'message': 'Vertex AI API has not been used in project...'}, habilita la API de Vertex AI escribiendo lo siguiente en la terminal:

gcloud services enable aiplatform.googleapis.com

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

Otros errores

Si recibes otros errores que no se mencionan anteriormente, intenta volver a cargar la pestaña de Cloud Shell en el navegador (y vuelve a autorizar si se te solicita).

8. Ejecuta el agente en la IU web de desarrollo

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

Si tu terminal aún ejecuta adk run, escribe exit para cerrarla antes de escribir este comando:

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 el vínculo (p.ej., http://localhost:8000), como se muestra en 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. ¡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 Chat!

9. Limpieza (opcional)

Nota: No es necesario que realices este paso si planeas continuar con la serie. Si asistes a este codelab en persona con un instructor, este te brindará más instrucciones sobre qué hacer.

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

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.

10. Conclusión

¡Felicitaciones! Creaste correctamente un agente asistente personal simple con el Kit de desarrollo de agentes (ADK). Ahora tienes una base sólida y comprendes los componentes principales de un agente del ADK.

Como siguiente paso, puedes expandir significativamente las capacidades de tu agente proporcionándole herramientas para acceder a información en tiempo real y para interactuar con servicios externos. Si quieres continuar tu recorrido, el siguiente codelab de esta serie, Cómo compilar agentes de IA con el ADK: Potenciación con herramientas, te guiará por este proceso.