GSP532

Visão geral do desafio

Nos laboratórios com desafio, apresentamos uma situação e um conjunto de tarefas. Para concluí-las, em vez de seguir instruções detalhadas, você usará o que aprendeu nos laboratórios do curso. Um sistema automático de pontuação (mostrado nesta página) vai avaliar seu desempenho.

Nos laboratórios com desafio, não ensinamos novos conceitos do Google Cloud. O objetivo dessas tarefas é aprimorar aquilo que você já aprendeu, como a alteração de valores padrão ou a leitura e pesquisa de mensagens para corrigir seus próprios erros.

Para alcançar a pontuação de 100%, você precisa concluir todas as tarefas no tempo definido.

Este laboratório é recomendado para estudantes que se inscreveram no curso Criar um aplicativo de nuvem inteligente com vibe coding. Tudo pronto para começar o desafio?

Conhecimentos avaliados

• Ativar as APIs e definir as variáveis de ambiente.
• Realizar as vinculações de política do IAM.
• Implantar o servidor MCP localmente para testes e implantar no Cloud Run.
• Usar o Kit de Desenvolvimento de Agente (ADK) para atualizar o aplicativo Python e usar o MCP.
• Implantar o servidor MCP e o agente do ADK no Cloud Run e colocá-los no Docker.

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

Observação: para executar este laboratório, use o modo de navegação anônima (recomendado) ou uma janela anônima do navegador. Isso evita conflitos entre sua conta pessoal e de estudante, o que poderia causar cobranças extras na sua conta pessoal.

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

Observação: use apenas a conta de estudante neste laboratório. Se usar outra conta do Google Cloud, você poderá receber cobranças nela.

Cenário do desafio

O zoológico Cloud Creek contratou a divisão de consultoria de experiência digital do grupo Cymbal para implementar um sistema de última geração de engajamento de visitantes. O objetivo final do zoológico é ter um guia turístico com tecnologia de IA de grande precisão, dinâmico e envolvente que dê respostas detalhadas e contextuais às perguntas dos visitantes. A principal meta é implementar e melhorar o agente de IA "guia turístico do zoológico", capaz de executar pesquisas sobre animais usando um servidor remoto do Protocolo de Contexto de Modelo (MCP, na sigla em inglês), o "servidor do zoológico".

Além de usar a Wikipédia para contextualização ao responder às perguntas dos visitantes, o agente "guia turístico do zoológico" precisa ter acesso a informações amplas e em tempo real usando uma ferramenta do servidor MCP da Pesquisa Google. Isso daria ao agente a capacidade de responder a solicitações como: "Me dê notícias recentes sobre a conservação da espécie leão."

Um consultor júnior cometeu alguns erros ao fazer upgrade do servidor do zoológico usado atualmente, o que resultou em um servidor Python com falhas e não funcional. Além disso, a arquitetura do projeto ainda não havia sido finalizada de acordo com as rígidas políticas de IAM do Cymbal Group.

Chamaram você para resolver esses problemas.

Seu desafio

Nesse laboratório, sua missão como especialista sênior em integração de IA do Cymbal Group é:

• Configurar o projeto e ativar as APIs e os serviços necessários.
• Aplicar a política de IAM corporativa.
• Corrigir o código do servidor MCP com falha e implantar o sistema no Cloud Run para testes.
• Integrar e fazer upgrade da funcionalidade e do fluxo de trabalho do agente de IA do ADK "guia turístico do zoológico" para dar suporte à Pesquisa Google.
• Colocar o pacote do agente ADK no Docker e implantá-lo no Cloud Run para alcançar a prontidão para produção.

Tarefa 1: Configurar o ambiente e ativar as APIs necessárias

Nesta tarefa, você vai criar a base específica do projeto no Google Cloud para apoiar uma implantação de IA em grande escala.

Verifique se o projeto do Google Cloud está configurado de forma a permitir que os serviços necessários funcionem e se comuniquem de maneira eficaz.

Baixe os arquivos de código

1. No Cloud Shell, clique em Abrir editor para acessar o editor do Cloud Shell no seu diretório principal.

2. Na barra de ações do editor do Cloud Shell, clique em Visualizar > Terminal.

   Observação: talvez você precise aumentar o tamanho da janela do navegador ou clicar em Mais opções () para ver a opção de menu Visualizar.

Use esta janela como seu ambiente de desenvolvimento integrado (IDE, na sigla em inglês), com o editor do Cloud Shell (acima) e o terminal do Cloud Shell (abaixo) durante o restante deste laboratório.

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

3. No terminal, insira este comando para configurar o projeto:

   gcloud config set project {{{primary_project.project_id | filled in at lab start}}}

   Saída esperada: você vai receber uma mensagem de saída confirmando a propriedade atualizada.

4. No terminal, execute os seguintes comandos para baixar e extrair os arquivos de código boilerplate:

   gcloud storage cp gs://{{{primary_project.project_id | filled in at lab start}}}-labconfig-bucket/labs_code.zip . unzip labs_code.zip

5. Execute os seguintes comandos para criar as variáveis de ambiente:

   cd ~/zoo_guide_agent cat <<EOF > .env MODEL="{{{primary_project.startup_script.gemini_flash_model_id |filled in at lab start}}}" SERVICE_ACCOUNT="{{{primary_project.startup_script.project_number | filled in at lab start}}}-compute@developer.gserviceaccount.com" MCP_SERVER_URL="https://{{{primary_project.startup_script.mcp_server_name | filled in at lab start}}}-{{{primary_project.startup_script.project_number | filled in at lab start}}}.{{{primary_project.default_region | filled in at lab start}}}.run.app/mcp/" GOOGLE_GENAI_USE_ENTERPRISE=1 GOOGLE_CLOUD_PROJECT={{{primary_project.project_id | filled in at lab start}}} PROJECT_NUMBER={{{primary_project.startup_script.project_number | filled in at lab start}}} GOOGLE_CLOUD_LOCATION={{{primary_project.default_region | filled in at lab start}}} EOF

   Sua estrutura de diretórios final deve ser semelhante a esta:

   Saída:

   . ├── mcp-on-cloudrun │ ├── Dockerfile │ ├── local_mcp_call.py │ ├── pyproject.toml │ ├── server.py │ └── uv.lock └── zoo_guide_agent ├── agent.py ├── __init__.py ├── .env └── requirements.txt

6. Por fim, ative as APIs necessárias: API Agent Platform, API Artifact Registry, API Compute Engine, API Cloud Build e API Cloud Run Admin.

Clique em Verificar meu progresso para conferir o objetivo. Ative as APIs necessárias.

Tarefa 2: Realizar as vinculações de política necessárias (configuração do IAM)

Os serviços automatizados (Cloud Build e Cloud Run) precisam de permissões específicas para interagir entre si e com o AI Platform.

Nesta tarefa, você precisa realizar as vinculações de políticas necessárias para dar ao usuário/conta de serviço permissões para invocar o Cloud Run e usar o AI Platform.

Você precisa conceder os seguintes papéis do IAM às respectivas contas de serviço:

• Conceda os papéis Cloud Run Admin e Agent Platform User ao usuário para permitir que essa pessoa implante serviços no Cloud Run.

Clique em Verificar meu progresso para conferir o objetivo. Realizar as vinculações de política necessárias

Tarefa 3: Corrigir e implantar o servidor MCP no Cloud Run

Nesta tarefa, você vai usar a CLI do Gemini para solucionar problemas e revitalizar o servidor MCP, que atua como a estrutura central do aplicativo e orquestra o uso de ferramentas de IA.

Depois de corrigir os problemas no código, use o comando de integração do Cloud Build relevante na CLI do Gemini para implantar o servidor MCP remoto preexistente no repositório da interface de linha de comando para fazer testes.

Implantar e testar localmente

1. No terminal, use os comandos a seguir para executar ~/mcp-on-cloudrun/server.py:

   cd ~/mcp-on-cloudrun uv run server.py

   Você vai receber um erro, que precisa ser corrigido usando o Gemini no Cloud Shell.

   Observação: a CLI do Gemini pode levar algum tempo para atualizar e fazer alterações no código no arquivo Python real. Se a CLI pedir sua permissão para executar o arquivo Python que ela corrigiu, pressione ESC para cancelar e saia da ferramenta para retornar ao terminal. Depois siga as próximas etapas para continuar com o laboratório.

2. Execute novamente o comando anterior assim que o erro for corrigido. Isso vai iniciar o MCP server localmente, e você vai receber uma saída confirmando isso.

3. Abra outra instância do terminal e execute ~/mcp-on-cloudrun/local_mcp_call.py para testar o agente implantado localmente:

   Observação: se você receber um erro google.logging.v2.WriteLogEntriesPartialErrors, defina o projeto usando o comando gcloud config set project . cd ~/mcp-on-cloudrun uv run local_mcp_call.py

   Saída esperada: a saída resultante, apresentada como um CallToolResult, deve mostrar a recuperação bem-sucedida de dados estruturados sobre a espécie morsa.

Clique em Verificar meu progresso para conferir o objetivo. Implantar e testar o MCP localmente

Implantar no Cloud Run

Observação: se for solicitado, você precisa autorizar o Cloud Shell durante o processo de implantação.

• Execute o seguinte comando gcloud para implantar o aplicativo no Cloud Run:

  cd ~/mcp-on-cloudrun gcloud run deploy {{{primary_project.startup_script.mcp_server_name | filled in at lab start}}} \ --no-allow-unauthenticated \ --region={{{primary_project.default_region | filled in at lab start}}} \ --source=. \ --min=1 \ --project={{{primary_project.project_id | filled in at lab start}}} \ --labels=lab-dev=mcp-zoo-cloud-run-service

Observação: a implantação pode levar até 10 minutos. Se você encontrar um erro Quota exceeded for total allowable CPU per project per region durante a implantação do Cloud Run, aguarde um pouco e tente o comando novamente.

Clique em Verificar meu progresso para conferir o objetivo. Implantação do MCP no Cloud Run

Tarefa 4: Atualizar o agente para usar o MCP

Nesta tarefa, você vai implantar o código do agente Python e vinculá-lo ao servidor MCP recém-implantado.

Usando os comandos do ADK na CLI do Gemini, implante o arquivo local (atualizado) agent.py. Configure essa implantação para usar o servidor MCP implantado na Tarefa 3, tornando o guia turístico do zoológico operacional no seu ambiente de CLI local.

Gerar tokens e configurar o arquivo settings.json

1. Salve suas credenciais do Google Cloud e o número do projeto em variáveis de ambiente para usar no arquivo de configurações do Gemini:

   export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)") export ID_TOKEN=$(gcloud auth print-identity-token)

Observação: se você receber um erro de autenticação na CLI do Gemini, é possível que seu ID_TOKEN tenha expirado. Saia com /quit e defina o projeto usando o comando gcloud config set project.

2. No editor do Cloud Shell, selecione Visualizar > Ativar/desativar arquivos ocultos e abra ou crie o arquivo ~/.gemini/settings.json para atualizá-lo. Preencha o conteúdo do arquivo com as seguintes configurações da CLI do Gemini para adicionar o servidor MCP do Cloud Run:

   { "mcpServers": { "zoo-remote": { "httpUrl": "https://{{{primary_project.startup_script.mcp_server_name | filled in at lab start}}}-{{{primary_project.startup_script.project_number | filled in at lab start}}}.{{{primary_project.default_region | filled in at lab start}}}.run.app/mcp/", "headers": { "Authorization": "Bearer $ID_TOKEN" } } }, "selectedAuthType": "cloud-shell", "hasSeenIdeIntegrationNudge": true }

Abrir a CLI do Gemini

Siga as etapas abaixo para abrir a CLI do Gemini.

1. No terminal, execute o comando para iniciar a CLI.

   Talvez seja necessário pressionar ENTER para aceitar algumas configurações padrão.

2. Use o comando de barra relevante para que o Gemini liste as ferramentas do MCP disponíveis no contexto.

3. Peça ao Gemini para encontrar alguma coisa no zoológico:

   Onde encontro pinguins?

   A CLI do Gemini deve saber usar o servidor MCP zoo-remote e perguntar se você permite a execução da ferramenta MCP.

4. Escolha sempre permitir todas as ferramentas do servidor MCP zoo-remote.

   Resposta esperada: a saída deve mostrar a resposta correta e uma caixa de exibição indicando que o servidor MCP foi usado.

5. Solicite à CLI do Gemini para que use o novo comando personalizado que você criou da seguinte forma:

   /find --animal="lion"

   Saída esperada: você verá que a CLI do Gemini chama a ferramenta fetch_animals_by_species e formata a resposta conforme as instruções do comando do MCP.

6. Para encerrar a sessão, saia da CLI do Gemini usando o comando ou os atalhos de teclado relevantes.

Verificar os registros do servidor

• No terminal, digite o seguinte para verificar os registros do servidor:

  gcloud run services logs read {{{primary_project.startup_script.mcp_server_name | filled in at lab start}}} --region {{{primary_project.default_region| filled in at lab start}}} --limit=5

  Saída esperada: você verá um registro de saída que confirma que foi feita uma chamada de ferramenta. 🛠️

Clique em Verificar meu progresso para conferir o objetivo. Atualizar o agente para usar o MCP e verificar

Tarefa 5: Implantar o agente do ADK no Cloud Run e colocá-lo no Docker.

Na tarefa final, você precisa migrar todo o sistema do seu ambiente de teste local para um ambiente sem servidor escalonável e pronto para produção.

Você precisa transformar em contêiner o aplicativo ADK completo, incluindo o servidor MCP e o agente do guia turístico do zoológico que tem o Google Pesquisa integrado e implantar as imagens de contêiner resultantes no Google Cloud Run. Você precisa garantir que o serviço esteja configurado para invocação pública e confirmar se o agente está respondendo no URL público.

Implantar e testar localmente

1. Abra ~/zoo_guide_agent/agent.py, revise os comentários TODO e atualize o código adequadamente para concluir a configuração do agente.

2. Execute os comandos a seguir para instalar o pacote zoo_guide_agent:

   gcloud config set project {{{primary_project.project_id | filled in at lab start}}} cd ~/zoo_guide_agent python -m venv .venv source .venv/bin/activate pip install --no-cache-dir -r requirements.txt

3. Execute o seguinte comando para implantar o agente do ADK localmente:

   cd ~ adk web

4. No Cloud Shell, pressione CTRL e clique no link http://localhost:8000 ou http://127.0.0.1:8000 para abrir a interface de desenvolvimento do ADK em uma nova guia do navegador.

5. Na interface de desenvolvimento do ADK, selecione zoo_guide_agent e faça a seguinte consulta:

   Onde encontro ursos?

   Saída esperada: você verá eventos para todas as chamadas de função e uma resolução para sua consulta que combina informações de todas as fontes. O agente também deve fornecer um valor aproximado do número de espécies de urso no mundo.

Observação: o agente pode levar algum tempo para dar a resposta.

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

Implantar no Cloud Run

• No terminal, abra outra instância e execute os comandos a seguir para implantar o agente:

  cd ~/zoo_guide_agent uvx --from google-adk \ adk deploy cloud_run \ --project={{{primary_project.project_id | filled in at lab start}}} \ --region={{{primary_project.default_region| filled in at lab start}}} \ --service_name={{{primary_project.startup_script.adk_server_name | filled in at lab start}}} \ --with_ui \ . \ -- \ --labels=lab-dev=cloud-zoo-run-adk-service

O comando uvx permite executar ferramentas de linha de comando publicadas como pacotes Python sem exigir uma instalação global dessas ferramentas.

Observação: a conclusão da implantação pode levar 15 minutos, em média. Se for solicitada a confirmação da sua permissão para invocações não autenticadas, digite y para continuar.

Clique em Verificar meu progresso para conferir o objetivo. Implantar o agente do ADK no Cloud Run

Verificar o agente do ADK implantado

Agora que o agente está ativo no Cloud Run, faça um teste para confirmar que a implantação foi bem-sucedida e que o agente está funcionando conforme o esperado. Usar o URL do serviço público para acessar a interface da web do ADK e interagir com o agente.

1. Depois que o agente for implantado no Cloud Run, pressione CTRL e clique no URL do serviço na saída para abrir em uma nova guia do navegador.

O URL provavelmente terá o formato a seguir.

Saída de URL do serviço:

https://{{{primary_project.startup_script.adk_server_name | filled in at lab start}}}-{{{primary_project.startup_script.project_number | filled in at lab start}}}.{{{primary_project.default_region | filled in at lab start}}}.run.app/

Como você usou a flag --with_ui ao implantar no Cloud Run, a interface do desenvolvedor do ADK deve aparecer.

2. Deixe a opção Streaming de token Ligada no canto superior direito.

3. Interaja com o agente do zoológico. Digite a consulta a seguir para iniciar uma nova conversa:

   Onde encontro elefantes?

   Saída esperada: você verá eventos para todas as chamadas de função com uma resolução para sua consulta que combina informações de todas as fontes. O agente também deve fornecer um valor aproximado do número de espécies de elefante no mundo.

Observação: o agente pode levar algum tempo para dar a resposta.

Clique em Verificar meu progresso para conferir o objetivo. Verificar o agente do ADK implantado

Parabéns!

Neste laboratório, você demonstrou sua capacidade de usar a CLI do Gemini com o Google Cloud Run e o Cloud Build para configurar, testar e implantar um agente ADK aprimorado e funcional de "guia turístico do zoológico". O zoológico Cloud Creek tem feito esforços no sentido da transformação digital do local. Ao garantir a interação do agente com um servidor MCP dedicado e com ferramentas integradas, você melhora e simplifica significativamente o tratamento de consultas e pesquisas de animais feitas por visitantes do zoológico.

Próximas etapas / Saiba mais

Confira os recursos a seguir para saber mais sobre a IA generativa e a Gemini Enterprise Agent Platform:

• Confira a Visão geral dos modelos do Gemini do Google DeepMind para saber mais sobre os principais recursos do modelo.
• Confira a documentação oficial da Agent Platform para ver as diretrizes de design, escalonamento e implantação.
• Confira a Visão geral dos agentes na Agent Platform para entender como criar e gerenciar agentes personalizados.
• Assista à playlist de IA generativa no YouTube para conferir tutoriais em vídeo e demonstrações de produtos.
• Conheça outros notebooks e exemplos no Repositório da IA generativa do Google Cloud (em inglês).
• Confira o repositório de amostras do Kit de Desenvolvimento de Agente (ADK) do Google para ver os modelos de agentes personalizados.

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 16 de outubro de 2025

Laboratório testado em 16 de outubro de 2025

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.