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 Start Lab

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

Este laboratório prático do Qwiklabs permite que você realize as atividades em um ambiente real de nuvem, não em um ambiente simulado ou de demonstração. Isso é possível porque você recebe credenciais novas e temporárias para fazer login e acessar o Google Cloud Platform durante o laboratório.

O que é necessário

Para fazer este laboratório, você precisa ter:

• acesso a um navegador de Internet padrão (recomendamos o Chrome);
• tempo para concluir todas as atividades.

Observação: não use um projeto seu nem uma conta pessoal do GCP neste 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

Observação: o recomendado é usar uma janela de navegação anônima na maioria dos laboratórios do Qwiklabs para evitar confusão entre sua conta de estudante do Qwiklabs e outras contas conectadas ao Google Cloud. Se você estiver usando o Chrome, a maneira mais fácil de fazer isso é fechar todas as janelas anônimas, clicar com o botão direito do mouse no botão Abrir console do Google Cloud na parte de cima do laboratório e selecionar Abrir link em uma janela anônima.

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. No terminal do Cloud Shell, insira o seguinte código para abrir o editor no seu diretório principal:

   cloudshell workspace ~

6. Feche qualquer outro tutorial ou painel do Gemini que apareça no lado direito da tela. Assim você terá mais espaço para o editor de código.
7. Durante o restante deste laboratório, você pode trabalhar nessa janela como seu IDE com o editor do Cloud Shell e o terminal do Cloud Shell.

Baixe e instale o ADK e os exemplos de código para este laboratório

1. 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 google-adk

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

3. Instale outros requisitos do laboratório com:

   python3 -m pip install -r adk_to_agent_engine/requirements.txt

4. 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, você pode usar os menus do editor do Cloud Shell para habilitar 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={{{project_0.default_region| GCP_LOCATION}}} MODEL=gemini-2.5-flash EOF

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 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 no arquivo:

   google-cloud-aiplatform[adk,agent_engines]==1.110.0

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" \ --staging_bucket gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket

   Você pode acompanhar o status no arquivo de registros que será vinculado 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 o agente concluir a implantação, volte para uma guia do navegador que mostra o console do Cloud e navegue até o Agent Engine pesquisando e selecionando na parte de cima do console.

2. No menu suspenso Região, verifique se o local deste laboratório () está selecionado.

3. O nome de exibição do agente implantado vai aparecer. Clique nele para acessar o painel de monitoramento.

4. Observe as guias Métricas e Sessão, que vão fornecer insights sobre como seu agente está sendo usado.

5. Quando estiver tudo pronto para excluir o agente, selecione Detalhes da implantação na parte de cima do painel de monitoramento.

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

   cd ~/adk_to_agent_engine python3 agent_engine_utils.py delete REPLACE_WITH_AE_ID

7. No painel Informações de implantação do Agent Engine, copie o campo Nome, que terá um formato como: projects/qwiklabs-gcp-02-76ce2eed15a5/locations/us-central1/reasoningEngines/1467742469964693504.

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

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

10. No console do Cloud, volte ao painel do Agent Engine para conferir se o agente foi excluído.

11. 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 19 de agosto de 2025

Laboratório testado em 19 de agosto de 2025

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