GENAI129

Visão geral

Neste laboratório, você vai demonstrar sua capacidade de criar agentes usando o Kit de Desenvolvimento de Agente (ADK), 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 a ferramenta Vertex AI para Pesquisa e ferramentas de função personalizada
• 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 Engine
• Consultar o agente implantado no Agent Engine

Materiais de aprendizado 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 Olá.

   {{{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, é possível que 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 gratuitos.

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 folhas de dados de produtos de tinta 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ê é o novo engenheiro de ML da Cymbal Shops. Sua tarefa é concluir a implantação do Agente de Pintura. Confira a estrutura do agente:

Tarefa 1: instalar o ADK e configurar o ambiente

Neste ambiente de laboratório, a API Vertex AI já foi ativada para você. Para ativar o recurso no seu projeto, acesse a Vertex AI e siga essas etapas.

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

Tarefa 2: criar um app de pesquisa do AI Applications com informações sobre produtos de tinta

Nesta tarefa, você vai implantar um repositório de dados do AI Applications. Esse repositório vai importar uma folha de dados 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 folha de dados vai atuar como fonte de dados de embasamento para as consultas dos usuários sobre as tintas.

1. Crie um repositório de dados do AI Applications 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
   Habilitar anotações nas tabelas	Ativado
   Incluir títulos ancestrais em blocos	Ativado

2. Crie um app de pesquisa do IA Applications com esta configuração:

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

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 no AI Applications:

   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

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

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:

   olá

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

   yes

   A saída esperada 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 agente raiz 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):

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 para AgentTool():

   • agent deve ser definido como 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.

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 o preço 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, mas 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.

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
   olá	[Oferece informações sobre as tintas da Cymbal Shops]
   sim	[Compartilha informações sobre produtos de tintas, como Project Paint, EcoGreens, SureCoverage e Forever Paint.]
   Gostaria de usar o EcoGreens	[A guia Estado deve mostrar os valores de estado atualizados. Pergunta o número de cômodos e como chamar cada um deles.]
   Só uma sala, meu escritório	[Pede para você selecionar uma cor para seu escritório.]
   Deep Ocean	[Pede as dimensões do cômodo.]
   3 m por 4 m. 3 m de altura. 1 porta, 2 janelas.	[Confirma quantas demãos.]
   Duas demãos.	[Calcula que você vai precisar de uma cobertura de 74 metros quadrados.]

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 Engine

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

   cd ~/adk_challenge_lab

2. Implante o agente com o comando de implantação apropriado para implantar o paint_agent no Agent Engine usando estes argumentos:

   Parâmetro	Argumento
   --display_name	"Paint Agent"
   --staging_bucket	gs://-bucket

3. À medida que o agente for implantado, conceda os papéis do IAM Usuário da Vertex AI e Usuário do Discovery Engine para o Agente de serviço do Vertex AI Reasoning Engine.

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 Engine

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
   olá	[Oferece informações sobre a Cymbal Paints]
   sim	[Compartilha informações sobre produtos de tintas, como Project Paint, EcoGreens, SureCoverage e Forever Paint]
   Gostaria de usar a Forever Paint	[Pergunta o número de cômodos e como chamar cada um deles]
   Dois cômodos. A sala e um quarto de bebê.	[Pede para você selecionar uma cor para seu escritório.]
   "Sunlight through a canvas tent" para o quarto do bebê e "Coffee Cream" para a sala.	[Pede as dimensões do cômodo]
   A sala tem 5 m por 4 m. 2,5 m de altura. 1 porta, 3 janelas.	[Pergunta o número de demãos.]
   Duas demãos.	[Pede as dimensões do quarto do bebê.]
   O quarto do bebê é de 3 m por 3 m. 2,5 m de altura. 1 porta, 1 janela.	[Oferece uma estimativa de uma demão e confirma o número de demãos.]
   Sempre duas demãos.	[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 da Vertex AI para Pesquisa e ferramentas de função personalizada
• 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 Engine
• Consultou o agente implantado no Agent Engine

Treinamento e certificação do Google Cloud

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

Manual atualizado em 26 de fevereiro de 2026

Laboratório testado em 26 de fevereiro 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 produtos e empresas podem ser marcas registradas das respectivas empresas a que estão associados.