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

1. Introducción

Última actualización: 2026-02-02

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

Te damos la bienvenida a este taller de ADK en Python(*), que incluye baterías gracias a Gemini CLI.

Este codelab se divide en dos 🏅 hitos:

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

La segunda parte hace que este codelab sea perfecto para un hackathon (¡y premios para las soluciones más creativas!).

Hito 1: Tu primer agente con ADK y Gemini CLI

El objetivo de este hito es compilar un agente de viajes simple con el ADK paso a paso.

Para ello, primero configuraremos la CLI de Gemini para que nos ayude a programar con el ADK. Esto hará que tu shell local pueda elegir la versión más reciente del ADK de Python, interpretar el código y la documentación, y proporcionar el código más reciente o mejor para trabajar con él en función de tu objetivo.

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

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

Logro 2: Extiende tu agente

Después de eso, te brindamos una docena de opciones (de dificultad variable) para que extiendas la app a tu gusto. Esto te permite explorar diferentes aspectos (IU, operaciones, interacciones complejas con el agente, etc.).

Qué compilarás

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

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

Gemini CLI te guiará en todo este proceso: escribir o revisar código y encontrar la documentación más reciente en una duplicación local del repo del ADK (en Python o tu lenguaje favorito).

Qué aprenderás

• Cómo crear una app con 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 de programación básica en Python, TypeScript, Go o Java
• Se recomienda encarecidamente usar un IDE ( Antigravity, VSCode, IntelliJ, 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 local basado en agentes (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 no lo lograron (principalmente debido a problemas de "bucle dentro de un bucle"). En este codelab, se intentan compartir algunas sugerencias para que esta coexistencia sea posible.

2. Cómo prepararte

Para obtener créditos de Google Cloud: Para ayudarte a comenzar, canjea tus créditos gratuitos de Google Cloud con este vínculo ( instrucciones).

Elige una de las siguientes opciones: Configuración del entorno a su propio ritmo si deseas ejecutar este

codelab en tu propia máquina, o inicia Cloud Shell si deseas ejecutar este codelab por completo en la nube.

Configuración del entorno de autoaprendizaje

1. Accede a Google Cloud Console 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 Google Cloud Console, 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 de desarrollo que necesitarás. 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.

Requisitos previos (instalación)

Nota: Si decides ejecutar este codelab en Cloud Shell, python, uv y la CLI de Gemini ya estarán preinstalados, pero deberás instalar just si quieres usarlo.

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 instalado uv:

$ 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 igual para ti y para Gemini CLI, por lo que tu experiencia de 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

En el caso de Gemini CLI, puedes encontrar las instrucciones de instalación aquí: https://github.com/google-gemini/gemini-cli .

Nota: Esto requiere que tengas instalado npm o npx.

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 archivo 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 natural de Gemini CLI. Si no es así, pídele ayuda a Gemini CLI aquí.

De manera opcional, también puedes instalar just, que es un Makefile más avanzado y con documentación propia. También puedes pedirle a Gemini CLI que te ayude a instalarlo.

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.) y abrir la carpeta.

# 1. Find an empty directory, and download this repo.
git clone https://github.com/palladius/ai-friendly-agents/
cd ai-friendly-agents/adk/workshops/simple-travel-agent/

# 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 sync

# 4. Call Gemini CLI
gemini  # This runs Gemini CLI under the simple-travel-agent/ folder.
# Login with your GMail account.

uv sync no es estrictamente necesario, pero, si falla, sabrás que debes corregir la instalación de Python o uv.

Importante. Asegúrate de ejecutar Gemini CLI desde la carpeta 📁 simple-travel-agent/. Además, el IDE debería mostrarte esto como nombre raíz. Esto garantiza que Gemini CLI tome la configuración correcta. Siempre puedes agregar carpetas externas a través de /dir add /your/other/folder, pero 📁 simple-travel-agent/ 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 buen código del ADK, sino de configurar tu entorno para que se escriba BUEN código automáticamente bajo tu dirección.

1. Instala el software
2. configurarlo o hacerlo funcionar
3. Ingresar a un ciclo de retroalimentación justo

Esto es lo que realmente queremos que aprendas aquí. También puedes probarlas todas al mismo tiempo con $ just web-4steps.

3. 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 y agrega el siguiente contenido:

from .agent import root_agent

Es así de simple. Esto permite que el ADK sepa dónde está tu código: en agent.py.

Edita el archivo llamado mysolution/agent.py y agrega 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: CLI y Web.

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

Nota: Para los fines de este ejercicio, y para lograr cualquier objetivo (excepto las pruebas de unidades), usa la Web. ¡Es 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 la siguiente (instrucción "prueba de fuego" inteligente):

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

1. Dime qué día de la semana y qué fecha (AAAAMMDD) es mañana.
2. Dime qué hoteles ves para mañana (al menos 3). Quiero ver: > precio, dirección, alguna calificación (en formato XX/YY, p. ej., "4.7/5" de Google Hotels, Booking o Airbnb) y la cantidad de opiniones. Bríndame los datos en formato TABULAR. Lo ideal sería 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 la hora y los hoteles, y fallará de manera diferente en los pasos 1, 2 y 3, y solo debería tener éxito por completo en el paso 4. Por supuesto, puedes usar cualquier instrucción que 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 "pregunta de prueba" anterior.

Es probable que no pueda determinar fechas específicas. Tenemos que enseñarle a conocer 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 parte superior derecha (consulta la imagen junto a este texto).
3. Haz tu pregunta por texto o con el micrófono, algo similar a la "pregunta de prueba".

TODO(ricc): <imagen aquí>

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

Aquí tienes una posible solución, con una semialucinación de fecha. Nota: 3 de los 5 vínculos para reservar funcionan. Bastante bien.

4. Paso 2: Agrega la herramienta now()

El agente no sabe qué es "hoy". Démosle una herramienta.

TODO(imagen): ricc coloca aquí la imagen del paso 2.

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

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

Vuelve a ejecutarla 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 lo siguiente:

# 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/

5. Paso 3: Cambiemos de tema: google_search

Ahora que sabemos cómo crear una herramienta personalizada, exploremos cómo usar una de las potentes herramientas integradas que proporciona el ADK: google_search. Esto permite que nuestro agente acceda a información en tiempo real de la Web.

Nota: 🚨 Los modelos de gemini-2.x no pueden combinar de forma nativa la Búsqueda de Google con herramientas personalizadas (consulta el problema núm. 969), por lo que reemplazaremos now() por google_search para simplificar. 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 del 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 para expertos. Para una integración más avanzada (con google_search y now juntos), consulta el código en steps/step03b_search_and_tool/agent.py y ejecútalo con just run-step3b. Esto es totalmente opcional.

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

TODO(ricc): add image 4

Ahora que vimos las herramientas personalizadas y las integradas, pasemos a algo más potente: el patrón Modelo como herramienta 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 presentar 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

Este paso requiere que npx esté instalado en tu sistema. Para el resto, es igual 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 de 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 demasiado poco para que Airbnb obtenga respuestas), consulta la documentación del ADK para aumentar el tiempo de espera a, por ejemplo, 30 segundos. O bien usa Gemini CLI para hacerlo. Ten en cuenta que, el 3 de diciembre a las 25 min, Cloud Shell me dio un error de tiempo de espera. Lo corregí, pero seguí recibiendo errores hasta que lo forcé a la versión anterior: args=["-y", "@openbnb/mcp-server-airbnb@0.1.2", "--ignore-robots-txt"].

7. 🏅 ¡Se completó el hito 1!

🏅 ¡Felicitaciones! 🏅 ¡Ahora eres 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 avanzadas de MCP. Ahora puedes crear tus propios agentes increíbles con el Kit de desarrollo de agentes de Google.

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

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

8. 🏅 Hito 2: Vibe coding con el ADK a través de la CLI de Gemini

Ahora, ingresamos a la parte interesante del taller.

1. asegúrate de haber git commitdo 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. Encuentra una 💡 idea para implementar. Puedes consultar las ideas a continuación, buscar una por tu cuenta o pedirle a Gemini que revise la documentación en rag/ y proponga algunas ideas inteligentes.
3. Sigue los requisitos previos para asegurarte de que Gemini pueda leer la documentación del ADK y, luego, podrás comenzar.

💡 Ideas

Este es un menú con algunas ideas de diferente complejidad.

1. 🟢 [Fácil] ¿Hablas varios idiomas? ¿Quieres dar go, java o Typescript? Refactorizar el código existente es muy simple. Solo asegúrate de descargar el ADK adecuado y pídele a Gemini CLI que realice la traducción.
2. 🟢 [Fácil] Agrega emojis o especifica el formato de salida que prefieras (p. ej., una tabla con el emoji de un hotel, seguido del precio y de emojis de 1 a 5 estrellas, con 🌕🌕🌕🌗🌑 para hacer mitades también).
3. 🟢 [Fácil] Cambia la instrucción para enseñarle cosas que buscas o que no buscas específicamente (admite mascotas, no está en la planta baja, es silencioso, está cerca del transporte público, etc.) y pruébala. Quizás puedas agregar una calificación personal, como "una calificación de YOUR_NAME del 1 al 10" basada en lo anterior, y ordenar los resultados según esa calificación.
4. 🟢 [Fácil] ¿Hay algún operador en la sala? Implementa en Cloud Run. O bien 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 la siguiente variante más difícil.
6. 🟡 [Medio] Crea un subagente que haga HotelSearch y cree un BudgetAgent o un LocationAgent que pueda profundizar y realizar iteraciones sobre 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 GoogleSearch ayude con algunas idas y vueltas. 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 color 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. 🟡 [Medio] Integración con A2A. ¡Conviértelo en un agente A2A! Nuevamente, pídele ayuda a Gemini CLI.
9. 🔴 [Complejo] Puedes integrar Vuelos o cualquier otra función de MCP para crear un agente de viajes multifacético y multifuncional.
10. 🔴 [Complejo] Integra la Web del ADK con 🍌 NanoBanana MCP. Este es más difícil que el 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 documentación y código de rag/.

¿Buscas más inspiración?

1. Consulta el excelente instructivo de ADK de Maurizio 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" del ADK

Para programar una función con vibe, te recomendamos que descargues todo el ADK ADK de Python (nota: 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 que se ignoran de forma segura con Git. Técnicamente, también podrías mostrar todos los archivos .gitignore estableciendo context.fileFiltering.respectGitIgnore en 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.

9. Próximos pasos

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

Lecciones aprendidas

Aprendimos a vincular el ADK con Gemini CLI

Lecturas adicionales

• Consulta estos dos increíbles codelabs de Antigravity de Romin y Mete:
• Primeros pasos con Google Antigravity
• Cómo crear con Google Antigravity
• Compila e implementa en Google Cloud con Antigravity
• Consulta el excelente instructivo de ADK de Maurizio para obtener algunas ideas.