Crie seu primeiro complemento de IA: um workshop para iniciantes

1. O que você vai aprender

  • Como usar a CLI do Gemini para gerar uma configuração completa do agente do ADK.
  • Como melhorar a personalidade de um agente aprimorando as instruções.
  • Como adicionar "fundamentação" ao seu agente a ele um google_search para responder a perguntas sobre eventos recentes.
  • Como gerar um avatar personalizado para seu acompanhante usando um servidor MCP com o Imagen.

O app AI Companion

Neste codelab, você vai criar um companheiro de IA visual e interativo. Ele é 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 é criar 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 principal 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-lhe superpoderes, fornecendo-lhe ferramentas para acessar informações em tempo real da internet.
  • Criar um visual personalizado 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 funciona 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 conhecer um conceito mais avançado ao iniciar um servidor MCP (Protocolo de Contexto de Modelo) local. Esse servidor funciona como uma ponte de ferramentas especializadas para a geração de imagens. Em seguida, vamos usar a CLI do Gemini para comandar esse servidor MCP, instruindo-o a gerar uma aparência exclusiva para nosso assistente de IA.

Resgate seus créditos

Siga estas instruções com atenção para provisionar os recursos do workshop.

Antes de começar

AVISO!

  • Use uma conta pessoal do Gmail. Contas corporativas ou gerenciadas por escolas NÃO funcionam.
  • Use o Google Chrome no modo de navegação anônima para evitar conflitos de contas.

Abra uma nova janela anônima, cole o link do evento e faça login com seu Gmail pessoal.

👉 Clique abaixo para copiar o link do evento especial:

goo.gle/devfest-boston-ai

Aceite os Termos de Serviço do Google Cloud Platform. Depois de aplicado, você vai ver a mensagem informando que o crédito foi aplicado.

Criar e configurar projeto

Agora que os créditos foram aplicados, configure o ambiente do projeto.

👉 Acesse o console do Google Cloud. Clique abaixo para copiar o link:

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

👉 Na barra de navegação superior do console, clique em Selecionar um projeto e depois em Novo projeto no canto superior direito.

👉 Dê um nome ao projeto e clique em Criar. (Nenhuma organização)

👉 Depois de criar, selecione. No menu à esquerda, acesse Faturamento.

👉 Clique em Vincular uma conta de faturamento, selecione Conta de faturamento de avaliação do Google Cloud Platform no menu suspenso e clique em Definir conta. Se o menu suspenso não aparecer, aguarde um minuto para que o crédito seja aplicado e recarregue a página.

Seus créditos estão ativos e seu projeto está configurado.

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.

👉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 "Informações 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 Google Cloud necessárias:

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

Iniciar o app

Vamos executar o projeto inicial. Essa versão inicial é um servidor de "eco" simples. Ela não tem inteligência e apenas repete o que você envia.

👉💻 No terminal do Cloud Shell, crie e ative um ambiente virtual do Python e instale as bibliotecas necessárias do arquivo requirements.txt.

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

👉💻 Inicie o servidor da Web.

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

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

Às vezes, em um novo ambiente do Cloud Shell, o navegador pode precisar de ajuda para carregar todos os recursos do aplicativo (como imagens e bibliotecas de áudio) pela primeira vez. Vamos fazer uma etapa rápida para "preparar o navegador" e garantir que tudo seja carregado corretamente.

  1. Mantenha a guia de visualização da Web do aplicativo aberta.
  2. Abra uma nova guia do navegador.
  3. Na nova guia, cole o URL do aplicativo, mas adicione o seguinte caminho ao final: /static/images/char-mouth-open.png.Por exemplo, o URL vai ficar assim: https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png
  4. Pressione Enter. Apenas a imagem do personagem com a boca aberta vai aparecer. Essa etapa ajuda a garantir que o navegador tenha buscado corretamente os arquivos da sua instância do Cloud Shell.

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.

👉 Para interromper o servidor, pressione CTRL+C.

3. Criar um personagem com a CLI do Gemini

Agora, vamos criar o núcleo da inteligência do nosso acompanhante. Para isso, vamos trabalhar com dois terminais ao mesmo tempo (este é o terminal do Google Cloud Shell):

  • Terminal 1:será usado para executar nosso servidor da Web Python, permitindo que testemos nossas mudanças em tempo real.
  • Terminal 2:será nossa "estação de criação", onde vamos interagir com a CLI do Gemini.

Vamos usar a Gemini CLI, uma interface de linha de comando avançada que funciona como um assistente de programação de IA. Ele permite descrever o código desejado em inglês simples e gera a estrutura para você, acelerando significativamente o desenvolvimento.

👉💻 No terminal da CLI do Gemini, saia da sessão atual clicando em ctrl+c duas vezes, já que o diretório do projeto está em ~/companion-python, e reinicie a CLI do Gemini.

cd ~/companion-python
clear
gemini --yolo

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 (a personalidade dele) 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 comando da CLI do Gemini, 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-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".

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-2.5-flash se um modelo diferente foi escolhido. Isso garante consistência para o 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 no nome das variáveis temporárias. No entanto, a lógica e a estrutura principais precisam ser funcionalmente idênticas ao que foi solicitado.

Por isso, a programação com uma IA raramente é um comando único. Em um projeto real, os desenvolvedores tratam isso como uma conversa. Comece com um pedido amplo (como acabamos de fazer), revise a saída e refine 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 é o que realmente importa. 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-2.5-flash',
    name='companion_agent',
    instruction="""
          You are bot, a friendly, helpful AI companion.
          Answer no more than 3 sentences.
    """,
)

Teste o código gerado:

👉💻 Acesse o primeiro terminal (aquele para executar o código Python) e inicie o servidor da Web.

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

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

👉 Digite Hello, how are you? e pressione Enviar. Agora, o agente vai responder com uma saudação amigável em vez de apenas repetir suas palavras. Isso confirma que nosso agente agora é alimentado pelo Gemini.

👉 Quando terminar de testar, pare o servidor com CTRL+C. E para o terminal que executa a CLI do Gemini , saia da CLI com CTRL+C duas vezes.

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 acompanhante e instruir a CLI do Gemini a modificar diretamente o código do agente para adotar essa nova persona.

Discutir ideias sobre a personalidade do seu acompanhante

Primeiro, pense um pouco sobre o 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, Capitão IA, Professor Sabe-Tudo)
  • 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 dele? (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 precisa 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 Gemini

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, 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 Gemini, 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]

Teste sua nova persona

A CLI do Gemini vai gerar o código atualizado para character.py.

👉💻 Inicie o servidor da Web novamente.

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

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

👉 Quando terminar, pare o servidor com CTRL+C.

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. Ela não pode informar sobre notícias de ontem ou descobertas recentes. Para resolver isso, damos 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 os servidores MCP (Protocolo de contexto de modelo) que mencionamos na nossa arquitetura. Faremos isso mais tarde para a geração de imagens. Mas, para esta etapa, não precisamos de um servidor separado. O ADK vem com uma ferramenta google_search eficiente e pré-criada que pode ser facilmente adicionada aos recursos do 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.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
)

Testar o agente embasado

👉💻 Inicie o servidor mais uma vez.

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

👉 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 vai usar a ferramenta de pesquisa para encontrar informações atuais e fornecer um resumo útil e fundamentado com a própria voz.

Para interromper o servidor, pressione CTRL+C.

6. Personalizar a aparência do acompanhante (opcional)

Agora que nosso acompanhante tem um cérebro, vamos dar a ele um rosto único. Vamos usar um servidor MCP (Protocolo de Contexto de Modelo) local que permite à CLI do Gemini gerar imagens. Esse servidor vai usar os modelos de IA generativa disponíveis no Google AI Studio.

Então, o que é exatamente um servidor MCP?

O Protocolo de Contexto de Modelo (MCP) é um padrão aberto criado para resolver um problema comum e complexo: como os modelos de IA se comunicam com ferramentas e fontes de dados externas? Em vez de escrever um código personalizado e único para cada integração, o MCP oferece uma "linguagem" universal para essa comunicação.

Pense nisso como um adaptador universal ou uma porta USB para IA. Qualquer ferramenta que "fale" MCP pode se conectar a qualquer aplicativo de IA que também "fale" MCP.

No nosso workshop, o servidor nano-banana-mcp que vamos executar atua como essa ponte crucial. A CLI Gemini vai enviar uma solicitação padronizada ao nosso servidor MCP local. Em seguida, o servidor traduz essa solicitação em uma chamada específica aos modelos de IA generativa para criar a imagem. Isso permite que conectemos recursos avançados de geração de imagens diretamente ao nosso fluxo de trabalho de linha de comando.

Configurar o servidor local de geração de imagens

Agora vamos clonar e executar um servidor MCP pré-criado que processa solicitações de geração de imagens.

👉💻 Em um primeiro terminal do Cloud Shell (aquele em que você está executando o Python), clone o repositório do servidor.

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

Vamos dar uma olhada rápida no servidor, no arquivo mcp_server.py dentro da pasta nano-banana-mcp. Esse servidor foi criado para expor duas "ferramentas" específicas que a CLI do Gemini pode usar. Pense nelas como duas habilidades distintas que nosso serviço de geração de imagens aprendeu.

  1. generate_image:é uma ferramenta de uso geral. Ele usa um único comando de texto e gera uma imagem com base nele. Ele é direto e útil para muitas tarefas.
  2. generate_lip_sync_images:é uma ferramenta altamente especializada, projetada perfeitamente para nossas necessidades. Quando você dá um comando básico descrevendo um personagem, ele realiza um processo inteligente de duas etapas:
    • Primeiro, ele adiciona "com a boca aberta" ao seu comando e gera a primeira imagem.
    • Em seguida, ela pega essa imagem recém-criada e a envia de volta ao modelo com uma nova instrução: "mude a boca de aberta para fechada".

A capacidade do Gemini 2.5 Flash Image (Nano Banana) de alterar ou editar uma imagem com base em um comando de linguagem natural é muito poderosa. O modelo redesenha apenas as partes necessárias da imagem, mantendo todo o resto perfeitamente intacto. Isso garante que as duas imagens sejam absolutamente consistentes em estilo, iluminação e design de personagens, diferindo apenas na posição da boca, que é exatamente o que precisamos para um efeito de sincronia labial convincente.

Nas etapas a seguir, vamos comandar a CLI do Gemini para usar a ferramenta especializada generate_lip_sync_images e criar o avatar exclusivo do nosso acompanhante.

👉💻 Ative o ambiente virtual do projeto e instale os requisitos específicos do servidor.

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

👉💻 Agora, execute o servidor MCP em segundo plano para que ele possa detectar solicitações da CLI do Gemini.

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

Esse comando inicia o servidor, e o símbolo & o mantém em execução em segundo plano.

Em seguida, precisamos configurar a CLI do Gemini para enviar solicitações de geração de imagens ao nosso servidor local recém-executado. Para isso, vamos modificar o arquivo de configuração central da CLI.

Então, o que é esse arquivo settings.json?

O arquivo ~/.gemini/settings.json é o arquivo de configuração central da CLI Gemini. É onde a CLI armazena as configurações, preferências e o diretório de todas as ferramentas externas que ela sabe usar.

Dentro desse arquivo, há uma seção especial chamada mcpServers. Pense nesta seção como uma agenda ou um diretório de serviços específico para ferramentas que usam o protocolo de contexto do modelo. Cada entrada nesse diretório tem um apelido (por exemplo, "nano-banana") e as instruções de como se conectar a ele (no nosso caso, um URL).

O comando que vamos executar vai adicionar uma nova entrada ao diretório de serviços de forma programática. Ele vai informar à CLI do Gemini:

"Olá, a partir de agora, você conhece uma ferramenta chamada nano-banana. Sempre que um usuário pedir para usar, você precisa se conectar ao servidor MCP em execução no URL http://localhost:8000/sse."

Ao modificar essa configuração, estamos tornando a CLI Gemini mais eficiente. Estamos ensinando dinamicamente uma nova habilidade a ele: como se comunicar com nosso servidor local de geração de imagens, sem nunca tocar no código principal da CLI. Esse design extensível permite que a CLI do Gemini organize tarefas complexas chamando um ecossistema inteiro de ferramentas especializadas.

👉💻 No primeiro terminal, execute o seguinte comando. Ele vai criar ou atualizar o arquivo de configurações do Gemini, informando onde encontrar o serviço "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

O conteúdo do arquivo vai aparecer, incluindo a configuração nano-banana.

Gerar avatares de personagens

Com o servidor em execução e a CLI configurada, agora é possível gerar as imagens. Mas, antes de pedir que a IA seja criativa, vamos fazer o que todo bom desenvolvedor faz: verificar nossa configuração. Precisamos confirmar se a CLI do Gemini pode se comunicar com nosso servidor MCP local.

👉💻 De volta ao terminal da CLI do Gemini (aquele que não está executando um servidor), vamos iniciar o shell interativo do Gemini. Se ele já estiver em execução, saia com CTRL+C duas vezes e reinicie para garantir que as novas configurações sejam carregadas.

clear
gemini --yolo

Agora você está no ambiente interativo da CLI do Gemini. Aqui, você pode conversar com a IA ou dar comandos diretos à CLI.

👉✨ Para verificar se o servidor MCP está conectado, vamos usar um "comando de barra" especial. Esse não é um comando para a IA, mas sim uma instrução para o próprio aplicativo da CLI. Digite o seguinte e pressione Enter:

/mcp list

Esse comando diz à CLI do Gemini: "Analise sua configuração, encontre todos os servidores MCP que você conhece, tente se conectar a cada um deles e informe o status."

👀 Você vai ver a seguinte saída, que é uma confirmação de que tudo está funcionando perfeitamente:

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

Vamos analisar o que essa resposta bem-sucedida significa:

  • 🟢 nano-banana: o círculo verde é nosso indicador de sucesso. Ele confirma que a CLI conseguiu acessar o servidor nano-banana no URL especificado em settings.json.
  • - Ready: esse status confirma que a conexão está estável.
  • (2 tools): esta é a parte mais importante. Isso significa que a CLI não apenas se conectou, mas também perguntou ao nosso servidor MCP: "O que você pode fazer?" Nosso servidor respondeu anunciando as duas ferramentas que vimos no código: generate_image e generate_lip_sync_images.

Isso confirma que toda a cadeia de comunicação foi estabelecida. Agora, a CLI conhece nosso serviço local de geração de imagens e está pronta para usá-lo no nosso comando.

Agora, a parte mais criativa do workshop! Vamos usar um comando único e eficiente para instruir a CLI do Gemini a usar a ferramenta especial generate_lip_sync_images no nosso servidor MCP em execução.

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

👉✨ Este é um exemplo de comando bem estruturado. Você pode usar como ponto de partida ou substituir totalmente a parte descritiva pela sua própria visão.

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.

A ferramenta vai gerar um conjunto de imagens (com a boca aberta, fechada etc.) e salvá-las. Ele vai mostrar os caminhos para onde os arquivos foram salvos.

Reiniciar o aplicativo

Com os avatares personalizados no lugar, reinicie o servidor da Web para conferir o novo visual do personagem.

👉💻 Inicie o servidor pela última vez no primeiro terminal

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

👀 Para garantir que as novas imagens carreguem corretamente, vamos carregar a imagem char-mouth-open.png com antecedência.

  1. Mantenha a guia de visualização da Web do aplicativo aberta.
  2. Abra uma nova guia do navegador.
  3. Na nova guia, cole o URL do aplicativo, mas adicione o seguinte caminho ao final: /static/images/char-mouth-open.png.Por exemplo, o URL vai ficar assim: https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png
  4. Pressione Enter. Apenas a imagem do personagem com a boca aberta vai aparecer. Essa etapa ajuda a garantir que o navegador tenha buscado corretamente os arquivos da sua instância do Cloud Shell.

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 Gemini 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ê está pronto para criar agentes de IA ainda mais complexos e capazes.