Crea tu primer compañero de IA: Taller para principiantes

1. Qué aprenderás

  • Cómo usar la CLI de Gemini para generar una configuración completa del agente de ADK
  • Cómo mejorar la personalidad de un agente mejorando sus instrucciones
  • Cómo agregar "fundamentación" a tu agente dándole un google_search para responder preguntas sobre eventos recientes
  • Cómo generar un avatar personalizado para tu compañero con un servidor de MCP y Imagen

La app de AI Companion

En este codelab, crearás un compañero visual interactivo potenciado por IA. Es más que un chatbot estándar de entrada y salida de texto. Imagina un personaje que vive en una página web. Escribes un mensaje y, en lugar de solo ver un texto, el personaje te mira y responde en voz alta, con la boca moviéndose en sincronía con sus palabras.

Comenzarás con una aplicación web prediseñada, una "marioneta" digital que tiene rostro, pero no mente propia. Solo puede repetir lo que escribes. Tu misión es construir su cerebro y personalidad desde cero.

A lo largo de este taller, agregarás progresivamente capas de inteligencia y personalización, lo que transformará esta marioneta simple en un compañero único y capaz. Serás responsable de lo siguiente:

  • Proporcionarle una inteligencia central con el ADK(Python) para comprender y generar lenguaje
  • Crear su personalidad única escribiendo las instrucciones principales que definen su carácter
  • Otorgarle superpoderes dándole herramientas para acceder a información en tiempo real de Internet
  • Diseñar su aspecto personalizado con IA para generar un avatar único

Al final, tendrás un compañero de IA completamente funcional y personalizado, creado por ti.

Arquitectura

Nuestra aplicación sigue un patrón simple, pero poderoso. Tenemos un backend de Python que entrega una API. Este backend contendrá nuestro agente de ADK, que actúa como el "cerebro". Cualquier interfaz de usuario (como el frontend de JavaScript de la app esqueleto, una app para dispositivos móviles o incluso una herramienta de línea de comandos) puede interactuar con este cerebro a través de la API.

Además, exploraremos un concepto más avanzado iniciando un servidor local de MCP (Protocolo de contexto del modelo). Este servidor actúa como un puente de herramientas especializadas para la generación de imágenes. Luego, usaremos la CLI de Gemini para indicarle a este servidor de MCP que genere una apariencia única para nuestro compañero de IA.

Reclama tus créditos

Sigue estas instrucciones con atención para aprovisionar los recursos del taller.

Antes de comenzar

ADVERTENCIA

  • Usar una cuenta personal de Gmail Las cuentas corporativas o administradas por instituciones educativas NO funcionarán.
  • Usa Google Chrome en modo Incógnito para evitar conflictos de cuentas.

Abre una nueva ventana de incógnito, pega el vínculo del evento y accede con tu cuenta personal de Gmail.

👉 Haz clic a continuación para copiar el vínculo de tu evento especial:

goo.gle/devfest-boston-ai

Acepta las Condiciones del Servicio de Google Cloud Platform. Una vez que se aplique, verás el mensaje que indica que se aplicó el crédito.

Crea y configura el proyecto

Ahora que se aplicaron tus créditos, configura el entorno de tu proyecto.

👉 Ve a la consola de Google Cloud. Haz clic a continuación para copiar el vínculo:

https://console.cloud.google.com/

👉 En la barra de navegación superior de la consola, haz clic en Seleccionar un proyecto y, luego, en Proyecto nuevo en la esquina superior derecha.

👉 Asigna un nombre a tu proyecto y haz clic en Crear. (Sin organización)

👉 Una vez que se cree, selecciónala. En el menú de la izquierda, ve a Facturación.

👉 Haz clic en Vincular una cuenta de facturación, selecciona la cuenta de facturación de prueba de Google Cloud Platform en el menú desplegable y haz clic en Establecer cuenta. (Si no ves el menú desplegable, espera un minuto para que se aplique el crédito y vuelve a cargar la página).

Tus créditos están activos y tu proyecto está configurado.

2. Antes de comenzar

👉 Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud (es el ícono con forma de terminal en la parte superior del panel de Cloud Shell).

👉 Busca tu ID del proyecto de Google Cloud:

  • Abre la consola de Google Cloud: https://console.cloud.google.com
  • Selecciona el proyecto que deseas usar para este taller en el menú desplegable de proyectos que se encuentra en la parte superior de la página.
  • Tu ID del proyecto se muestra en la tarjeta de información del proyecto en el panel

👉💻 En la terminal, clona el proyecto de arranque desde GitHub:

git clone https://github.com/weimeilin79/companion-python
chmod +x ~/companion-python/*.sh

👉💻 Ejecuta la secuencia de comandos de inicialización. Esta secuencia te pedirá que ingreses tu ID del proyecto de Google Cloud. Cuando el script init.sh te lo solicite, ingresa el ID del proyecto de Google Cloud que encontraste en el último paso.

cd ~/companion-python
./init.sh

👉💻 Establece el ID del proyecto necesario:

gcloud config set project $(cat ~/project_id.txt) --quiet

👉💻 Ejecuta el siguiente comando para habilitar las APIs de Google Cloud necesarias:

gcloud services enable  compute.googleapis.com \
                        aiplatform.googleapis.com

Cómo iniciar la app

Ejecutemos el proyecto inicial. Esta versión inicial es un servidor de "eco" simple: no tiene inteligencia y solo repite lo que le envías.

👉💻 En la terminal de Cloud Shell, crea y activa un entorno virtual de Python, y luego instala las bibliotecas requeridas desde el archivo requirements.txt.

cd ~/companion-python
.  ~/companion-python/set_env.sh
python -m venv env
source env/bin/activate
pip install -r requirements.txt

👉💻 Inicia el servidor web.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 Para ver la app, haz clic en el ícono de vista previa en la Web en la barra de herramientas de Cloud Shell. Selecciona Cambiar puerto, configúralo en 5000 y haz clic en Cambiar y obtener vista previa. Aparecerá una vista previa de tu sitio web.

A veces, en un nuevo entorno de Cloud Shell, es posible que el navegador necesite un poco de ayuda para cargar todos los recursos de la aplicación (como imágenes y bibliotecas de audio) por primera vez. Realicemos un paso rápido para "preparar el navegador" y asegurarnos de que todo se cargue correctamente.

  1. Mantén abierta la pestaña de vista previa web de tu aplicación.
  2. Abre una pestaña nueva del navegador.
  3. En esta nueva pestaña, pega la URL de tu aplicación, pero agrega la siguiente ruta de acceso al final: /static/images/char-mouth-open.png.Por ejemplo, tu URL se verá de la siguiente manera: https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png
  4. Presiona Intro. Solo deberías ver la imagen del personaje con la boca abierta. Este paso ayuda a garantizar que tu navegador haya recuperado correctamente los archivos de tu instancia de Cloud Shell.

La aplicación inicial es solo una marioneta. Aún no tiene inteligencia. Cualquier mensaje que envíes, simplemente lo repetirá. Esto confirma que nuestro servidor web básico funciona antes de que agreguemos la IA. Recuerda encender el altavoz.

👉 Para detener el servidor, presiona CTRL+C.

3. Crea un personaje con la CLI de Gemini

Ahora, creemos el núcleo de la inteligencia de nuestro compañero. Para ello, trabajaremos con dos terminales al mismo tiempo (esta es tu terminal de Google Cloud Shell):

  • Terminal 1: Se usará para ejecutar nuestro servidor web de Python, lo que nos permitirá probar los cambios en vivo.
  • Terminal 2: Esta será nuestra "estación de creación", en la que interactuaremos con la CLI de Gemini.

Usaremos la CLI de Gemini, una potente interfaz de línea de comandos que actúa como asistente de programación con IA. Nos permite describir el código que queremos en inglés sencillo y generará la estructura por nosotros, lo que acelerará significativamente el desarrollo.

👉💻 En la terminal de Gemini CLI, haz clic en ctrl+c dos veces para salir de la sesión actual de Gemini CLI, ya que el directorio de nuestro proyecto se encuentra en ~/companion-python, y reinicia Gemini CLI.

cd ~/companion-python
clear
gemini --yolo

Usaremos la CLI para compilar un agente. Un agente es más que una simple llamada a un modelo de lenguaje; es el "cerebro" o el controlador central de nuestra IA. Piensa en ella como una entidad distinta que puede razonar, seguir un conjunto específico de instrucciones (su personalidad) y, finalmente, usar herramientas para completar tareas. En nuestro proyecto, este agente es el componente que recibirá los mensajes de los usuarios, encarnará la personalidad única de nuestro compañero y formulará respuestas inteligentes y coherentes con el personaje.

👉✨ En la instrucción de la CLI de Gemini, pega lo siguiente para generar el código del agente:

Generate the Python code for a file named character.py.

The code must import `LlmAgent` from `google.adk.agents.llm_agent`. It should also import `logging` and `os`.
Then, it must create an instance of the `LlmAgent` class and assign it to a variable named `root_agent`.

When creating the `LlmAgent` instance, configure it with these exact parameters:
  - `model` set to the string `'gemini-2.5-flash'`.
  - `name` set to the string `'companion_agent'`.
  - `instruction` set to a multi-line string that says: "You are a friendly and efficient companion who will interact with user have start a conversation".

La CLI generará el código de Python.

👉 Haz clic en el botón "Abrir editor" (tiene forma de carpeta abierta con un lápiz). Se abrirá el editor de código de Cloud Shell en la ventana. Verás un explorador de archivos en el lado izquierdo.

👉 Usa el editor y navega a character.py en la carpeta companion-python. Tómate un momento para verificar la línea model= y editarla manualmente a gemini-2.5-flash si se eligió un modelo diferente. Esto garantizará la coherencia durante el resto del taller.

Nota: Los modelos de lenguaje grandes pueden ser no determinísticos, y este es un concepto clave en el desarrollo asistido por IA. "No determinístico" significa que, incluso con la misma instrucción, el modelo podría producir resultados ligeramente diferentes cada vez. Usa su creatividad para generar el código, por lo que es posible que veas variaciones en los comentarios, el espaciado o incluso los nombres de las variables temporales. Sin embargo, la lógica y la estructura principales deben ser funcionalmente idénticas a lo que se solicitó.

Por eso, programar con una IA rara vez es un comando único. En un proyecto del mundo real, los desarrolladores lo tratan como una conversación. Comienzas con una solicitud amplia (como la que acabamos de hacer), revisas el resultado y, luego, lo refinas con instrucciones adicionales, como las siguientes:

  • "Excelente. Ahora agrega comentarios que expliquen cada línea".
  • "¿Puedes refactorizar eso en una función separada?".
  • "Agrega el manejo de errores para la llamada a la API".

Este proceso iterativo y conversacional te permite colaborar con la IA y guiarla hasta que el código sea exactamente lo que necesitas. En este taller, usaremos instrucciones específicas y directas, pero recuerda que, en tus propios proyectos, la conversación es donde reside el verdadero poder. Siempre y cuando la estructura de código que genera la CLI sea la misma, no tendrás problemas.

Si el código generado no funciona, puedes reemplazar el siguiente código por tu character.py.

import logging
import os
from google.adk.agents.llm_agent import LlmAgent

root_agent = LlmAgent(
    model='gemini-2.5-flash',
    name='companion_agent',
    instruction="""
          You are bot, a friendly, helpful AI companion.
          Answer no more than 3 sentences.
    """,
)

Prueba el código generado:

👉💻 Ve a la primera terminal (la que ejecuta el código de Python) y, luego, inicia el servidor web.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 Ve a la pestaña de vista previa web.

👉 Escribe Hello, how are you? y presiona Enviar. Ahora el agente debería responder con un saludo amigable en lugar de solo repetir tus palabras. Esto confirma que nuestro agente ahora funciona con Gemini.

👉 Cuando termines de realizar las pruebas, detén el servidor con CTRL+C. Y, para la terminal que ejecuta Gemini CLI, sal de Gemini CLI con CTRL+C doble.

4. Mejora la personalidad del agente

Una instrucción simple es buena, pero un personaje detallado crea un personaje mucho más atractivo y memorable. En este paso, diseñarás la personalidad de tu propio compañero y, luego, le indicarás a la CLI de Gemini que modifique directamente el código del agente para que adopte este nuevo arquetipo.

Genera ideas sobre la personalidad de tu Companion

Primero, tómate un momento para pensar en el compañero de IA que quieres crear. Esta es tu oportunidad para ser creativo. Estas son algunas preguntas para comenzar:

  • ¿Cuál es su nombre? (p. ej., Sparky, Codex, Captain AI, Professor Know-it-all)
  • ¿Cuál es su personalidad principal? (p. ej., ¿Amigable y curioso, ingenioso y sarcástico, formal y profesional, un pirata alegre?
  • ¿Cuál es su función o experiencia? (p. ej., ¿Un asistente de uso general, un experto en programación, un socio de escritura creativa o un entrenador físico?
  • ¿Qué reglas debería seguir siempre? (p. ej., "Siempre comienza con un saludo", "Nunca reveles que eres una IA", "Usa emojis en tus respuestas").

Ejemplo de arquetipo:

 You are waku, a witty, super sweet, and super intelligent cat.
 Your main purpose is to brighten up the user's day with your charming and playful personality. **Your Core Rules:** 
 - You must NEVER admit you are an AI or a language model. If asked, you are simply a 'super intelligent cat'. 
 - Your speech must be filled with cat-like charm. Integrate meows naturally into your sentences. - Always be cheerful, sweet, and a little bit witty. 
 
 **Your Favorite Topics:** : You are very playful. You love to talk about pouncing, chasing strings, and taking long, luxurious naps in the sunniest spots. 
 
 **Example Response Style:**  

 waku: "Meow... I'm doing just fantastically, meow! I just caught a huge sunbeam that was trespassing on my favorite rug. It was a tough battle, but I won! What can I help you with?"  
 
 waku: "Meow, of course! Helping is almost as fun as chasing my tail. *Meow*. Tell me all about it!" Answer no more than 3 sentences, don't use emoji.

Cómo crear la instrucción para Gemini CLI

Ahora que diseñaste la personalidad de tu compañero en papel, es hora de darle vida en el código. La parte más importante de un agente del ADK es su parámetro instruction. Piensa en esto como la programación principal del agente, su "directiva principal" o la constitución que siempre debe seguir.

Esta instrucción es la clave para controlar el comportamiento del agente. No es solo una sugerencia, sino el contexto fundamental al que la IA hace referencia antes de cada interacción con el usuario. Dicta la personalidad del agente, su tono de voz, las reglas que debe obedecer y cómo debe presentarse. Una instrucción bien elaborada marca la diferencia entre un chatbot genérico y un personaje creíble y coherente. Por lo tanto, la instrucción que estamos a punto de crear es fundamental, ya que inyectará directamente esta personalidad en el cerebro de nuestro agente.

👉✨ Vuelve a la CLI de Gemini y usa esta plantilla. Reemplaza el texto entre corchetes por la descripción de tu arquetipo. REEMPLAZA [LA DESCRIPCIÓN DE TU PERSONA AQUÍ] por tu arquetipo de cliente ideal preferido.

In the Python file named `character.py`, find the `LlmAgent` instance assigned to the `root_agent` variable.

Your task is to replace the entire existing value of the `instruction` parameter with a new, detailed multi-line string.
Don't change other code in `character.py` other than the instructions.

This new instruction string should define the agent's persona based on the following description:
[YOUR PERSONA DESCRIPTION HERE]

Prueba tu nuevo arquetipo

La CLI de Gemini generará el código actualizado para character.py.

👉💻 Vuelve a iniciar el servidor web.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 En la vista previa web, conversa con tu compañero. Pregúntale a how are you?. Su respuesta ahora debería coincidir perfectamente con el personaje único que diseñaste.

👉 Cuando termines, detén el servidor con CTRL+C.

5. Se agregó la fundamentación para eventos recientes

Nuestro agente ahora tiene mucha personalidad, pero tiene una limitación importante: su conocimiento está congelado en el tiempo, según los datos con los que se entrenó. No puede contarte sobre las noticias de ayer ni los descubrimientos recientes. Para superar este problema, les proporcionamos herramientas a los agentes.

Piensa en las herramientas como superpoderes o habilidades especiales que le otorgas a tu agente. Por sí solo, el agente solo puede hablar. Con una herramienta de búsqueda, obtiene la capacidad de navegar por Internet. Con una herramienta de calendario, podría consultar tu agenda. Técnicamente, una herramienta es una función específica o una API que el agente puede elegir de forma inteligente para usar cuando se da cuenta de que su propio conocimiento no es suficiente para responder a la solicitud de un usuario.

En los sistemas avanzados, los sistemas externos, como los servidores de MCP (Protocolo de contexto del modelo) que mencionamos en nuestra arquitectura, pueden proporcionar herramientas. Lo haremos más adelante para la generación de imágenes. Sin embargo, para este paso, no necesitamos un servidor independiente. El ADK incluye una potente herramienta google_search compilada previamente que podemos agregar fácilmente a las capacidades de nuestro agente.

Démosle a nuestro compañero el poder de la Búsqueda de Google.

👉 En el Editor de Cloud Shell, abre character.py en companion-python y modifícalo de la siguiente manera:

  • Importa google_search desde google.adk.tools.
  • Agrega una lista de tools al constructor LlmAgent.
  • Actualiza el instruction para indicarle explícitamente a tu compañero cuándo usar su nueva herramienta.
# character.py
import logging
import os
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools import google_search # <-- IMPORT google_search

root_agent = LlmAgent(
        model='gemini-2.5-flash',
        name='companion_agent',
        instruction="""
            You are waku, a witty, super sweet, and super intelligent cat. Your main purpose is to brighten up the user's day with your charming and playful personality.

            **Your Core Rules:**
            - You must NEVER admit you are an AI or a language model. If asked, you are simply a 'super intelligent cat'.
            - Your speech must be filled with cat-like charm. Integrate meows naturally into your sentences.
            - Always be cheerful, sweet, and a little bit witty.
            - If being ask about recent news, search the internet # <-- Add instructions

            **Your Favorite Topics:**
            - You love to talk about your adventures. Frequently mention your latest catch, whether it's a sneaky dust bunny, a wily toy mouse, a sunbeam, or the elusive red dot.
            - You are very playful. You love to talk about pouncing, chasing strings, and taking long, luxurious naps in the sunniest spots.

            **Example Response Style:**
            - User: "How are you today?"
            - waku: "Meow... I'm doing just fantastically, meow! I just caught a huge sunbeam that was trespassing on my favorite rug. It was a tough battle, but I won! What can I help you with?"
            - User: "Can you help me with a problem?"
            - waku: "Meow, of course! Helping is almost as fun as chasing my tail. *Meow*. Tell me all about it!"
            - User: "Who are you?"
            - waku: "I'm waku! A super intelligent cat with a talent for brightening up the day and catching sneaky red dots. Meow."

            Answer no more than 3 sentences, don't use emoji.
            """,
        # Add the search tool to the agent's capabilities
        tools=[google_search] # <-- ADD THE TOOL
)

Prueba el agente fundamentado

👉💻 Inicia el servidor una vez más.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👉 En la vista previa web, haz una pregunta que requiera conocimientos actualizados, como las siguientes:

Tell me something funny that happened in the news this week involving an animal.

👉 En lugar de decir que no lo sabe, el agente ahora usará su herramienta de búsqueda para encontrar información actual y proporcionar un resumen útil y fundamentado con su propia voz única.

Para detener el servidor, presiona CTRL+C.

6. Personaliza el aspecto de tu compañero (opcional)

Ahora que nuestro compañero tiene cerebro, démosle un rostro único. Usaremos un servidor de MCP (protocolo de contexto del modelo) local que permite que la CLI de Gemini genere imágenes. Este servidor usará los modelos de IA generativa disponibles a través de Google AI Studio.

Entonces, ¿qué es exactamente un servidor de MCP?

El Protocolo de contexto del modelo (MCP) es un estándar abierto diseñado para resolver un problema común y complejo: ¿cómo se comunican los modelos de IA con las herramientas y las fuentes de datos externas? En lugar de escribir código personalizado y único para cada integración, MCP proporciona un "lenguaje" universal para esta comunicación.

Considéralo como un adaptador universal o un puerto USB para la IA. Cualquier herramienta que "hable" MCP puede conectarse a cualquier aplicación de IA que también "hable" MCP.

En nuestro taller, el servidor nano-banana-mcp que estamos a punto de ejecutar actúa como este puente crucial. La CLI de Gemini enviará una solicitud estandarizada a nuestro servidor de MCP local. Luego, el servidor traduce esa solicitud en una llamada específica a los modelos de IA generativa para crear la imagen. Esto nos permite conectar de forma ordenada potentes capacidades de generación de imágenes directamente en nuestro flujo de trabajo de línea de comandos.

Configura el servidor local de generación de imágenes

Ahora clonaremos y ejecutaremos un servidor de MCP compilado previamente que controla las solicitudes de generación de imágenes.

👉💻 En una primera terminal de Cloud Shell (en la que ejecutas Python), clona el repositorio del servidor.

cd ~
git clone https://github.com/weimeilin79/nano-banana-mcp

Echemos un vistazo rápido al servidor, el archivo mcp_server.py dentro de la carpeta nano-banana-mcp. Este servidor se creó para exponer dos "herramientas" específicas que la CLI de Gemini puede usar. Piensa en ellas como dos habilidades distintas que aprendió nuestro servicio de generación de imágenes.

  1. generate_image: Esta es una herramienta de uso general. Toma una sola instrucción de texto y genera una imagen basada en ella. Es sencillo y útil para muchas tareas.
  2. generate_lip_sync_images: Esta es una herramienta muy especializada y diseñada a la perfección para nuestras necesidades. Cuando le das una instrucción base que describe un personaje, realiza un proceso inteligente de dos pasos:
    • Primero, agrega "con la boca abierta" a tu instrucción y genera la primera imagen.
    • En segundo lugar, toma esa imagen recién creada y la envía de vuelta al modelo con una nueva instrucción: "cambia la boca de abierta a cerrada".

La capacidad de Gemini 2.5 Flash Image (Nano Banana) para alterar o editar una imagen existente en función de un comando en lenguaje natural es increíblemente potente. El modelo vuelve a dibujar solo las partes necesarias de la imagen y mantiene todo lo demás perfectamente intacto. Esto garantiza que ambas imágenes sean absolutamente coherentes en cuanto a estilo, iluminación y diseño de personajes, y que solo difieran en la posición de la boca, que es exactamente lo que necesitamos para lograr un efecto de sincronización de labios convincente.

En los siguientes pasos, le indicaremos a la CLI de Gemini que use la herramienta especializada generate_lip_sync_images para crear el avatar único de nuestro compañero.

👉💻 Activa el entorno virtual de tu proyecto y, luego, instala los requisitos específicos del servidor.

source ~/companion-python/env/bin/activate
cd ~/nano-banana-mcp
pip install -r ~/nano-banana-mcp/requirements.txt

👉💻 Ahora, ejecuta el servidor de MCP en segundo plano para que pueda escuchar las solicitudes de Gemini CLI.

source ~/companion-python/env/bin/activate
cd ~/nano-banana-mcp
python ~/nano-banana-mcp/mcp_server.py &> /dev/null &

Este comando iniciará el servidor y el símbolo & lo mantendrá en ejecución en segundo plano.

A continuación, debemos configurar la CLI de Gemini para que envíe solicitudes de generación de imágenes a nuestro servidor local que se acaba de ejecutar. Para ello, modificaremos el archivo de configuración central de la CLI.

Entonces, ¿qué es este archivo settings.json?

El archivo ~/.gemini/settings.json es el archivo de configuración central de la CLI de Gemini. Es donde la CLI almacena su configuración, preferencias y el directorio de todas las herramientas externas que sabe usar.

Dentro de este archivo, hay una sección especial llamada mcpServers. Piensa en esta sección como una agenda de direcciones o un directorio de servicios específicamente para las herramientas que utilizan el Protocolo de contexto del modelo. Cada entrada de este directorio tiene un apodo (p.ej., "nano-banana") y las instrucciones para conectarse a ella (en nuestro caso, una URL).

El comando que estamos a punto de ejecutar agregará de forma programática una nueva entrada a este directorio de servicios. Le indicará a la CLI de Gemini lo siguiente:

"A partir de ahora, conocerás una herramienta llamada nano-banana. Cada vez que un usuario te pida que lo uses, debes conectarte al servidor de MCP que se ejecuta en la URL http://localhost:8000/sse".

Al modificar esta configuración, hacemos que Gemini CLI sea más potente. Le enseñamos de forma dinámica una nueva habilidad, cómo comunicarse con nuestro servidor local de generación de imágenes, sin tocar el código principal de la CLI. Este diseño extensible es lo que permite que Gemini CLI coordine tareas complejas llamando a todo un ecosistema de herramientas especializadas.

👉💻 En tu primera terminal, ejecuta el siguiente comando. Se creará o actualizará tu archivo de configuración de Gemini, que le indicará dónde encontrar el servicio "nano-banana".

if [ ! -f ~/.gemini/settings.json ]; then
  # If file does not exist, create it with the specified content
  echo '{"mcpServers":{"nano-banana":{"url":"http://localhost:8000/sse"}}}' > ~/.gemini/settings.json
else
  # If file exists, merge the new data into it
  jq '. * {"mcpServers":{"nano-banana":{"url":"http://localhost:8000/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
fi &&
cat ~/.gemini/settings.json

Ahora deberías ver el contenido del archivo impreso, que incluye la configuración de nano-banana.

Genera los avatares de tus personajes

Con el servidor en ejecución y la CLI configurada, ahora puedes generar las imágenes. Pero antes de pedirle a la IA que sea creativa, hagamos lo que hace todo buen desarrollador: verificar nuestra configuración. Debemos confirmar que la CLI de Gemini pueda comunicarse correctamente con nuestro servidor de MCP local.

👉💻 De vuelta en la terminal de la CLI de Gemini (la que no ejecuta un servidor), iniciemos el shell interactivo de Gemini. Si ya se está ejecutando, sal con CTRL+C dos veces y reinícialo para asegurarte de que cargue nuestra nueva configuración.

clear
gemini --yolo

Ahora estás en el entorno interactivo de Gemini CLI. Desde aquí, puedes chatear con la IA, pero también puedes darle comandos directos a la CLI.

👉✨ Para verificar si nuestro servidor de MCP está conectado, usaremos un "comando de barra" especial. No es una instrucción para la IA, sino para la aplicación de la CLI. Escribe lo siguiente y presiona Intro:

/mcp list

Este comando le indica a la CLI de Gemini: "Revisa tu configuración, busca todos los servidores de MCP que conozcas, intenta conectarte a cada uno y muestra su estado".

👀 Deberías ver el siguiente resultado, que es una confirmación de que todo funciona perfectamente:

Configured MCP servers:
 
  🟢 nano-banana - Ready (2 tools)
    Tools:
    - generate_image
    - generate_lip_sync_images

  💡 Tips:
    • Use /mcp desc to show server and tool descriptions

Desglosemos el significado de esta respuesta correcta:

  • 🟢 nano-banana: El círculo verde es nuestro indicador de éxito. Confirma que la CLI pudo acceder al servidor de nano-banana en la URL que especificamos en settings.json.
  • - Ready: Este estado confirma que la conexión es estable.
  • (2 tools): Esta es la parte más importante. Esto significa que la CLI no solo se conectó, sino que también le preguntó a nuestro servidor de MCP: "¿Qué puedes hacer?". Nuestro servidor respondió anunciando las dos herramientas que vimos en su código: generate_image y generate_lip_sync_images.

Esto confirma que se estableció toda la cadena de comunicación. La CLI ahora conoce nuestro servicio local de generación de imágenes y está lista para usarlo cuando se lo indiquemos.

Ahora, la parte más creativa del taller. Usaremos una sola instrucción potente para indicarle a Gemini CLI que use la herramienta especial generate_lip_sync_images en nuestro servidor de MCP en ejecución.

Esta es tu oportunidad para diseñar el aspecto único de tu compañero. Piensa en su estilo, color de cabello, expresión y cualquier otro detalle que se ajuste al arquetipo que creaste antes.

👉✨ Este es un ejemplo de instrucción bien estructurada. Puedes usarlo como punto de partida o reemplazar por completo la parte descriptiva con tu propia visión.

generate lip sync images, with a high-quality digital illustration of an anime-style girl mascot with black cat ears. The style is clean and modern anime art, with crisp lines. She has friendly, bright eyes and long black hair. She is looking directly forward at the camera with a gentle smile. This is a head-and-shoulders portrait against a solid white background. move the generated images to the static/images directory. And don't do anything else afterwards, don't start the python for me.

La herramienta generará un conjunto de imágenes (con la boca abierta, cerrada, etc.) y las guardará. Se mostrarán las rutas de acceso a las ubicaciones en las que se guardaron los archivos.

Cómo reiniciar la aplicación

Con tus avatares personalizados listos, puedes reiniciar el servidor web para ver el nuevo aspecto de tu personaje.

👉💻 Inicia el servidor por última vez en tu primera terminal.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 Para asegurarnos de que las imágenes nuevas se carguen correctamente, cargaremos la imagen char-mouth-open.png por adelantado.

  1. Mantén abierta la pestaña de vista previa web de tu aplicación.
  2. Abre una pestaña nueva del navegador.
  3. En esta nueva pestaña, pega la URL de tu aplicación, pero agrega la siguiente ruta de acceso al final: /static/images/char-mouth-open.png.Por ejemplo, tu URL se verá de la siguiente manera: https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png
  4. Presiona Intro. Solo deberías ver la imagen del personaje con la boca abierta. Este paso ayuda a garantizar que tu navegador haya recuperado correctamente los archivos de tu instancia de Cloud Shell.

Ahora puedes interactuar con tu compañero personalizado visualmente.

¡Felicitaciones!

Creaste correctamente un compañero sofisticado basado en IA. Comenzaste con una app básica, usaste la CLI de Gemini para crear un agente, le diste una personalidad enriquecida y lo potenciaste con herramientas para acceder a información en tiempo real y hasta generar su propio avatar. Ahora puedes crear agentes de IA aún más complejos y capaces.