Sobre este codelab
1. Visão geral
Por onde começar a criar com a IA hoje? Para a maioria de nós, isso geralmente começa com uma pergunta simples: "O modelo pode ajudar a resolver esse problema que tenho pensado?". É exatamente aí que entra o Google AI Studio. É um lugar onde você pode criar protótipos de qualquer coisa rapidamente. Quero reformar minha cozinha, e tenho certeza de que o Gemini pode ajudar, mas sou engenheiro, não empreiteiro. Não sei ao certo o que pedir. Há tantas coisas a considerar: regulamentos, acessórios etc. Vamos dividir isso e pedir para o Gemini gerar um comando super detalhado, depois um plano de renovação completo e também visualizar a reforma. Mas espere. Como posso ajudar as empresas a crescer? Entre em CONTATO COM OS AGENTES!!!
Um agente é um programa autônomo que conversa com um modelo de IA para realizar uma operação baseada em metas usando as ferramentas e o contexto que tem e é capaz de tomar decisões autônomas com base na verdade.
O Agent Development Kit (ADK)
O Agent Development Kit (ADK) é um framework flexível e modular para desenvolvimento e implantação de agentes de IA. O ADK oferece suporte à criação de aplicativos sofisticados ao compor várias instâncias de agentes distintas em um sistema multiagente (MAS).
No ADK, um sistema multiagente é um aplicativo em que diferentes agentes, geralmente formando uma hierarquia, colaboram ou se coordenam para alcançar uma meta maior. Estruturar seu aplicativo dessa maneira oferece vantagens significativas, incluindo modularidade, especialização, reutilização, capacidade de manutenção e a capacidade de definir fluxos de controle estruturados usando agentes de fluxo de trabalho dedicados.
O que você vai criar
Tudo pronto para passar do nosso PROMPT de protótipo para Criar um agente? Vamos criar um agente para ajudar a gerar o documento de proposta para o projeto de reforma da cozinha. Como parte deste laboratório, você vai:
- Criar um agente simples para gerar um documento de proposta de renovação com o ADK
- Armazenar o documento de proposta de reforma gerado em um bucket do Cloud Storage
- Testar o agente no Cloud Shell e na saída da Web do agente
Requisitos
2. Antes de começar
Criar um projeto
- No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
- Verifique se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto .
- Além disso, se você estiver lendo este artigo e quiser receber créditos para começar a usar o Google Cloud e o ADK, acesse este link para resgatar créditos.
- Siga estas instruçõespara resgatar o código. Este link é válido apenas até 15 de julho de 2025 para resgate.
- Ative o Cloud Shell clicando neste link. É possível alternar entre o terminal do Cloud Shell (para executar comandos de nuvem) e o Editor (para criar projetos) clicando no botão correspondente no Cloud Shell.
- Depois de se conectar ao Cloud Shell, verifique se você já está autenticado e se o projeto está definido como seu ID usando o seguinte comando:
gcloud auth list
- Execute o comando a seguir no Cloud Shell para confirmar se o comando gcloud sabe sobre seu projeto.
gcloud config list project
- Se o projeto não estiver definido, use este comando:
gcloud config set project <YOUR_PROJECT_ID>
- Instale o Python 3.9 ou versão mais recente.
Consulte a documentação para conferir outros comandos e usos do gcloud.
3. Protótipo
Acesse o Google AI Studio. Comece a digitar no comando. Este é meu comando:
I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.
Ajuste e configure os parâmetros à direita para receber a resposta ideal.
Com base nessa descrição simples, o Gemini me deu um comando muito detalhado para iniciar minha reforma. Na prática, estamos usando o Gemini para receber respostas ainda melhores do AI Studio e dos nossos modelos. Você também pode selecionar diferentes modelos com base no seu caso de uso.
Escolhemos o Gemini 2.5 Pro. Esse é um modelo de pensamento, o que significa que temos ainda mais tokens de saída, neste caso até 65 mil, para análises longas e documentos detalhados. A caixa de pensamento do Gemini aparece quando você ativa o Gemini 2.5 Pro, que tem recursos de raciocínio nativo e pode receber solicitações de contexto longo.
Confira o snippet da resposta abaixo:
O AI Studio analisou meus dados e produziu todas essas coisas, como armários, bancadas, backsplash, piso, pia, coesão, paleta de cores e seleção de materiais. O Gemini até cita fontes.
Agora tente ver a ideia ganhar vida com um comando diferente.
- Copie e cole este comando no editor de comandos:
Add flat and circular light accessories above the island area for my current kitchen in the attached image.
- Anexe uma imagem da sua cozinha atual (ou use minha imagem de exemplo de cozinha).
- Mude o modelo para "Gemini 2.0 Flash Preview Image Generation" para ter acesso à geração de imagens.
A saída foi esta:
Esse é o potencial do Gemini.
Desde a compreensão de vídeos até a geração de imagens nativas e a coleta de informações reais com a Pesquisa Google, há coisas que só podem ser criadas com o Gemini.
No AI Studio, é possível usar esse protótipo, extrair a chave de API e dimensioná-lo para um aplicativo totalmente agente usando o poder do ADK da Vertex AI.
4. Configuração do ADK
Agora, vamos para o terminal do Cloud Shell que ativamos na seção "Antes de começar":
- Criar e ativar o ambiente virtual (recomendado)
No terminal do Cloud Shell, crie um ambiente virtual:
python -m venv .venv
Ative o ambiente virtual:
source .venv/bin/activate
- Instalar o ADK
pip install google-adk
5. Estrutura do projeto
- No terminal do Cloud Shell, crie um diretório raiz para os apps de agentes no local do projeto desejado:
mkdir agentic-apps
- No diretório principal, crie uma pasta específica para o projeto atual:
mkdir renovation-agent
- Acesse o editor do Cloud Shell e crie a estrutura de projeto a seguir criando os arquivos (vazios para começar):
renovation-agent/
__init__.py
agent.py
requirements.txt
.env
6. Código-fonte
- Acesse init.py e atualize com o seguinte conteúdo:
from . import agent
- Acesse agent.py e atualize o arquivo com o conteúdo a seguir no seguinte caminho:
https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/agent.py
Em agent.py, importamos as dependências necessárias, extraímos os parâmetros de configuração do arquivo .env e definimos o root_agent, que gera um documento de proposta e o armazena em um bucket do Cloud Storage. Para realizar a etapa do Cloud Storage, usamos uma ferramenta chamada store_pdf.
- Verifique se você tem o bucket do Cloud Storage
Isso é para armazenar o documento de proposta gerado pelo agente. Crie e provisioneie o acesso para que o sistema de agentes criado com a Vertex AI possa acessá-lo. Confira como fazer isso:
https://cloud.google.com/storage/docs/creating-buckets#console
Nomeie o bucket como "next-demo-store". Se você der outro nome, não se esqueça de atualizar o valor de STORAGE_BUCKET no arquivo .env (na etapa de configuração das variáveis de ambiente).
- Para configurar o acesso ao bucket, acesse o console do Cloud Storage e o bucket do Storage. No nosso caso, o nome do bucket é "next-demo-storage": https://console.cloud.google.com/storage/browser/next-demo-storage.
Navegue até Permissões > Visualizar principais > Permitir acesso. Selecione "Princípios" como "allUsers" e "Papel" como "Usuário de objetos do Storage".
Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.
- Criar lista de dependências
Liste todas as dependências em requirements.txt. Você pode copiar isso do repo.
Explicação do código-fonte do sistema de um único agente
O arquivo agent.py define a estrutura e o comportamento do sistema multiagente de reforma de cozinha usando o Kit de desenvolvimento de agentes (ADK). Vamos detalhar os principais componentes:
Definição do agente
Agente raiz (orquestrador): proposal_agent
O root_agent atua como o orquestrador desse sistema de um único agente. Ele recebe a solicitação inicial de renovação e determina quais ferramentas invocar com base nas necessidades da solicitação.
O root_agent coleta as respostas das ferramentas e as combina para fornecer uma resposta abrangente ao usuário. Neste caso, temos apenas uma ferramenta "store_pdf".
7. Fluxo de dados e principais conceitos
O usuário inicia uma solicitação pela interface do ADK (terminal ou interface da Web).
- A solicitação é recebida pelo root_agent.
- O root_agent analisa a solicitação e a encaminha para a ferramenta conforme necessário.
- A ferramenta "store_pdf" foi projetada para gravar o conteúdo de texto renovado em um arquivo PDF e fazer upload dele no Google Cloud Storage.
- Isso retorna a resposta para o root_agent.
- O root_agent combina as respostas e fornece uma saída final para o usuário.
Modelos de linguagem grandes (LLMs)
Os agentes dependem muito dos LLMs para gerar texto, responder a perguntas e realizar tarefas de raciocínio. Os LLMs são o "cérebro" por trás da capacidade dos agentes de entender e responder às solicitações dos usuários. Estamos usando o Gemini 2.5 neste aplicativo.
Google Cloud Storage
Usado para armazenar os documentos gerados da proposta de reforma. Você precisa criar um bucket e conceder as permissões necessárias para que os agentes o acessem.
Cloud Run (opcional)
O OrderingAgent usa uma função do Cloud Run para interagir com o AlloyDB. O Cloud Run oferece um ambiente sem servidor para executar código em resposta a solicitações HTTP.
AlloyDB
Se você estiver usando o OrderingAgent, vai precisar configurar um banco de dados do AlloyDB para armazenar informações de pedidos.
Arquivo.env
O arquivo .env armazena informações sensíveis, como chaves de API, credenciais de banco de dados e nomes de bucket. É fundamental manter esse arquivo seguro e não confirmar no repositório. Ele também armazena as configurações dos agentes e do seu projeto do Google Cloud. O root_agent ou as funções de suporte geralmente leem valores desse arquivo. Verifique se todas as variáveis necessárias estão definidas corretamente no arquivo .env. Isso inclui o nome do bucket do Cloud Storage
8. Configuração do modelo
A capacidade do seu agente de entender as solicitações dos usuários e gerar respostas é alimentada por um modelo de linguagem grande (LLM). O agente precisa fazer chamadas seguras para esse serviço externo de LLM, que exige credenciais de autenticação. Sem uma autenticação válida, o serviço LLM negará as solicitações do agente, que não vai funcionar.
- Receba uma chave de API do Google AI Studio.
- Na próxima etapa, quando você configurar o arquivo .env, substitua
<<your API KEY>>pelo valor real da CHAVE DE API.
9. Configuração de variáveis de ambiente
- Defina os valores dos parâmetros no arquivo .env do modelo neste repo. No meu caso, o .env tem estas variáveis:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION = us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT = <<your project id>>
PROJECT_ID = <<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
STORAGE_BUCKET = next-demo-store <<or your storage bucket name>>
Substitua os marcadores de posição pelos seus valores.
10. Executar o agente
- Usando o terminal, navegue até o diretório pai do projeto do agente:
cd agentic-apps/renovation-agent
- Instalar todas as dependências
pip install -r requirements.txt
- É possível executar o comando a seguir no terminal do Cloud Shell para executar o agente:
adk run .
- Execute o seguinte para executar em uma interface da Web provisionada pelo ADK:
adk web
- Teste com as seguintes solicitações:
user>>
Hello. Generate Proposal Document for the kitchen remodel requirement in a proper format that applies to a renovation contract. Remember this text will eventually be stored as a pdf file so make sure to have the formatting appropriate. I have no other specification.
11. Resultado
Para o comando adk run . O resultado é o seguinte"
…
Você pode validar se o documento "Proposta de reforma" foi criado no bucket do Cloud Storage.
12. Limpar
Para evitar cobranças na sua conta do Google Cloud pelos recursos usados nesta postagem, siga estas etapas:
- No console do Google Cloud, acesse a página Gerenciar recursos.
- Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir.
- Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.
13. Parabéns
Parabéns! Você criou e interagiu com seu app multiagente usando o ADK. O sistema multiagente foi projetado para simplificar o processo de reforma da cozinha automatizando tarefas como a geração de propostas, a verificação de licenças e o rastreamento do status do pedido. Cada agente tem um papel específico, e o root_agent coordena as atividades para fornecer uma solução abrangente. O sistema usa LLMs, serviços do Google Cloud e APIs possivelmente externas para oferecer a funcionalidade. Este é um link para a documentação do produto.