Cómo crear un agente de viajes simple con ADK y Gemini CLI

1. Introducción

Última actualización: 22 de junio de 2026

Cómo crear un agente de viajes simple con el ADK

Te damos la bienvenida a este taller de Python(*) de ADK, que incluye todo lo que necesitas gracias a Gemini CLI.

Este codelab se divide en dos 🏅 hitos:

1. Una ruta de aprendizaje común y sencilla: configuración y gratificación instantánea.
2. Una ruta personalizada en la que eliges una misión para resolver con la ayuda de Gemini CLI

La segunda parte hace que este codelab sea perfecto para una hackatón (y premios para las soluciones más creativas).

Hito 1: Tu primer agente con ADK y Gemini CLI

El objetivo de este hito es crear un agente de viajes simple con el ADK paso a paso. Para ello, primero queremos configurar Gemini CLI para que nos ayude a programar con el ADK. Esto permitirá que tu shell local elija la versión más reciente del ADK de Python, adapte el código y los documentos, y proporcione el código más reciente y mejor para trabajar con él y lograr tu objetivo.

Esta es una parte guiada en la que logramos una app completamente funcional a través de incrementos pequeños y sencillos. Por lo general, este proceso tarda alrededor de una hora (más el tiempo de instalación).

Nota (*): Si bien el codelab supone que usas el ADK de Python, puedes hacer que funcione con Go, Java o TypeScript con muy pocos cambios. De hecho, si solo usaste el ADK con Python, este codelab es una gran oportunidad para probar la ruta en un lenguaje diferente. Cuéntanos qué te parece a través del vínculo de comentarios que aparece a continuación.

Hito 2: Extiende tu agente

Después de eso, te daremos una docena de opciones (de dificultad variable) para que extiendas la app como quieras. Esto te permite explorar diferentes aspectos (IU, operaciones, interacciones complejas de agentes, etcétera).

Qué compilarás

En este codelab, crearás una app de agente de viajes con ADK y Gemini CLI. Tu app hará lo siguiente:

• Conectarse a las APIs de Airbnb a través del MCP de Airbnb
• Buscar información actualizada en línea (clima, fechas, etc.)
• Ejecutar herramientas personalizadas
• Crea imágenes de los departamentos o las habitaciones con Nano Banana.

Gemini CLI te guiará en todo esto: escribir y revisar código, y encontrar la documentación más reciente en una réplica local del repositorio del ADK (en Python o tu lenguaje favorito).

Qué aprenderás

• Cómo crear una app con el ADK
• Cómo usar Gemini CLI para programar apps basadas en documentos locales
• Cómo interactuar con un servidor de MCP para conectarse a fuentes de datos externas en tiempo real, como se muestra a continuación:

Requisitos

• Una computadora que te permita instalar paquetes (p. ej., npm install ..)
• Capacidad básica de programación en Python, TypeScript, Go o Java
• Se recomienda usar un IDE (Antigravity, VS Code, IntelliJ o Vim).

¿Por qué usar ADK y Gemini CLI?

Es posible que algunos de ustedes se pregunten: ¿Por qué necesito usar el ADK (un SDK de compilador de agentes) junto con un asistente de código de agentes local (como la CLI de Gemini)? El motivo es que ambas herramientas son increíblemente potentes, pero su interacción no es trivial; muchas personas intentaron trabajar con ambas en conjunto y fallaron (principalmente debido a problemas de "bucle en un bucle"). En este codelab, se comparten algunas sugerencias para que esta coexistencia sea posible.

2. Cómo prepararte

Elige una de las siguientes opciones: Configuración del entorno de autoaprendizaje si quieres ejecutar este codelab en tu propia máquina o Iniciar Cloud Shell si quieres ejecutar este codelab por completo en la nube.

Configuración del entorno de autoaprendizaje

1. Accede a la consola de Google Cloud y crea un proyecto nuevo o reutiliza uno existente. Si aún no tienes una cuenta de Gmail o de Google Workspace, debes crear una.

• El Nombre del proyecto es el nombre visible de los participantes de este proyecto. Es una cadena de caracteres que no se utiliza en las APIs de Google. Puedes actualizarla cuando quieras.
• El ID del proyecto es único en todos los proyectos de Google Cloud y es inmutable (no se puede cambiar después de configurarlo). La consola de Cloud genera automáticamente una cadena única. Por lo general, no importa cuál sea. En la mayoría de los codelabs, deberás hacer referencia al ID de tu proyecto (suele identificarse como PROJECT_ID). Si no te gusta el ID que se generó, podrías generar otro aleatorio. También puedes probar uno propio y ver si está disponible. No se puede cambiar después de este paso y se usa el mismo durante todo el proyecto.
• Recuerda que hay un tercer valor, un número de proyecto, que usan algunas APIs. Obtén más información sobre estos tres valores en la documentación.

Precaución: El ID del proyecto es único a nivel global y no lo puede usar nadie más después de que lo hayas seleccionado. Eres el único usuario de ese ID. Incluso si se borra un proyecto, no se puede volver a usar el ID.

Nota: Si usas una cuenta de Gmail, puedes dejar la ubicación predeterminada como Sin organización. Si usas una cuenta de Google Workspace, elige una ubicación adecuada para tu organización.

2. A continuación, deberás habilitar la facturación en la consola de Cloud para usar las APIs o los recursos de Cloud. Ejecutar este codelab no costará mucho, tal vez nada. Para cerrar recursos y evitar que se generen cobros más allá de este instructivo, puedes borrar los recursos que creaste o borrar el proyecto. Los usuarios nuevos de Google Cloud son aptos para participar en el programa Prueba gratuita de $300.

Inicia Cloud Shell

Si bien Google Cloud y Spanner se pueden operar de manera remota desde tu laptop, en este codelab usarás Google Cloud Shell, un entorno de línea de comandos que se ejecuta en la nube.

En la consola de Google Cloud, haz clic en el ícono de Cloud Shell en la barra de herramientas en la parte superior derecha:

El aprovisionamiento y la conexión al entorno deberían tomar solo unos minutos. Cuando termine el proceso, debería ver algo como lo siguiente:

Esta máquina virtual está cargada con todas las herramientas para desarrolladores que necesitará. Ofrece un directorio principal persistente de 5 GB y se ejecuta en Google Cloud, lo que permite mejorar considerablemente el rendimiento de la red y la autenticación. Todo tu trabajo en este codelab se puede hacer en un navegador. No es necesario que instales nada.

3. Requisitos previos (instalación)

Nota: Si decides ejecutar este codelab en Cloud Shell, Python, uv y la CLI de Gemini (gemini) ya están preinstalados.

Para este instructivo, debes instalar lo siguiente:

1. Python y uv

python y uv (administrador de paquetes para Python). Esto es necesario para el ADK. Asegúrate de tener uv instalado:

$ curl -LsSf https://astral.sh/uv/install.sh | sh

¿Por qué uv? Si bien puedes usar el administrador de Python que prefieras, usar uv garantizará que la configuración de ENV/PATH para Python sea la misma para ti y para Gemini CLI, por lo que tu experiencia con la shell será casi la misma que la de Gemini CLI. Si usas virtualenv , por ejemplo, Gemini CLI se verá obligada a hacer cosas como "source .env/venv/bin/activate && my-original-command" para imitar tu entorno.

2. Gemini CLI

Para la CLI de Gemini, consulta las instrucciones de instalación aquí: https://github.com/google-gemini/gemini-cli.

# Note: This requires having npm or npx installed.
npm install -g @google/gemini-cli

1. En Mac, puedes usar brew según los documentos oficiales.
2. En Windows, puedes usar chocolatey o simplemente descargar el ejecutable desde https://nodejs.org/en/download.

Para el paso 4 (más adelante), también necesitarás tener instalado npx. Tanto npm como npx deberían ser parte de Gemini CLI de forma natural. Si no es así, pídele a Gemini CLI que te ayude aquí.

Autenticación

Necesitas un proyecto de Google Cloud con Vertex AI habilitado o una clave de API de Google AI Studio.

Opción A (recomendada para el taller): Exporta tu clave de API:

export GOOGLE_API_KEY="your-api-key"

Opción B (Vertex AI): Autentícate con gcloud:

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
export GOOGLE_GENAI_USE_VERTEXAI=true
gcloud auth application-default login

Configura tu entorno de trabajo

Crearás tu PROPIA solución en mysolution/, así que crearemos la carpeta y los dos archivos que necesitamos.

Este es el momento en el que puedes abrir tu IDE (Visual Studio Code, IntelliJ, RubyMine, etcétera) y abrir la carpeta.

# 1. Find an empty directory, and download this repo.
git clone https://github.com/palladius/adk-gemini-cli-workshop
cd adk-gemini-cli-workshop/

# 2. Create your solution empty skeleton
mkdir -p mysolution/
touch mysolution/__init__.py mysolution/agent.py

# 3. This installs ADK and MCP via `uv` by reading pyproject.toml
uv init
uv sync

# 4. Call Gemini CLI
gemini  # This runs Gemini CLI under the adk-gemini-cli-workshop/ folder.
# Login with your GMail account.

uv sync no es estrictamente necesario, pero si falla, sabrás que debes corregir tu instalación de Python o uv. Esto debería instalar adk y otras secuencias de comandos útiles en la carpeta ./.venv/bin/.

Para probar tu configuración, puedes ejecutar make test-step1 y verificar que no obtengas un 403 PERMISSION DENIED.

Importante: Asegúrate de ejecutar Gemini CLI desde la carpeta 📁 adk-gemini-cli-workshop/. Además, el IDE debería mostrarte esto como nombre raíz. Esto garantiza que Gemini CLI use la configuración correcta. Siempre puedes agregar carpetas externas a través de /dir add /your/other/folder, pero 📁 adk-gemini-cli-workshop/ proporciona la mejor ubicación inicial.

Soluciones disponibles

Todo el código se encuentra en 📂 steps/. Puedes copiar el código desde allí.

Este codelab no se trata de aprender a escribir un buen código de ADK, sino de configurar tu entorno para que se escriba un BUEN código automáticamente bajo tu dirección.

1. Instala el software
2. configurarlo o hacerlo funcionar, y
3. ingresando a un ciclo de reacción virtuoso

Esto es lo que realmente queremos que aprendas aquí. También puedes probarlos todos al mismo tiempo con $ make web-4steps.

4. Paso 1: Agente básico

Comencemos por crear un agente básico que pueda mantener una conversación.

Edita el archivo llamado mysolution/__init__.py agregando el siguiente contenido:

from .agent import root_agent

¡Así de simple! Esto permite que ADK sepa dónde está tu código: en agent.py.

Edita el archivo llamado mysolution/agent.py agregando el siguiente contenido:

from google.adk.agents import Agent

root_agent = Agent(
    name="travel_basic",
    model="gemini-2.5-flash",
    instruction="You are a helpful travel assistant." +
    "You can help with general travel advice based on your knowledge.",
)

Prueba el agente

Esto se aplica a todos los pasos. El ADK te permite probar tu agente de dos maneras: con la CLI y con la Web.

• La CLI es ideal para pruebas rápidas y automatizadas.
• La Web es la mejor opción para ver visualmente lo que sucede, usar el micrófono (!) y solucionar problemas.

Sugerencia: Para este ejercicio, usa la Web para realizar cualquier acción (excepto las pruebas de unidades). ¡Es realmente increíble! Mantén la CLI solo para las pruebas automatizadas.

Una buena instrucción que pruebe correctamente los pasos 1, 2, 3 y 4 puede ser esta (instrucción de "prueba de fuego" inteligente):

Hola, me gustaría reservar un hotel en París para mañana por la noche, solo una noche, en el centro de la ciudad. Idealmente, cerca de la estación Gare de Lyon. Presupuesto: menos de EUR 200 por noche.

1. Dime qué AAAAMMDD y día de la semana es mañana.
2. Dime qué hoteles ves para mañana (al menos 3). Quiero ver lo siguiente: > precio, dirección, alguna calificación (en formato XX/YY, p. ej., "4.7/5", de Hoteles de Google, Booking o Airbnb), cantidad de opiniones. Proporciónalas en formato TABULAR. Lo ideal es que el nombre del hotel esté vinculado a algún tipo de URL del hotel (no te preocupes por agregar una columna de URL). Asegúrate de que el vínculo sea legítimo (que funcione y que la página dirija a información sobre el hotel).

Esta es una instrucción inteligente, ya que prueba el tiempo y los hoteles, y fallará de manera diferente en los pasos 1, 2 y 3, y debería tener éxito solo en el paso 4. Por supuesto, puedes usar cualquier instrucción que tú quieras.

Ejecútalo desde Bash (CLI):

# 1. If ADK was installed:
adk run mysolution/
# ... but if you get: -bash: adk: command not found"
# 2. Call ADK cli script through UV to avoid python install nightmares.
uv run adk run mysolution/

Intenta usar la "instrucción de prueba" anterior.

Es probable que no pueda conocer fechas específicas. ¡Tenemos que enseñarle a saber la fecha!

En la Web, puedes hacer lo siguiente:

1. uv run adk web . : Ejecuta todos los agentes de esta carpeta. Quieres que apunte a la subcarpeta "mysolution/"
2. Elige mysolution/ en la esquina superior derecha (consulta la imagen que aparece al lado).
3. Haz tu pregunta en texto o con el micrófono, algo similar a la "instrucción de prueba".

Ten en cuenta que debes llamar a adk web desde la carpeta superior, con respecto a la versión de la CLI.

Esta es una posible solución, con una semialucinación de fecha. Observa que 3 de los 5 vínculos para reservar funcionan. Bastante bien.

5. Paso 2: Agrega la herramienta now()

Agrega esta función a agent.py justo antes de la definición de root_agent:

from datetime import datetime

def now() -> dict:
    """Returns the current date and time."""
    my_datetime = ... # Ask Gemini CLI to help you!
    return {
        "status": "success",
        "current_time": my_datetime
    }

Actualiza la definición del agente para incluir la herramienta:

  # file XXX.py

  root_agent = Agent(
        name="..",
        model="..",
        instruction="..",
        tools=[now] # <== This is the only line you want to add.
    )

Vuelve a ejecutarlo y haz la misma pregunta. Ahora debería saber la fecha (bien) y ser impreciso sobre los hoteles (mal).

También puedes probarlo con algo como esto:

# Let's pretend we're in Milan. This should call the tool
# and respond correctly (possibly with some TZ math issues)
echo "What time is it in Milan?" | uv run adk run mysolution/

6. Paso 3: Cambia de tema: google_search

google_search. Esto permite que nuestro agente acceda a información en tiempo real de la Web.

Nota: Los modelos 🚨 gemini-2.x no pueden mezclar de forma nativa la Búsqueda de Google con herramientas personalizadas (consulta el problema n° 969), por lo que reemplazaremos now() por google_search para simplificar el proceso. Más detalles: ISSUES.md.

Tu tarea es modificar el agente del paso 2. En lugar de usar la herramienta now, importarás y usarás la herramienta google_search de la biblioteca de ADK.

# Full Code: `steps/step03_search/agent.py`
# Remember to REMOVE the now() tool here. See above why.
from google.adk.agents import Agent
from google.adk.tools import google_search

root_agent = Agent(
    name="travel_agent",
    model="gemini-2.5-flash",
    tools=[google_search],
    instruction="""You are a travel agent.
Your job is to help the user plan a trip.
You have access to a search engine.
If you don't know the answer, you can use the search engine.
When you are done, reply with "DONE".""",
)

Cómo ejecutar

Igual que en el paso 1.

Solo expertos. Para una integración más avanzada (en la que se usen google_search y now juntos), revisa el código en steps/step03b_search_and_tool/agent.py y ejecútalo con make run-step3b. Esto es completamente opcional.

7. Paso 4: Una herramienta más sofisticada: MCP

Ahora que vimos las herramientas personalizadas y las integradas, pasemos a algo más potente: el patrón Model-as-a-Tool con el Protocolo de contexto del modelo (MCP).

Para que este paso se centre en las potentes capacidades de MCP, volveremos a reemplazar nuestra herramienta anterior (google_search). Volveremos a introducir nuestra sencilla herramienta now para que se ejecute junto con la herramienta airbnb_mcp. Esto demuestra cómo un agente puede usar varias herramientas compatibles (en este caso, un FunctionTool y un MCPToolset) para realizar tareas complejas.

# Full Code: steps/step04_mcp/agent.py
# ... Imports as before
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters

def now() -> dict:
    # ... as before

# Configure the Airbnb MCP Toolset
airbnb_mcp = MCPToolset(
    connection_params=StdioConnectionParams(
        server_params=StdioServerParameters(
            command='npx',
            args=["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"],
        ),
    )
)

root_agent = Agent(
    name="travel_mcp",
    model="gemini-2.5-flash",
    instruction="You are a helpful travel assistant. You can find accommodation using Airbnb, and have access to the current time.",
    tools=[now, airbnb_mcp],
)

Cómo ejecutar

Para este paso, se requiere que npx esté instalado en tu sistema. Para el resto, es lo mismo que lo anterior.

Advertencias y errores

1. Si recibes un error de restricción robots.txt, puedes aplicar un parche al MCP con una directiva para ignorar robots. Lee los documentos para obtener más detalles: https://github.com/openbnb-org/mcp-server-airbnb
2. Si recibes un error timeout (5 segundos es un tiempo demasiado corto para que Airbnb obtenga respuestas), consulta la documentación de ADK para saber cómo aumentar el tiempo de espera, por ejemplo, a 30 segundos. O bien, usa Gemini CLI para hacerlo. Ten en cuenta que, el 3 de diciembre de 2025, Cloud Shell me dio un error de tiempo de espera, lo corregí y, aun así, obtuve errores hasta que lo forcé a la versión anterior: args=["-y", "@openbnb/mcp-server-airbnb@0.1.2", "--ignore-robots-txt"].

8. 🏅 ¡Se completó el hito 1!

🏅 ¡Felicitaciones! 🏅 ¡Ahora eres un experto en el ADK! Completaste la primera parte del taller y creaste y probaste correctamente agentes de IA con herramientas personalizadas, herramientas integradas y herramientas de MCP avanzadas. Ya tienes todo lo necesario para crear tus propios agentes increíbles con el Kit de desarrollo de agentes de Google.

Ahora tienes un agente de viajes funcional que conoce la hora y puede buscar en la Web. ¡El cielo es el límite!

Ahora es momento de agregar una funcionalidad adicional con "Gemini CLI".

9. 🏅 Hito 2: Realiza vibe coding con ADK a través de Gemini CLI

Ahora, ingresamos a la parte interesante del taller.

1. asegúrate de haber git commitguardado el código en un lugar seguro. Puedes bifurcar el código original o crear una rama. No te preocupes, Gemini CLI es excelente para ayudarte en este proceso.
2. Busca una 💡 idea para implementar. Puedes consultar las ideas que se muestran a continuación, encontrar una por tu cuenta o pedirle a Gemini que consulte la documentación en rag/ y proponga algunas ideas inteligentes.
3. Sigue los requisitos previos para asegurarte de que Gemini pueda leer los documentos del ADK y, luego, podrás comenzar.

💡 Ideas

1. 🟢 [Fácil] ¿Eres políglota? ¿Quieres dar go, java o TypeScript? Refactorizar el código existente es muy sencillo. Solo asegúrate de descargar el ADK adecuado y pedirle a Gemini CLI que realice la traducción.
2. 🟢 [Fácil] Agrega emojis o especifica algún formato de resultado que te guste (p. ej., una tabla con un emoji de hotel, seguido del precio y, luego, de emojis de 1 a 5 estrellas con 🌕🌕🌕🌗🌑 para incluir también medias estrellas).
3. 🟢 [Fácil] Cambia la instrucción para enseñarle cosas que buscas o que no quieres (que se admitan mascotas, que no sea en la planta baja, que sea silencioso, que esté cerca del transporte público, etcétera) y pruébala. Tal vez, agregar una calificación personal como "una calificación de TU_NOMBRE del 1 al 10" según lo anterior y ordenar por esa calificación.
4. 🟢 [Fácil] ¿Hay algún operador en la sala? Implementa en Cloud Run. O a Vertex AI Agent Engine. ¿Sabías que puedes integrar este agente y llamarlo directamente desde el nuevo Gemini Enterprise?
5. 🟢 [Fácil] Integra adk run con 🍌 NanoBanana MCP. Requiere una clave de API de Gemini. Aquí podrás crear imágenes, pero no visualizarlas. Consulta más abajo para ver una variante más difícil.
6. 🟡 [Media] Crea un agente secundario que realice la HotelSearch y un BudgetAgent o un LocationAgent que pueda profundizar y realizar iteraciones en los hoteles respetando tus necesidades de ubicación, p. ej., "a no más de X km de UBICACIÓN". Si la API no lo permite, es posible que haya un intercambio de información con la ayuda de la Búsqueda de Google. Nota: Gemini CLI puede ayudarte.
7. 🟡 [medio] Implementa un AirbnbReviewAgent que analice las opiniones y resuma los aspectos positivos y negativos en algunas viñetas codificadas por colores para 1 o N hoteles que resulten de una búsqueda. Ya tienes 2 ingredientes (GoogleSearch y MCP Airbnb), por lo que debes conectarlos al agente principal y, tal vez, inventar algún tipo de protocolo para que se comuniquen.
8. 🟡 [media] Realiza la integración con A2A. Conviértelo en un agente A2A Una vez más, pídele ayuda a Gemini CLI.
9. 🔴 [complejo] Puedes integrarlo con Vuelos o con otras funciones de MCP para crear un agente de viajes multifacético y multifuncional.
10. 🔴 [Complejo] Integra la Web del ADK con el MCP de NanoBanana. Esta tarea es más difícil que la anterior, y puedes encontrar algunas sugerencias en https://github.com/palladius/ai-friendly-agents/issues/11. Esto le llevó al autor 3 horas de idas y vueltas con Gemini CLI, Gemini 3 y ambos leyendo la documentación y el código de rag/.

¿Buscas más inspiración?

1. Consulta el instructivo oficial del ADK para obtener algunas ideas.
2. Pídele a Gemini CLI que busque ideas consultando la documentación en rag/. Una posible instrucción podría ser: Is there a feature in here which seems very succulent to you? Give me 3 proposals and let's implement together the one I choose.

Requisitos previos para la "RAG" de ADK

Para programar una funcionalidad con vibe coding, te recomendamos que descargues todo el ADK de Python (ten en cuenta que esto se puede adaptar muy fácilmente a tu lenguaje favorito, como Java o Go).

El código se encuentra en ./rag y se puede descargar con ./download-adk.sh.

Como la carpeta rag aparece en tu archivo .gitignore, asegúrate de que tu .gemini/settings.json contenga lo siguiente:

{
 "context": {
   "includeDirectories": ["rag"]
 }
}

¿Por qué? Queremos que Gemini pueda leer esos archivos, mientras se ignoran de forma segura en Git. Técnicamente, también podrías mostrar todos los archivos .gitignore configurando context.fileFiltering.respectGitIgnore como false, pero esto abre mucha basura de node_modules/ y __pycache__/, por lo que la inclusión explícita de carpetas es la opción preferida.

10. Próximos pasos

Curiosidad: Este taller se creó con la ayuda de Gemini CLI. Si te interesa, puedes ver cómo lo hice consultando GEMINI.md y WORKSHOP_PLAN.md en esta carpeta.

Lecciones aprendidas

Aprendimos a vincular ADK con Gemini CLI.

Lecturas adicionales

• Consulta estos dos codelabs oficiales de Antigravity:
  • Primeros pasos con Google Antigravity
  • Build with Google Antigravity
  • Compila e implementa en Google Cloud con Antigravity
• Consulta el instructivo oficial del ADK para obtener algunas ideas.