GENAI107

Visão geral

Neste laboratório, você vai aprender a implantar agentes do ADK no Agent Engine para ter um ambiente escalonável e totalmente gerenciado para seus fluxos de trabalho de agentes.

Isso permite que você se concentre na lógica dos agentes enquanto a infraestrutura é alocada e escalonada para você.

Objetivo

Neste laboratório, você vai aprender:

• Os benefícios de implantar agentes no Agent Engine
• Como conceder os papéis necessários ao agente de serviço do Reasoning Engine
• Como implantar um agente no Agent Engine usando a interface de linha de comando do ADK
• Como consultar um agente implantado no Agent Engine
• Como monitorar os agentes implantados
• Como excluir agentes

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.

Agent Engine

O Vertex AI Agent Engine (antigamente conhecido como LangChain na Vertex AI ou Vertex AI Reasoning Engine) é um serviço totalmente gerenciado do Google Cloud que permite aos desenvolvedores implantar, gerenciar e escalonar agentes de IA em produção.

Saiba mais sobre os benefícios na documentação do Vertex AI Agent Engine.

Tarefa 1: instalar o ADK e configurar o ambiente

Ative as APIs recomendadas da Vertex AI

1. Neste ambiente de laboratório, a API Vertex AI já foi ativada para você. Se você seguisse essas etapas no seu próprio projeto, poderia ativar o recurso navegando até a Vertex AI e seguindo o comando para ativá-lo.

Prepare uma guia do editor do Cloud Shell

1. Com a janela do console do Google Cloud selecionada, abra o Cloud Shell pressionando as teclas G e S no teclado. Como alternativa, clique no botão "Ativar o Cloud Shell" () no canto superior direito do console do Cloud.
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. Pelo restante deste laboratório, você pode trabalhar nesta janela como seu ambiente de desenvolvimento integrado com o editor e o terminal do Cloud Shell.

Faça o download e instale o ADK e os exemplos de código para este laboratório

1. Cole os comandos a seguir no terminal do Cloud Shell para copiar um arquivo de um bucket do Cloud Storage e descompactá-lo, 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_to_agent_engine .

2. Atualize a variável de ambiente PATH e instale o ADK executando os comandos a seguir no terminal do Cloud Shell.

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

3. Execute os comandos a seguir para criar um arquivo .env no diretório adk_to_agent_engine. (Observação: para visualizar um arquivo oculto que começa com um ponto, use os menus do Editor do Cloud Shell para ativar a opção Visualizar > Ativar/Desativar arquivos ocultos):

   cd ~/adk_to_agent_engine cat << EOF > .env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id| YOUR_GCP_PROJECT_ID}}} GOOGLE_CLOUD_LOCATION=us-central1 MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF

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

   cp .env transcript_summarization_agent/.env

Tarefa 2: Implantar no Agent Engine usando o método de implantação da linha de comando

A interface de linha de comando do ADK oferece atalhos para implantar agentes no Agent Engine, no Cloud Run e no Google Kubernetes Engine (GKE). Você pode usar os seguintes comandos básicos para fazer a implantação em cada um desses serviços:

• adk deploy agent_engine (com os argumentos de linha de comando descritos no decorador @deploy.command("agent_engine"))
• adk deploy cloud_run (com os argumentos de linha de comando descritos no decorador @deploy.command("cloud_run"))
• adk deploy gke (com os argumentos de linha de comando descritos no decorador @deploy.command("gke"))

O comando adk deploy agent_engine encapsula seu agente em uma classe reasoning_engines.AdkApp e implanta esse app no ambiente de execução gerenciado do Agent Engine, pronto para receber consultas direcionadas a agentes.

Quando um AdkApp é implantado no Agent Engine, ele usa automaticamente um VertexAiSessionService para um estado de sessão gerenciado e persistente. Isso fornece uma memória conversacional de vários turnos sem nenhuma configuração adicional. Para testes locais, o aplicativo usa por padrão um InMemorySessionService temporário.

Para implantar um app do Agent Engine usando adk deploy agent_engine, siga estas etapas:

1. No diretório adk_to_agent_engine/transcript_summarization_agent, clique no arquivo agent.py para revisar as instruções deste simples agente de resumo.

2. Para implantar um agente, você precisa fornecer os requisitos dele. No editor do Cloud Shell, clique com o botão direito do mouse no diretório transcript_summarization_agent. Talvez seja necessário clicar em Permitir para ativar o menu do botão direito do mouse.

3. Selecione Novo arquivo...

4. Nomeie o arquivo como um arquivo de requisitos padrão em Python: requirements.txt

5. Cole o seguinte conteúdo no arquivo:

   google-cloud-aiplatform[agent_engines,adk]>=1.112

6. Salve o arquivo.

7. No terminal do Cloud Shell, execute o comando de implantação:

   adk deploy agent_engine transcript_summarization_agent \ --display_name "Transcript Summarizer" \ --region us-central1 \ --staging_bucket gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket

   Acompanhe o status pelo arquivo de registro que será exibido na saída do comando. Durante a implantação, as seguintes etapas estão ocorrendo:

   1. Um pacote de artefatos é gerado localmente, incluindo:
      • *.pkl: um arquivo pickle correspondente ao local_agent.
      • requirements.txt: esse arquivo da pasta do agente define os requisitos do pacote.
      • dependencies.tar.gz: um arquivo tar que contém pacotes extras.
   2. O pacote é enviado para o Cloud Storage (usando um diretório definido, se especificado) para preparar os artefatos.
   3. Os URIs do Cloud Storage para os respectivos artefatos são especificados no PackageSpec.
   4. O serviço Vertex AI Agent Engine recebe a solicitação, cria contêineres e ativa servidores HTTP no back-end.

   Observação: a implantação deve levar cerca de 10 minutos, mas você pode continuar com este laboratório enquanto ela é feita.

   Teste enquanto o agente é implantado

   Cada um dos comandos adk deploy ... exige que certos argumentos sejam definidos. Para conferir os argumentos mais atualizados, clique nos comandos vinculados na lista na parte de cima desta tarefa e procure os argumentos marcados como "Obrigatório".

   Alguns argumentos obrigatórios, como --project e --region da implantação adk deploy agent_engine, podem carregar seus valores do arquivo .env do agente, se estiver presente.

   Responda às perguntas a seguir com base nos argumentos para adk deploy agent_engine:

   Destaques da saída esperada:

   Copying agent source code... Copying agent source code complete. Initializing Vertex AI... [...] Creating AgentEngine Create AgentEngine backing LRO: projects/430282503153/locations/us-central1/reasoningEngines/2902138951282196480/operations/2777364189918789632 View progress and logs at https://console.cloud.google.com/logs/query?project=qwiklabs-gcp-04-f71a2270bd79 AgentEngine created. Resource name: projects/430282503153/locations/us-central1/reasoningEngines/2902138951282196480 To use this AgentEngine in another session: agent_engine = vertexai.agent_engines.get('projects/430282503153/locations/us-central1/reasoningEngines/2902138951282196480') Cleaning up the temp folder: /tmp/agent_engine_deploy_src/20250813_175223

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

Tarefa 3: Receber e consultar um agente implantado no Agent Engine

Para consultar o agente, primeiro você precisa conceder a ele a autorização para chamar modelos usando a Vertex AI.

1. Para ver o agente de serviço e o papel atribuído a ele, acesse IAM no console.

2. Marque a caixa de seleção para Incluir concessões de papéis fornecidos pelo Google.

3. Encontre o Agente de serviço do Reasoning Engine do AI Platform (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) e clique no ícone de lápis de edição na linha desse agente de serviço.

4. Clique em + Adicionar outro papel.

5. No campo Selecionar um papel, digite Usuário da Vertex AI. Se você implantar um agente que usa ferramentas para acessar outros dados, também concederá acesso a esses sistemas a esse agente de serviço.

6. Salve as alterações.

7. De volta ao editor do Cloud Shell, no diretório adk_to_agent_engine, abra o arquivo query_agent_engine.py.

8. Analise o código e os comentários para entender o que ele faz.

9. Analise a transcrição enviada ao agente para avaliar se ele está gerando um resumo adequado.

10. No terminal do Cloud Shell, execute o arquivo do diretório adk_to_agent_engine com:

    cd ~/adk_to_agent_engine/transcript_summarization_agent python3 query_agent_engine.py

    Exemplo de resposta (a sua pode ser um pouco diferente):

    [resposta remota] O usuário quer comprar um barco e, depois de ser perguntado sobre o tamanho, pergunta que tipo de barco ele poderia comprar com US$50.000. O agente virtual responde que com US$50.000 dá para comprar um "barco muito bom", e o usuário concorda em prosseguir.

Clique em Verificar meu progresso para conferir o objetivo. Consultar um agente

Tarefa 4: Ver e excluir agentes implantados no Agent Engine

1. Quando a implantação do agente for concluída, volte à guia do navegador que mostra o console do Cloud e navegue até o Agent Engine pesquisando por ele e selecionando-o na parte superior do Console.

2. No menu suspenso Região, certifique-se de que a região us-central1 esteja selecionada.

3. Você verá o nome de exibição do agente implantado. Clique nele para abrir o painel de monitoramento.

4. Observe as guias Métricas de ambiente de execução, Traces e Sessões, que podem fornecer insights sobre como o agente está sendo usado.

5. Observe o Playground, que permite interagir via chat com o agente implantado.

6. Quando estiver com tudo pronto para excluir o agente, selecione Configuração de serviço na parte superior do console do Agent Engine e, em seguida, acesse a guia Detalhes da implantação.

7. De volta à guia do navegador que executa o terminal do Cloud Shell, cole o comando a seguir, mas ainda não o execute:

   cd ~/adk_to_agent_engine python3 agent_engine_utils.py delete REPLACE_WITH_AE_ID

8. No painel Detalhes da implantação do Agent Engine, copie o campo Nome do recurso, que terá um formato como: projects/qwiklabs-gcp-02-76ce2eed15a5/locations/us-central1/reasoningEngines/1467742469964693504.

9. Volte ao terminal do Cloud Shell e substitua REPLACE_WITH_AE_ID no final do comando pelo nome do recurso que você copiou.

10. Pressione Return para executar o comando de exclusão.

    Exemplo de saída:

    Deleting AgentEngine resource: projects/1029886909158/locations/us-central1/reasoningEngines/1456078850617245696 Delete AgentEngine backing LRO: projects/1029886909158/locations/us-central1/operations/2884525977596067840 AgentEngine resource deleted: projects/1029886909158/locations/us-central1/reasoningEngines/1456078850617245696

11. No console do Cloud, retorne ao painel do Agent Engine para confirmar que o agente foi excluído.

12. Para conferir o código do SDK Python para listar e excluir agentes, veja o conteúdo do arquivo adk_to_agent_engine/agent_engine_utils.py.

Clique em Verificar meu progresso para conferir o objetivo. Listar e excluir agentes

Parabéns!

Neste laboratório, você aprendeu a:

• Os benefícios de implantar agentes no Agent Engine
• Como conceder os papéis necessários ao agente de serviço do Reasoning Engine
• Como implantar um agente no Agent Engine usando a interface de linha de comando do ADK
• Como consultar um agente implantado no Agent Engine
• Como monitorar os agentes implantados
• Como excluir agentes

Próximas etapas

Saiba mais sobre como criar agentes com o Kit de Desenvolvimento de Agentes em outros laboratórios desta série:

• Capacitar agentes do ADK com ferramentas
• Criar sistemas multiagente com o ADK
• Implantar agentes do ADK 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 10 de fevereiro de 2026

Laboratório testado em 10 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.