Um workshop para iniciantes sobre a CLI do Antigravity e o ADK (crie seu primeiro assistente de IA)

1. O que você vai aprender

• Como instalar e registrar uma habilidade para a CLI do Antigravity e ativar recursos de programação em uma estrutura específica (ADK).
• Como usar a CLI do Antigravity para gerar uma configuração completa de agente do ADK.
• Como melhorar a personalidade de um agente aprimorando as instruções.
• Como adicionar "fundamentação" ao seu agente, atribuindo-lhe um google_search para responder a perguntas sobre eventos recentes.

O app Assistente de IA

Neste codelab, você vai criar um companheiro de IA visual e interativo. Ele é muito mais do que um chatbot padrão de texto. Imagine um personagem vivendo em uma página da Web. Você digita uma mensagem, e em vez de apenas ver o texto, o personagem olha para você e responde em voz alta, com a boca se movendo em sincronia com as palavras.

Você vai começar com um aplicativo da Web pré-criado, um "fantoche" digital que tem um rosto, mas não tem mente própria. Ele só pode repetir o que você digita. Sua missão é construir o cérebro e a personalidade dele do zero.

Ao longo deste workshop, você vai adicionar progressivamente camadas de inteligência e personalização, transformando esse fantoche simples em um companheiro único e capaz. Você vai:

• a ele uma inteligência central usando o ADK(Python) para entender e gerar linguagem.
• Criar uma personalidade única escrevendo as instruções principais que definem o caráter dela.
• Concedendo superpoderes ao dar a ele ferramentas para acessar informações em tempo real da Internet.
• Criar uma aparência personalizada usando a IA para gerar um avatar exclusivo.

Ao final, você terá um acompanhante de IA totalmente funcional e personalizado, criado por você.

Arquitetura

Nosso aplicativo segue um padrão simples, mas eficiente. Temos um back-end Python que veicula uma API. Esse back-end vai conter nosso agente do ADK, que atua como o "cérebro". Qualquer interface do usuário (como o front-end JavaScript do app esqueleto, um app para dispositivos móveis ou até mesmo uma ferramenta de linha de comando) pode interagir com esse cérebro pela API.

Além disso, vamos aproveitar os recursos de geração de imagens integrados à CLI do Antigravity, instruindo-a a gerar uma aparência exclusiva para nosso acompanhante de IA.

Receber uma chave da API Gemini

Antes de continuar, você precisa de uma chave da API Gemini para autenticar suas solicitações com o Google AI Studio.

1. Acesse o Google AI Studio.
2. Faça login usando sua Conta do Google.
3. Clique no botão Receber chave de API no menu do canto superior esquerdo.
4. Clique em Criar chave de API (é possível criar em um projeto do Google Cloud novo ou atual).
5. Copie a chave gerada. Mantenha essa chave privada e segura.

Criar e configurar um projeto

Para acessar o Cloud Shell, você ainda precisa de um projeto do Google Cloud. Se você não tiver:

1. Acesse o Console do Google Cloud.
2. Na barra de navegação superior do console, clique em Selecionar um projeto e em Novo projeto no canto superior direito.
3. Dê um nome ao projeto e clique em Criar. (Nenhuma organização é necessária).
4. Depois que o projeto for criado, selecione-o no menu suspenso na parte de cima do console.

Seu projeto agora está configurado para acesso ao Cloud Shell.

2. Antes de começar

👉Clique em "Ativar o Cloud Shell" na parte de cima do console do Google Cloud. É o ícone em forma de terminal na parte de cima do painel do Cloud Shell.

👉💻 Instale a CLI do Antigravity no terminal do Cloud Shell:

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

👉💻 Para usar a CLI "agy" globalmente, adicione-a ao seu perfil de shell:

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

👉💻 Exporte sua chave de API Gemini e salve-a localmente no terminal do Cloud Shell:

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

👉💻 Salve para usar depois:

echo $GEMINI_API_KEY > ~/gemini_key.txt

👉Encontre o ID do projeto do Google Cloud:

• Abra o console do Google Cloud: https://console.cloud.google.com
• Selecione o projeto que você quer usar neste workshop no menu suspenso na parte de cima da página.
• O ID do projeto é exibido no card de informação do projeto no painel

👉💻 No terminal, clone o projeto de bootstrap do GitHub:

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

👉💻 Execute o script de inicialização. Ele vai pedir que você insira o ID do projeto do Google Cloud. Insira o ID do projeto do Google Cloud que você encontrou na última etapa quando solicitado pelo script init.sh.

cd ~/companion-python
./init.sh

👉💻 Defina o ID do projeto necessário:

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

👉💻 Execute o comando a seguir para ativar as APIs do Cloud necessárias do Google Cloud. Somente o Compute Engine é necessário para a prévia/hospedagem do Cloud Shell:

gcloud services enable compute.googleapis.com

Instalar a habilidade para desenvolvedores do ADK

Para permitir que a CLI do Antigravity (agy) entenda e escreva código usando o Kit de Desenvolvimento de Agente (ADK) do Python, precisamos instalar a habilidade de desenvolvedor Python do ADK que criamos no espaço de trabalho do projeto.

👉💻 Crie o diretório de habilidades do agente local e copie o arquivo de habilidade:

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

Isso registra a habilidade localmente no projeto. Ao iniciar o agy, ele detecta e carrega automaticamente essa habilidade, permitindo que ela escreva, edite e organize agentes do ADK.

👉💻 Inicie a CLI do Antigravity no terminal do Cloud Shell:

cd ~/companion-python
agy

[!IMPORTANT] Fazer login na CLI do Antigravity

Na primeira vez que você executar o comando agy, será necessário fazer login:

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

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

1. Escolha a opção 1. Google OAuth pressionando Enter.
2. Siga a solicitação para abrir o navegador, faça a autenticação com sua Conta do Google e siga as instruções para fazer login.

Agora você está no comando interativo da CLI do Antigravity.

Iniciar o servidor da Web pela CLI do Antigravity

Como a CLI do Antigravity pode executar comandos para você, vamos pedir que ela execute o servidor em segundo plano na sua sessão.

👉✨ No comando da CLI do Antigravity, cole a seguinte solicitação:

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.

Pressione "Enter" para aprovar a solicitação do agy de gravar o arquivo.

A CLI vai executar o comando e confirmar que o servidor está em execução. Você vai permanecer na sessão interativa da CLI.

👀 Para conferir o app, clique no ícone de visualização da Web na barra de ferramentas do Cloud Shell. Selecione "Alterar porta", defina como 5000 e clique em "Alterar e visualizar". Uma prévia do seu site vai aparecer.

O aplicativo inicial é apenas um fantoche. Ainda não tem inteligência. Qualquer mensagem enviada será repetida. Isso confirma que o servidor da Web básico está funcionando antes de adicionarmos a IA. Não se esqueça de ligar o alto-falante.

3. Criar um personagem com a CLI do Antigravity

Agora, vamos criar o núcleo da inteligência do nosso acompanhante. Como a CLI do Antigravity já está em execução no terminal e gerenciando o servidor da Web em segundo plano, você pode continuar diretamente na sessão interativa.

Estamos usando a CLI para criar um agente. Um agente é mais do que apenas uma simples chamada para um modelo de linguagem. Ele é o "cérebro" ou controlador central da nossa IA. Pense nele como uma entidade distinta que pode raciocinar, seguir um conjunto específico de instruções (personalidade) e usar ferramentas para realizar tarefas. No nosso projeto, esse agente é o componente que vai receber mensagens do usuário, incorporar a personalidade única do nosso acompanhante e formular respostas inteligentes e de acordo com o personagem.

👉✨ No prompt da CLI do Antigravity, cole o seguinte para gerar o código do 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".

Pressione "Enter" para aprovar a solicitação do agy de gravar o arquivo.

A CLI vai gerar o código Python.

👉Clique no botão "Abrir editor" (parece uma pasta aberta com um lápis). Isso vai abrir o editor de código do Cloud Shell na janela. Um explorador de arquivos vai aparecer no lado esquerdo.

👉 Use o Editor e navegue até character.py na pasta companion-python. Verifique a linha model= e edite manualmente para gemini-3.5-flash se um modelo diferente foi escolhido. Isso garante a consistência do restante do workshop.

Observação: os modelos de linguagem grandes podem ser não deterministas, e esse é um conceito fundamental no desenvolvimento assistido por IA. "Não determinístico" significa que, mesmo com o mesmo comando, o modelo pode produzir resultados ligeiramente diferentes a cada vez. Ele usa a criatividade para gerar o código. Por isso, você pode notar variações em comentários, espaçamento ou até mesmo na nomenclatura de variáveis temporárias. No entanto, a lógica e a estrutura principais precisam ser funcionalmente idênticas ao que foi solicitado.

Por isso, programar com uma IA raramente é um comando único. Em um projeto real, os desenvolvedores tratam isso como uma conversa. Você começa com um pedido amplo (como acabamos de fazer), analisa a saída e a refina com comandos de acompanhamento, como:

• "Ótimo, agora adicione comentários explicando cada linha."
• "Você pode refatorar isso em uma função separada?"
• "Adicione tratamento de erros à chamada de API."

Esse processo iterativo e conversacional permite que você colabore com a IA, orientando-a até que o código seja exatamente o que você precisa. Neste workshop, vamos usar comandos específicos e diretos, mas lembre-se de que, nos seus projetos, a conversa é que tem o poder de verdade. Desde que a estrutura de código gerada pela CLI seja a mesma, tudo vai dar certo.

Se o código gerado não funcionar, substitua o código a seguir pelo seu 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.
    """,
)

Testar o código gerado

Para garantir que o servidor carregue o módulo character.py recém-gerado, peça à CLI do Antigravity para reiniciar o servidor da Web.

👉✨ No comando da CLI do Antigravity, cole a seguinte solicitação:

Please restart the Python web server for me.

Pressione "Enter" para aprovar a solicitação do agy de gravar o arquivo.

👀 Acesse a guia de visualização na Web.

👉 Tipo:

Hello, how are you?

e pressione "Enviar". Agora, o agente deve responder com uma saudação amigável em vez de apenas repetir suas palavras. Isso confirma que nosso agente agora é alimentado pelo Gemini.

4. Melhorar a personalidade do agente

Uma instrução simples é boa, mas uma persona detalhada cria um personagem muito mais envolvente e memorável. Nesta etapa, você vai criar a personalidade do seu próprio acompanhante e instruir a CLI do Antigravity a modificar diretamente o código do agente para adotar essa nova persona.

Discuta a persona do seu acompanhante

Primeiro, pense no acompanhante de IA que você quer criar. Esta é sua chance de usar a criatividade! Confira algumas perguntas para começar:

• Qual é o nome dele? (por exemplo, Sparky, Codex, Captain AI, Professor Know-it-all)
• Qual é a personalidade principal dele? (por exemplo, amigável e curioso, espirituoso e sarcástico, formal e profissional, um pirata alegre?)
• Qual é a função ou especialização dela? (por exemplo, um assistente de uso geral, um especialista em programação, um parceiro de escrita criativa, um instrutor de fitness?)
• Quais são algumas regras que ela sempre deve seguir? Por exemplo, "Sempre comece com uma saudação", "Nunca revele que você é uma IA", "Use emojis nas suas respostas".

Exemplo de persona:

 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.

Criar o comando para a CLI do Antigravity

Agora que você criou a personalidade do seu acompanhante no papel, é hora de dar vida a ela no código. A parte mais importante de um agente do ADK é o parâmetro instruction. Pense nisso como a programação principal do agente, a "diretriz principal" ou a constituição que ele precisa seguir sempre.

Essa instrução é a chave para controlar o comportamento do agente. Não é apenas uma sugestão, mas o contexto fundamental a que a IA se refere antes de cada interação com o usuário. Ela determina a personalidade do agente, o tom de voz, as regras que ele precisa obedecer e como ele deve se apresentar. Uma instrução bem elaborada é a diferença entre um chatbot genérico e um personagem consistente e confiável. Portanto, o comando que vamos criar é crucial, já que ele vai injetar diretamente essa personalidade no cérebro do nosso agente.

👉✨ De volta à CLI do Antigravity, use este modelo. Substitua o texto entre colchetes pela descrição da sua persona. REPLACE [YOUR PERSONA DESCRIPTION HERE] com o perfil ideal de cliente que você preferir

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]

Pressione "Enter" para aprovar a solicitação do agy de gravar o arquivo.

Teste sua nova persona

A CLI do Antigravity vai gerar o código atualizado para character.py. Para garantir que o servidor escolha a nova configuração do agente, vamos pedir à CLI do Antigravity para reiniciá-lo.

👉✨ No comando da CLI do Antigravity, cole a seguinte solicitação:

Please restart the Python web server for me.

Pressione "Enter" para aprovar a solicitação do agy de gravar o arquivo.

👀 Na prévia da Web, converse com o acompanhante. Pergunte para o how are you?. A resposta agora deve corresponder perfeitamente ao personagem exclusivo que você criou.

Adicionar tratamento de novas tentativas para limitações de taxa de API (opcional, mas recomendado)

Durante workshops ou períodos de alto uso simultâneo, você pode encontrar erros de limite de taxa da API (HTTP 429: recurso esgotado). Para garantir que seu complemento permaneça responsivo e processe exceções de limitação de taxa automaticamente, podemos configurar opções de nova tentativa integradas diretamente às opções de cliente do SDK do Google GenAI.

👉✨ No comando da CLI do Antigravity, cole a seguinte solicitação:

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.

Pressione "Enter" para aprovar a solicitação do agy de gravar o arquivo.

A CLI vai modificar seu arquivo character.py para processar limites de taxa automaticamente usando políticas de nova tentativa no nível do cliente. Não se esqueça de pedir para a CLI reiniciar o servidor da Web depois que ela atualizar o arquivo:

Please restart the Python web server for me.

Pressione "Enter" para aprovar a solicitação do agy de gravar o arquivo.

5. Adicionar embasamento para eventos recentes

Nosso agente agora tem muita personalidade, mas tem uma limitação significativa: o conhecimento dele está congelado no tempo, com base nos dados em que foi treinado. Ele não pode informar sobre notícias de ontem ou descobertas recentes. Para resolver isso, oferecemos ferramentas aos agentes.

Pense nas ferramentas como superpoderes ou habilidades especiais que você concede ao seu agente. Por si só, o agente só pode falar. Com uma ferramenta de pesquisa, ele pode navegar na Internet. Com uma ferramenta de agenda, ele pode verificar sua programação. Tecnicamente, uma ferramenta é uma função específica ou uma API que o agente pode escolher usar de forma inteligente quando percebe que o próprio conhecimento não é suficiente para responder à solicitação de um usuário.

Em sistemas avançados, as ferramentas podem ser fornecidas por sistemas externos, como servidores MCP (Protocolo de Contexto de Modelo). Mas, para esta etapa, não precisamos de um servidor separado. O ADK vem com uma ferramenta google_search poderosa e pré-criada que pode ser facilmente adicionada às capacidades do nosso agente.

Vamos dar ao nosso acompanhante o poder da Pesquisa Google.

👉 No editor do Cloud Shell, abra character.py em companion-python e modifique da seguinte maneira:

• Importe google_search de google.adk.tools.
• Adicione uma lista tools ao construtor LlmAgent.
• Atualize o instruction para informar explicitamente ao seu complemento quando usar a nova ferramenta.

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

Testar o agente embasado

Para garantir que o servidor da Web carregue seu novo código com a ferramenta google_search, peça à CLI do Antigravity para reiniciá-lo.

👉✨ No comando da CLI do Antigravity, cole a seguinte solicitação:

Please restart the Python web server for me.

Pressione "Enter" para aprovar a solicitação do agy de gravar o arquivo.

👉 Na prévia da Web, faça uma pergunta que exija conhecimento atualizado, como:

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

👉 Em vez de dizer que não sabe, o agente agora usa a ferramenta de pesquisa para encontrar informações atualizadas e fornecer um resumo útil e fundamentado com a própria voz.

6. Personalizar a aparência do modo companion

Agora que nosso companheiro tem um cérebro, vamos dar a ele um rosto único. Como a CLI do Antigravity já vem equipada com recursos de geração de imagens, basta pedir que ela crie os avatares diretamente para você.

Esta é a sua chance de criar uma aparência única para seu companheiro. Pense no estilo, na expressão e em outros detalhes que se encaixam na persona criada anteriormente.

👉✨ No comando da CLI do Antigravity, cole a seguinte solicitação (você pode modificar o comando com sua própria descrição de personagem criativo):

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.

Pressione "Enter" para aprovar a solicitação do agy de gravar o arquivo.

A ferramenta vai gerar o conjunto de imagens com a boca aberta e fechada e salvar automaticamente no diretório static/images do projeto.

Agora você pode interagir com seu acompanhante personalizado visualmente.

Parabéns!

Você criou um companheiro de IA sofisticado. Você começou com um app básico, usou a CLI do Antigravity para criar um agente, deu a ele uma personalidade rica e o capacitou com ferramentas para acessar informações em tempo real e até gerar um avatar próprio. Agora você já pode criar agentes de IA ainda mais complexos e eficientes.

👉💻 Para concluir e encerrar a sessão, volte ao terminal e saia da CLI do Antigravity digitando /exit no prompt agy:

/exit