GENAI129

Visão geral

Neste laboratório, você vai demonstrar sua capacidade de criar agentes usando o Kit de Desenvolvimento de Agente (ADK, na sigla em inglês), implantá-los no Agent Engine e usá-los em um web app.

Objetivo

Neste laboratório, você vai:

• Criar um agente composto de um agente raiz e subagentes usando o Kit de Desenvolvimento de Agente (ADK)
• Capacitar agentes com uma ferramenta Agent Search e funções Python usadas como ferramentas
• Armazenar as saídas do agente no estado da sessão e recuperar essas informações para contextualizar instruções subsequentes
• Implantar seu agente no Agent Runtime
• Consultar o agente implantado no Agent Runtime

Materiais de aprendizagem relacionados

Se você está em busca de recursos para desenvolver as habilidades necessárias para concluir este laboratório, dê uma olhada nas seções relevantes destes documentos:

Configuração e requisitos

Antes de clicar no botão "Começar o Laboratório"

Leia estas instruções. Os laboratórios são cronometrados e não podem ser pausados. O timer é ativado quando você clica em Iniciar laboratório e mostra por quanto tempo os recursos do Google Cloud vão ficar disponíveis.

Este laboratório prático permite que você realize as atividades em um ambiente real de nuvem, e não em uma simulação ou demonstração. Você vai receber novas credenciais temporárias para fazer login e acessar o Google Cloud durante o laboratório.

Confira os requisitos para concluir o laboratório:

• Acesso a um navegador de Internet padrão (recomendamos o Chrome).

• Tempo para concluir o laboratório: não se esqueça que, depois de começar, não será possível pausar o laboratório.

Como iniciar seu laboratório e fazer login no console do Google Cloud

1. Clique no botão Começar o laboratório. Se for preciso pagar por ele, uma caixa de diálogo vai aparecer para você selecionar a forma de pagamento. No painel Detalhes do Laboratório, à esquerda, você vai encontrar o seguinte:

   • O botão Abrir Console do Google Cloud
   • O tempo restante
   • As credenciais temporárias que você vai usar neste laboratório
   • Outras informações, se forem necessárias

2. Se você estiver usando o navegador Chrome, clique em Abrir console do Google Cloud ou clique com o botão direito do mouse e selecione Abrir link em uma janela anônima.

   O laboratório ativa os recursos e depois abre a página Fazer Login em outra guia.

   Dica: coloque as guias em janelas separadas lado a lado.

   Observação: se aparecer a caixa de diálogo Escolher uma conta, clique em Usar outra conta.

3. Se necessário, copie o Nome de usuário abaixo e cole na caixa de diálogo Fazer login.

   {{{user_0.username | "Username"}}}

   Você também encontra o nome de usuário no painel Detalhes do Laboratório.

4. Clique em Próxima.

5. Copie a Senha abaixo e cole na caixa de diálogo de boas-vindas.

   {{{user_0.password | "Password"}}}

   Você também encontra a senha no painel Detalhes do Laboratório.

6. Clique em Próxima.

   Importante: você precisa usar as credenciais fornecidas no laboratório, e não as da sua conta do Google Cloud. Observação: se você usar sua própria conta do Google Cloud neste laboratório, talvez receba cobranças adicionais.

7. Acesse as próximas páginas:

   • Aceite os Termos e Condições.
   • Não adicione opções de recuperação nem autenticação de dois fatores (porque essa é uma conta temporária).
   • Não se inscreva em testes sem custo financeiro.

Depois de alguns instantes, o console do Google Cloud será aberto nesta guia.

Observação: para acessar os produtos e serviços do Google Cloud, clique no Menu de navegação ou digite o nome do serviço ou produto no campo Pesquisar.

Cenário do desafio

Um colega de trabalho está desenvolvendo um agente chamado Agente de Pintura, que vai ajudar os usuários com o seguinte:

• selecionar uma tinta com base nas fichas técnicas de tintas da Cymbal Shops;
• escolher uma cor entre as disponíveis na linha de produtos selecionada;
• saber quanta tinta será necessária com base nas dimensões dos cômodos;
• calcular o preço de acordo com as opções selecionadas.

No entanto, seu colega não conseguiu resolver um bug do agente e, um tempo depois, se desligou da empresa.

Você agora é responsável pela engenharia de ML da Cymbal Shops. Sua tarefa é concluir a implantação do Agente de Pintura. Confira a estrutura do agente:

Tarefa 1: criar um app do Agent Search com informações sobre tintas

Nesta tarefa, você vai implantar um repositório de dados do Agent Search. Esse repositório vai importar uma ficha técnica que descreve as tintas da Cymbal Shops. Para conferir uma prévia, abra uma guia na janela anônima e acesse https://storage.cloud.google.com/-bucket/Cymbal_Shops_Paint_Datasheets.pdf. Essa ficha técnica vai atuar como fonte de dados de embasamento para as consultas dos usuários sobre as tintas.

Um repositório de dados e um app de pesquisa permitem que o agente encontre rapidamente o conteúdo da sua organização. Ele pode usar essas informações para fornecer uma resposta adequada ao usuário com base nos seus dados.

1. No console do Google Cloud, navegue até Agent Platform > Agentes > Pesquisa.

2. Crie um app do Agent Search com a seguinte configuração:

   Campo	Valor
   Tipo de app	Pesquisa personalizada (geral)
   Nome do app	Pesquisa de pintura
   Nome da empresa	Cymbal Shops
   Localização	global

3. Crie um repositório de dados do Agent Search com esta configuração:

   Campo	Valor
   Fonte de dados	Cloud Storage
   Tipo de dados	Documentos
   Pasta ou arquivo	Arquivo
   Arquivo para importar	-bucket/Cymbal_Shops_Paint_Datasheets.pdf
   Localização	global
   Nome do repositório de dados	Cymbal Paint
   Analisador de documentos	Analisador de layouts
   Ativar anotações nas tabelas	Ativado
   Incluir títulos ancestrais em blocos	Ativado

4. Selecione o Modelo de preços como Geral para o app e o repositório de dados.

Clique em Verificar meu progresso para conferir o objetivo. Criar um repositório de dados e um app de pesquisa.

Tarefa 2: instalar o ADK e configurar o ambiente

Neste ambiente de laboratório, a API Agent Platform já foi ativada para você. Se você fosse executar essas etapas no seu projeto, seria necessário ativá-las acessando a Agent Platform e seguindo o comando para ativação.

Preparar uma guia do editor do Cloud Shell

1. Clique em Ativar o Cloud Shell () na barra de título do console do Google Cloud.

   Observação: como alternativa, selecione a guia do navegador do console e pressione G e S para abrir o terminal do Cloud Shell.

2. Clique em Continuar.

3. Se for preciso autorizar o Cloud Shell, clique em Autorizar.

4. No canto superior direito do painel do terminal do Cloud Shell, clique no botão Abrir em uma nova janela .

5. Clique no ícone de lápis Abrir editor () na parte de cima do painel para visualizar os arquivos.

6. Na parte de cima do menu de navegação à esquerda, clique no ícone do Explorer () para abrir o explorador de arquivos.

7. Clique no botão Abrir pasta.

8. Na caixa de diálogo "Abrir pasta" exibida, clique em OK para selecionar a pasta inicial da sua conta de estudante do Qwiklabs.

9. Feche qualquer outro tutorial ou painel do Gemini que apareça no lado direito da tela. Assim você terá mais espaço na janela do editor de código.

10. Durante o restante deste laboratório, você pode trabalhar nesta janela como seu ambiente de desenvolvimento integrado (IDE, na sigla em inglês) com o editor e o terminal do Cloud Shell.

Baixar e instalar o ADK e os exemplos de código para este laboratório

1. Cole o comando a seguir no terminal do Cloud Shell para copiar arquivos de um bucket do Cloud Storage, criando um diretório de projeto com o código deste laboratório:

   gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_challenge_lab . 2> /dev/null

2. Execute os comandos abaixo no terminal do Cloud Shell para atualizar a variável de ambiente PATH e instalar o ADK e outros requisitos do laboratório.

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install -r adk_challenge_lab/requirements.txt python3 -m pip install chainlit==2.11.1

3. Copie os comandos abaixo para um arquivo de texto. Atualize o valor de SEARCH_ENGINE_ID de YOUR_ID para o ID do mecanismo de pesquisa que você acabou de criar. Ele vai aparecer como paint-search_1756… na lista de apps em Agent Platform > Agentes > Pesquisa:

   cd ~/adk_challenge_lab cat << EOF > .env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION={{{project_0.default_region| GCP_LOCATION}}} RESOURCES_BUCKET={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} SEARCH_ENGINE_ID=YOUR_ID EOF

4. Execute os comandos que você editou no terminal do Cloud Shell para criar um arquivo .env com variáveis de autenticação e configuração de modelos. [Observação: para visualizar arquivos ocultos (que começam com um ponto), os menus do editor do Cloud Shell podem ser usados para habilitar a opção Visualizar > Ativar/Desativar arquivos ocultos]

5. Copie o arquivo .env para o diretório do agente para fornecer as configurações de autenticação necessárias ao agente após a implantação:

   cp .env paint_agent/.env

Tarefa 3: depurar o Agente de Pintura

Um colega seu começou a trabalhar no Agente de Pintura, mas acabou se deparando com problemas. Você vai assumir o desenvolvimento de onde ele parou, corrigir o bug apontado e finalizar a implementação do agente.

1. No terminal do Cloud Shell, execute a versão atual do agente com:

   adk run paint_agent

2. Quando o comando [user]: aparecer, digite:

   hello

   Se o agente perguntar se você quer mais informações sobre as tintas da Cymbal Shops, responda:

   yes

   O resultado esperado termina com:

   ... google.genai.errors.ClientError: 400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': 'Multiple tools are supported only when they are all search tools.', 'status': 'INVALID_ARGUMENT'}}

   Nas próximas etapas, você vai resolver esse erro.

3. Abra o arquivo adk_challenge_lab/paint_agent/agent.py e inspecione as listas de subagentes e ferramentas usadas pelo root_agent. Observe que ele inclui subagentes. A transferência para subagentes invoca uma ferramenta implícita transfer_to_agent.

4. A ferramenta do root_agent não é uma ferramenta de pesquisa, então pelo menos um dos subagentes precisa invocar uma ferramenta de pesquisa. Confira os subagentes encontrados no diretório sub_agents para encontrar a ferramenta de pesquisa usada (nesse caso, uma VertexAiSearchTool):

   Teste seus conhecimentos (a resposta será revelada conforme você avança):

5. Ainda que uma ferramenta de pesquisa não possa ser combinada com outras que não sejam de pesquisa em um agente (mesmo se for usada em um subagente, como visto aqui), o ADK oferece o AgentTool, que pode incluir um agente isolado que usa uma ferramenta de pesquisa. Esse agente como ferramenta pode ser usado com outras ferramentas.

   No arquivo root_agent adk_challenge_lab/paint_agent/agent.py, adicione um AgentTool() à lista de ferramentas do root_agent. Insira estes argumentos em AgentTool():

   • agent deve ser definido como search_agent (o subagente que usa a ferramenta de pesquisa que você descobriu acima).
   • skip_summarization deve ser definido como False, porque você quer que o agente relate o retorno da ferramenta de pesquisa.

6. Remova o subagente da lista sub_agents.

7. Salve o arquivo.

   Observação: só prossiga depois que o repositório de dados for criado e o documento for indexado. Monitore esse status no repositório de dados Agent Platform > Agentes > Pesquisa > Repositórios de dados > Cymbal Paint na guia Documentos.

   Na prática, você vai receber uma saída mais confiável se esperar alguns minutos antes de consultar o agente depois que o status Pronto for exibido.

8. No terminal do Cloud Shell, execute o agente novamente usando este comando:

   adk run paint_agent

   Agora é possível conversar com o agente e receber informações sobre as tintas da Cymbal Shops.

9. Peça que ele informe os preços das tintas EcoGreens e Forever Paint.

   
   

   Clique em Verificar meu progresso para conferir o objetivo. Depurar o agente.

10. Quando você terminar de conversar com o agente pela interface de linha de comando, digite exit para encerrar a sessão.

Tarefa 4: salvar e usar o estado compartilhado

Seu root_agent importa e usa uma ferramenta set_session_value do adk_challenge_lab/paint_agent/tools.py. A intenção é coletar informações como SELECTED_PAINT e COVERAGE_RATE do usuário, armazená-las na sessão e usá-las no chat com várias rodadas. No entanto, ela não está totalmente implementada.

1. Atualize a função set_session_value no arquivo adk_challenge_lab/paint_agent/tools.py para armazenar pares de key-value no dicionário state do ToolContext.

2. Atualize a resposta da função para retornar uma mensagem de status f"stored '{value}' in '{key}'".

3. Abra o arquivo agent.py associado ao coverage_calculator_agent (subagente do room_planner, que é um subagente do seu root_agent).

4. Observe que as instruções não estão carregando os valores corretamente do dicionário de estado. Atualize a instrução para substituir os termos em ALL CAPS e passar a usar modelos de chaves do ADK para carregar valores de estado nas instruções. Use a sintaxe opcional (por exemplo, {SELECTED_PAINT?}) para garantir que o agente não falhe se for invocado antes que uma chave de estado seja preenchida.

5. Teste o agente usando este comando:

   adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

6. Selecione paint_agent.

7. Agora você pode ter esta conversa com seu agente:

   Você	Resposta do agente
   hello	[Oferece informações sobre as tintas da Cymbal Shops]
   yes	[Compartilha informações sobre produtos de tintas, como Project Paint, EcoGreens, SureCoverage e Forever Paint.]
   I'd like to use EcoGreens	[A guia Estado deve mostrar os valores de estado atualizados. Pergunta o número de cômodos e os nomes deles.]
   Just one room, my office	[Pede para você selecionar uma cor para seu escritório.]
   Deep Ocean	[Pede as dimensões do cômodo.]
   3m by 4m. 3m high. 1 door, 2 windows.	[Confirma quantas demãos.]
   Two coats.	[Calcula que você vai precisar de uma cobertura de 74 metros quadrados.]

   Observação: para garantir que as imagens dos produtos sejam exibidas corretamente, ative os cookies de terceiros deste domínio nas configurações do navegador e atualize a página.

8. Quando terminar de conversar com o agente, feche a guia do navegador da interface de desenvolvimento.

   Clique em Verificar meu progresso para conferir o objetivo. Definir e usar o estado da sessão

9. Selecione o painel do terminal do Cloud Shell e pressione CTRL+C para desligar o servidor.

Tarefa 5: implantar no Agent Runtime

1. No terminal do Cloud Shell, confirme que você está no diretório adk_challenge_lab:

   cd ~/adk_challenge_lab

2. Implante o agente no Agent Runtime usando o comando adk deploy agent_engine. Você precisa incluir o diretório do agente como o argumento posicional final (por exemplo, . se você estiver no diretório). Use o seguinte argumento:

   Parâmetro	Argumento
   --display_name	"Paint Agent"

   Observação: o comando de implantação pode levar de 5 a 10 minutos para ser concluído.

3. À medida que o agente for implantado, conceda os papéis do IAM Usuário da Agent Platform e Usuário do Discovery Engine para a conta de serviço .

4. Quando a implantação for concluída, o nome do recurso do agente implantado será exibido no console.

   Clique em Verificar meu progresso para conferir o objetivo. Implantar no Agent Runtime

Tarefa 6: consultar o agente implantado

1. No arquivo adk_challenge_lab/chainlit_ui/app.py, encontre e atualize a linha abaixo com o nome do recurso do agente implantado para carregar o agente remoto:

   agent = client.agent_engines.get(name='YOUR_AGENT_RESOURCE_NAME')

2. Execute a interface usando este comando:

   cd ~/adk_challenge_lab/chainlit_ui chainlit run app.py

   Resposta esperada:

   2025-08-25 12:30:00 - Your app is available at http://localhost:8000

3. Clique no link http://localhost:8000 para abrir em uma nova guia do navegador.

4. Tenha a conversa abaixo com o agente implantado:

   Você	Resposta do agente
   hello	[Oferece informações sobre as tintas da Cymbal Shops]
   yes	[Compartilha informações sobre produtos de tintas, como Project Paint, EcoGreens, SureCoverage e Forever Paint]
   I'd like to use Forever Paint	[Pergunta o número de cômodos e os nomes deles]
   Two rooms. The living room and a baby's room.	[Pede para você selecionar uma cor para sua sala de estar e quarto do bebê.]
   "Sunlight through a canvas tent" for the baby's room and "Coffee Cream" for the living room.	[Pede as dimensões do cômodo]
   The living room is 5m by 4m. 2.5m high. 1 door, 3 windows.	[Pergunta o número de demãos.]
   Two coats.	[Pede as dimensões do quarto do bebê.]
   The baby's room is 3m by 3m. 2.5m high. 1 door, 1 window.	[Oferece uma estimativa de uma demão e confirma o número de demãos.]
   Always two coats.	[Calcula que você vai precisar de uma cobertura de 77 metros quadrados para a sala de estar e 53 metros quadrados para o quarto do bebê.]

5. Para começar uma conversa com o agente, clique no ícone "Criar uma conversa" no canto superior esquerdo.

   Clique em Verificar meu progresso para conferir o objetivo. Configurar um front-end para consultar seu agente

Parabéns!

Neste laboratório, você:

• Usou o Kit de Desenvolvimento de Agente (ADK) para criar um agente composto de um agente raiz e subagentes
• Capacitou agentes com uma ferramenta do Agent Search e funções Python usadas como ferramentas
• Armazenou a saída do agente em um dicionário de estado da sessão e recuperou valores do dicionário para instruções subsequentes do agente
• Implantou o agente no Agent Runtime
• Consultou o agente implantado no Agent Runtime

Treinamento e certificação do Google Cloud

Esses treinamentos ajudam você a aproveitar ao máximo as tecnologias do Google Cloud. Nossas aulas incluem habilidades técnicas e práticas recomendadas para você alcançar rapidamente o nível esperado e continuar sua jornada de aprendizado. Os treinamentos vão do nível básico ao avançado, com opções de aulas virtuais, on demand e transmissões ao vivo que cabem na correria do seu dia a dia. As certificações comprovam suas habilidades e experiência com as tecnologias do Google Cloud.

Manual atualizado em 2 de julho de 2026

Laboratório testado em 2 de julho de 2026

Copyright 2026 Google LLC. Todos os direitos reservados. Google e o logotipo do Google são marcas registradas da Google LLC. Todos os outros nomes de empresas e produtos podem ser marcas registradas das empresas a que estão associados.