Taller para principiantes sobre la CLI y el ADK de Antigravity (crea tu primer asistente de IA)

1. Qué aprenderás

• Cómo instalar y registrar una habilidad para la CLI de Antigravity y habilitar las capacidades de programación en un framework específico (ADK)
• Cómo usar la CLI de Antigravity 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

La app de AI Companion

En este codelab, darás vida a 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 crear 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 eficaz. Tenemos un backend de Python que entrega una API. Este backend contendrá nuestro agente del 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 de esto, aprovecharemos las capacidades de generación de imágenes integradas en la CLI de Antigravity y le indicaremos que genere un aspecto único para nuestro compañero de IA.

Obtén una clave de API de Gemini

Antes de continuar, necesitas una clave de la API de Gemini para autenticar tus solicitudes con Google AI Studio.

1. Navega a Google AI Studio.
2. Accede con tu Cuenta de Google.
3. Haz clic en el botón Obtener clave de API en el menú de la parte superior izquierda.
4. Haz clic en Crear clave de API (puedes crearla en un proyecto de Google Cloud nuevo o existente).
5. Copia la clave generada. Mantén esta clave privada y segura.

Crea y configura el proyecto

Para acceder a Cloud Shell, seguirás necesitando un proyecto de Google Cloud. Si no tienes uno, haz lo siguiente:

1. Ve a la consola de Google Cloud.
2. 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.
3. Asigna un nombre al proyecto y haz clic en Crear. (No se requiere organización).
4. Una vez que se cree el proyecto, selecciónalo en el menú desplegable de proyectos en la parte superior de la consola.

Tu proyecto ahora está configurado para el acceso a Cloud Shell.

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

👉💻 Instala la CLI de Antigravity en la terminal de Cloud Shell:

curl -fsSL https://antigravity.google/cli/install.sh | bash

👉💻 Para usar la CLI de "agy" de forma global, agrégala a tu perfil de shell:

echo 'export PATH="~/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

👉💻 Exporta tu clave de API de Gemini y guárdala de forma local en la terminal de Cloud Shell:

# Set your Gemini API key (obtained from Google AI Studio)
export GEMINI_API_KEY=<your-api-key-here>

👉💻 Guárdalo para usarlo más adelante:

echo $GEMINI_API_KEY > ~/gemini_key.txt

👉 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 (solo se necesita Compute Engine para la vista previa o el alojamiento de Cloud Shell):

gcloud services enable compute.googleapis.com

Instala la skill para desarrolladores del ADK

Para permitir que la CLI de Antigravity (agy) comprenda y escriba código con el Kit de desarrollo de agentes (ADK) de Python, debemos instalar la habilidad de desarrollador de Python del ADK que creamos en el espacio de trabajo del proyecto.

👉💻 Crea el directorio de habilidades del agente local y copia el archivo de habilidad:

mkdir -p ~/companion-python/.agents/skills/adk-python
cp ~/companion-python/skills/skill.md ~/companion-python/.agents/skills/adk-python/SKILL.md

Esto registra la habilidad de forma local dentro del proyecto. Cuando inicies agy, detectará y cargará automáticamente esta habilidad, lo que le permitirá escribir, editar y coordinar agentes del ADK.

👉💻 Inicia la CLI de Antigravity en tu terminal de Cloud Shell:

cd ~/companion-python
agy

[!IMPORTANTE] Acceso a la CLI de Antigravity

Cuando ejecutes el comando agy por primera vez, se te pedirá que accedas:

Welcome to the Antigravity CLI. You are currently not signed in.

 Select login method:
 > 1. Google OAuth
   2. Use a Google Cloud project

1. Elige la opción 1. OAuth de Google presionando Enter.
2. Sigue las instrucciones para abrir el navegador, autenticarte con tu Cuenta de Google y acceder.

Ahora estás en la instrucción interactiva de la CLI de Antigravity.

Inicia el servidor web a través de la CLI de Antigravity

Dado que la CLI de Antigravity puede ejecutar comandos por ti, pidámosle que ejecute el servidor en segundo plano de tu sesión.

👉✨ En la instrucción de la CLI de Antigravity, pega la siguiente solicitud:

Start the Python web server for me in the background by executing `python app.py`. Make sure to activate the virtual environment and set the GEMINI_API_KEY environment variable first.

Presiona Intro para aprobar la solicitud de agy para escribir el archivo.

La CLI ejecutará el comando y confirmará que el servidor está en ejecución. Permanecerás en la sesión interactiva de la CLI.

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

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.

3. Crea un personaje con la CLI de Antigravity

Ahora, crearemos el núcleo de la inteligencia de nuestro compañero. Dado que la CLI de Antigravity ya se está ejecutando en tu terminal y administra el servidor web en segundo plano, puedes continuar directamente en tu sesión interactiva.

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 él 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 Antigravity, 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-3.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".

Presiona Intro para aprobar la solicitud de agy para escribir el archivo.

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-3.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 de seguimiento 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-3.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

Para asegurarnos de que el servidor cargue el módulo character.py recién generado, le pediremos a la CLI de Antigravity que reinicie el servidor web.

👉✨ En la instrucción de la CLI de Antigravity, pega la siguiente solicitud:

Please restart the Python web server for me.

Presiona Intro para aprobar la solicitud de agy para escribir el archivo.

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

👉 Tipo:

Hello, how are you?

y presiona Enviar. Ahora, el agente debería responder con un saludo amable en lugar de solo repetir tus palabras. Esto confirma que nuestro agente ahora funciona con Gemini.

4. Mejora la personalidad del agente

Una instrucción simple es buena, pero una personalidad detallada 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 Antigravity que modifique directamente el código del agente para que adopte esta nueva personalidad.

Intercambia 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 la CLI de Antigravity

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.

👉✨ De vuelta en la CLI de Antigravity, 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]

Presiona Intro para aprobar la solicitud de agy para escribir el archivo.

Prueba tu nuevo arquetipo

La CLI de Antigravity generará el código actualizado para character.py. Para asegurarnos de que el servidor recoja la nueva configuración del agente, le pediremos a la CLI de Antigravity que lo reinicie.

👉✨ En la instrucción de la CLI de Antigravity, pega la siguiente solicitud:

Please restart the Python web server for me.

Presiona Intro para aprobar la solicitud de agy para escribir el archivo.

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

Agrega el control de reintentos para los límites de frecuencia de la API (opcional, pero recomendado)

Durante los talleres o los períodos de uso simultáneo alto, es posible que se produzcan errores de límite de frecuencia de la API (HTTP 429: Recurso agotado). Para garantizar que tu compañero siga respondiendo y controle las excepciones de límite de frecuencia automáticamente, podemos configurar opciones de reintento integradas directamente en las opciones del cliente del SDK de GenAI de Google.

👉✨ En la instrucción de la CLI de Antigravity, pega la siguiente solicitud:

Help me configure the LlmAgent in character.py to automatically retry API calls when hitting rate limits. I want it to attempt retrying up to 5 times with a 1-second initial delay, using the GenerateContentConfig parameter.

Presiona Intro para aprobar la solicitud de agy para escribir el archivo.

La CLI modificará tu archivo character.py para controlar los límites de frecuencia automáticamente con políticas de reintentos a nivel del cliente. Recuerda pedirle a la CLI que reinicie el servidor web después de actualizar el archivo:

Please restart the Python web server for me.

Presiona Intro para aprobar la solicitud de agy para escribir el archivo.

5. Agrega 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), pueden proporcionar herramientas. Sin embargo, para este paso, no necesitamos un servidor independiente. El ADK incluye una potente herramienta google_search prediseñada 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.genai import types
from google.adk.tools import google_search # <-- IMPORT google_search

root_agent = LlmAgent(
        model='gemini-3.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.
            """,
        generate_content_config=types.GenerateContentConfig(
          http_options=types.HttpOptions(
            retry_options=types.HttpRetryOptions(
                attempts=5,
                initial_delay=1.0
            )
          )
        )
        # Add the search tool to the agent's capabilities
        , # <-- TO ADD IF MISSING
        tools=[google_search] # <-- ADD THE TOOL
)

Prueba el agente fundamentado

Para asegurarte de que el servidor web cargue tu código nuevo con la herramienta google_search, pídele a la CLI de Antigravity que lo reinicie.

👉✨ En la instrucción de la CLI de Antigravity, pega la siguiente solicitud:

Please restart the Python web server for me.

Presiona Intro para aprobar la solicitud de agy para escribir el archivo.

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

6. Personaliza el aspecto de tu acompañante

Ahora que nuestro compañero tiene cerebro, démosle un rostro único. Dado que la CLI de Antigravity está equipada con capacidades de generación de imágenes listas para usar, puedes pedirle directamente que genere los avatares por ti.

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

👉✨ En la instrucción de la CLI de Antigravity, pega la siguiente solicitud (puedes modificar la instrucción con tu propia descripción creativa del personaje):

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.

Presiona Intro para aprobar la solicitud de agy para escribir el archivo.

La herramienta generará el conjunto de imágenes con la boca abierta y cerrada, y las guardará automáticamente en el directorio static/images de tu proyecto.

Ahora puedes interactuar con tu compañero personalizado visualmente.

¡Felicitaciones!

Creaste correctamente un compañero de IA sofisticado. Comenzaste con una app básica, usaste la CLI de Antigravity 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.

👉💻 Para finalizar y cerrar tu sesión, regresa a la terminal y escribe /exit en el mensaje agy para salir de la CLI de Antigravity:

/exit