1. Introdução
Este laboratório se concentra na implementação e implantação de um serviço de agente do cliente. Você vai usar o Kit de Desenvolvimento de Agentes (ADK) para criar um agente de IA que usa ferramentas remotas, como o servidor MCP criado no Laboratório 1. O principal princípio arquitetônico demonstrado é a separação de conceitos, com uma camada de raciocínio distinta (o agente) se comunicando com uma camada de ferramentas distinta (o servidor MCP) por uma API segura.
No laboratório 1, você criou um servidor MCP que fornece dados sobre os animais de um zoológico fictício para LLMs, por exemplo, ao usar a CLI do Gemini. Neste laboratório, vamos criar um agente de guia turístico para o zoológico fictício. O agente vai usar o mesmo servidor MCP do laboratório 1 para acessar detalhes sobre os animais do zoológico e também usar a Wikipédia para criar a melhor experiência de guia turístico.
Por fim, vamos implantar o agente de guia turístico no Google Cloud Run para que ele possa ser acessado por todos os visitantes do zoológico, em vez de apenas ser executado localmente.
Pré-requisitos
- Um servidor MCP em execução no Cloud Run ou o URL do serviço associado.
- Ter um projeto do Google Cloud com o faturamento ativado.
O que você vai aprender
- Como estruturar um projeto Python para implantação do ADK.
- Como implementar um agente que usa ferramentas com o google-adk.
- Como conectar um agente a um servidor MCP remoto para o conjunto de ferramentas dele.
- Como implantar um aplicativo Python como um contêiner sem servidor no Cloud Run.
- Como configurar a autenticação segura entre serviços usando papéis do IAM.
- Como excluir recursos do Cloud para evitar custos futuros.
O que é necessário
- Uma conta e um projeto do Google Cloud
- Um navegador da Web, como o Chrome
2. Por que implantar no Cloud Run?
O Cloud Run é uma ótima opção para hospedar agentes do ADK porque é uma plataforma sem servidor. Isso significa que você pode se concentrar no seu código e não no gerenciamento da infraestrutura subjacente. Nós cuidamos do trabalho operacional para você.
Pense nisso como uma loja temporária: ela só abre e usa recursos quando os clientes (solicitações) chegam. Quando não há clientes, ela fecha completamente, e você não paga por uma loja vazia.
Principais características
Executa contêineres em qualquer lugar:
- Você traz um contêiner (imagem do Docker) com o app dentro.
- O Cloud Run executa na infraestrutura do Google.
- Sem problemas com aplicação de patches no SO, configuração de VM ou escalonamento.
Escalonamento automático:
- Se 0 pessoas estiverem usando seu app → 0 instâncias serão executadas (você não paga nada quando ocioso).
- Se 1.000 solicitações forem feitas, ele vai criar quantas cópias forem necessárias.
Sem estado por padrão:
- Cada solicitação pode ser enviada para uma instância diferente.
- Se você precisar armazenar estado, use um serviço externo como o Cloud SQL, o Firestore ou o Redis.
Compatível com qualquer linguagem ou framework:
- Desde que seja executado em um contêiner Linux, o Cloud Run não se importa se é Python, Go, Node.js, Java ou .Net.
Pague pelo que usar:
- O pagamento é por solicitação + tempo de computação (até 100 ms).
- Você não paga por recursos ociosos, como em uma VM tradicional.
3. Configuração e requisitos
Configuração de ambiente autoguiada
- Faça login no Console do Google Cloud e crie um novo projeto ou reutilize um existente. Crie uma conta do Gmail ou do Google Workspace, se ainda não tiver uma.
- O Nome do projeto é o nome de exibição para os participantes do projeto. É uma string de caracteres não usada pelas APIs do Google e pode ser atualizada quando você quiser.
- O ID do projeto precisa ser exclusivo em todos os projetos do Google Cloud e não pode ser mudado após a definição. O console do Cloud gera automaticamente uma string exclusiva. Em geral, não importa o que seja. Na maioria dos codelabs, é necessário fazer referência ao ID do projeto, normalmente identificado como
PROJECT_ID. Se você não gostar do ID gerado, crie outro aleatório. Se preferir, teste o seu e confira se ele está disponível. Ele não pode ser mudado após essa etapa e permanece durante o projeto. - Para sua informação, há um terceiro valor, um Número do projeto, que algumas APIs usam. Saiba mais sobre esses três valores na documentação.
- Em seguida, ative o faturamento no console do Cloud para usar os recursos/APIs do Cloud. A execução deste codelab não vai ser muito cara, se tiver algum custo. Para encerrar os recursos e evitar cobranças além deste tutorial, exclua os recursos criados ou exclua o projeto. Novos usuários do Google Cloud estão qualificados para o programa de US$ 300 de avaliação sem custos.
Inicie o Cloud Shell
Acesse o editor do Cloud Shell.
Se o terminal não aparecer na parte de baixo da tela, abra-o:
- Clique em Terminal.
- Clique em Novo terminal.
No terminal, defina seu projeto com este comando. Se você concluiu o laboratório 1, use o mesmo ID do projeto:
gcloud config set project [YOUR-PROJECT-ID]
Se você não se lembrar do ID do projeto, liste todos os IDs com:
gcloud projects list | awk '/PROJECT_ID/{print $2}'
4. Se for necessário autorizar, clique em Autorizar para continuar.
5. Você vai receber esta mensagem:
Updated property [core/project].
If you see a `WARNING` and are asked `Do you want to continue (Y/n)?`,
then you have likely entered the project ID incorrectly. Press `n`,
press `Enter`, and try to run the `gcloud config set project` command again.
4. Antes de começar
Ativar APIs e definir variáveis de ambiente
Ative todos os serviços necessários:
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com \
aiplatform.googleapis.com \
compute.googleapis.com
Resultado esperado
Operation "operations/acat.p2-[GUID]" finished successfully.
Configure a região padrão para usar os modelos de embedding da Vertex AI. Leia mais sobre os locais disponíveis para a Vertex AI. No exemplo, usamos a região europe-west1.
gcloud config set compute/region europe-west1
5. Fazer o download e instalar o ADK e criar a pasta do projeto
Crie os diretórios do projeto.
Esse comando cria uma pasta principal para o laboratório do código-fonte do agente.
cd && mkdir zoo_guide_agent && cd zoo_guide_agent
Crie um ambiente virtual.
python3 -m venv .venv
Ative o ambiente virtual.
source .venv/bin/activate
Crie o arquivo requirements.txt. Esse arquivo lista as bibliotecas Python necessárias para o agente. O comando a seguir cria e preenche o arquivo.
cloudshell edit requirements.txt
google-adk==1.12.0
langchain-community
wikipedia
Execute o comando no diretório principal do projeto, zoo_guide_agent.
pip install -r requirements.txt
Defina variáveis para o projeto, a região e o usuário atuais. Essa é uma maneira mais robusta de executar esses comandos.
export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_REGION=$(gcloud config get-value compute/region)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
Crie e abra um arquivo .env para autenticar o agente no diretório zoo_guide_agent.
cloudshell edit .env
O comando "cloudshell edit" abre o arquivo .env no editor acima do terminal. Insira o seguinte no arquivo .env e volte ao terminal.
MODEL="gemini-2.5-flash"
SERVICE_ACCOUNT="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
Adicione o URL do servidor MCP. Se você concluiu o laboratório 1, siga estas etapas para usar o servidor MCP criado nele:
- Conceda à identidade de serviço do Cloud Run permissão para chamar o servidor MCP remoto.
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT" \
--role="roles/run.invoker"
- Salve o URL do servidor MCP do laboratório 1 em uma variável de ambiente.
echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.europe-west1.run.app/mcp/" >> .env
Se você estiver usando um link público do servidor MCP, execute o seguinte e substitua PROJECT_NUMBER pelo que foi fornecido.
echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.europe-west1.run.app/mcp/" >> .env
6. Criar fluxo de trabalho do agente
Criar o arquivo init.py
Crie o arquivo init.py. Esse arquivo informa ao Python que o diretório "zoo_guide_agent" é um pacote.
cloudshell edit __init__.py
O comando acima abre o editor de código. Adicione o código a seguir a __init__.py:
from . import agent
Criar o arquivo principal agent.py
Crie o arquivo principal agent.py. Esse comando cria o arquivo Python e cola o código completo do seu sistema multiagente.
cloudshell edit agent.py
Etapa 1: importações e configuração inicial
O primeiro bloco traz todas as bibliotecas necessárias do ADK e do Google Cloud. Ele também configura o registro em log e carrega as variáveis de ambiente do arquivo .env, o que é crucial para acessar o modelo e o URL do servidor.
Adicione o seguinte código ao arquivo agent.py:
import os
import logging
import google.cloud.logging
from dotenv import load_dotenv
from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StreamableHTTPConnectionParams
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool
from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper
import google.auth
import google.auth.transport.requests
import google.oauth2.id_token
# --- Setup Logging and Environment ---
cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()
load_dotenv()
model_name = os.getenv("MODEL")
Etapa 2:definir as ferramentas (capacidades do agente)
Um agente só é tão bom quanto as ferramentas que pode usar. Nesta seção, definimos todos os recursos que nosso agente terá, incluindo uma função personalizada para salvar dados, uma ferramenta do MCP que se conecta ao nosso servidor seguro do MCP e uma ferramenta da Wikipédia.
Adicione o seguinte código à parte de baixo de agent.py:
# Greet user and save their prompt
def add_prompt_to_state(
tool_context: ToolContext, prompt: str
) -> dict[str, str]:
"""Saves the user's initial prompt to the state."""
tool_context.state["PROMPT"] = prompt
logging.info(f"[State updated] Added to PROMPT: {prompt}")
return {"status": "success"}
# Configuring the MCP Tool to connect to the Zoo MCP server
mcp_server_url = os.getenv("MCP_SERVER_URL")
if not mcp_server_url:
raise ValueError("The environment variable MCP_SERVER_URL is not set.")
def get_id_token():
"""Get an ID token to authenticate with the MCP server."""
target_url = os.getenv("MCP_SERVER_URL")
audience = target_url.split('/mcp/')[0]
request = google.auth.transport.requests.Request()
id_token = google.oauth2.id_token.fetch_id_token(request, audience)
return id_token
"""
# Use this code if you are using the public MCP Server and comment out the code below defining mcp_tools
mcp_tools = MCPToolset(
connection_params=StreamableHTTPConnectionParams(
url=mcp_server_url
)
)
"""
mcp_tools = MCPToolset(
connection_params=StreamableHTTPConnectionParams(
url=mcp_server_url,
headers={
"Authorization": f"Bearer {get_id_token()}",
},
),
)
# Configuring the Wikipedia Tool
wikipedia_tool = LangchainTool(
tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)
Explicação das três ferramentas
add_prompt_to_state📝
Essa ferramenta lembra o que um visitante do zoológico pergunta. Quando um visitante pergunta: "Onde estão os leões?", essa ferramenta salva a pergunta específica na memória do agente para que os outros agentes no fluxo de trabalho saibam o que pesquisar.
Como:é uma função Python que grava o comando do visitante no dicionário tool_context.state compartilhado. Esse contexto de ferramenta representa a memória de curto prazo do agente em uma única conversa. Os dados salvos no estado por um agente podem ser lidos pelo próximo agente no fluxo de trabalho.
MCPToolset🦁
Isso é usado para conectar o agente de guia turístico ao servidor MCP do zoológico criado no laboratório 1. Esse servidor tem ferramentas especiais para pesquisar informações específicas sobre nossos animais, como nome, idade e recinto.
Como:ele se conecta com segurança ao URL do servidor particular do zoológico. Ele usa get_id_token para receber automaticamente um "cartão-chave" seguro (um token de ID da conta de serviço) para provar sua identidade e ganhar acesso.
LangchainTool🌍
Isso dá ao agente de guia turístico um conhecimento geral do mundo. Quando um visitante faz uma pergunta que não está no banco de dados do zoológico, como "O que os leões comem na natureza?", essa ferramenta permite que o agente procure a resposta na Wikipédia.
Como:ele funciona como um adaptador, permitindo que nosso agente use a ferramenta WikipediaQueryRun pré-criada da biblioteca LangChain.
Recursos:
Etapa 3: definir os agentes especializados
Em seguida, vamos definir o agente de pesquisa e o agente de formatação de respostas. O agente de pesquisa é o "cérebro" da nossa operação. Esse agente usa o comando do usuário do State compartilhado, examina as ferramentas avançadas (a ferramenta de servidor MCP do zoológico e a ferramenta da Wikipédia) e decide quais usar para encontrar a resposta.
A função do agente formatador de respostas é a apresentação. Ele não usa ferramentas para encontrar novas informações. Em vez disso, ele usa os dados brutos coletados pelo agente Pesquisador (transmitidos pelo estado) e as habilidades de linguagem do LLM para transformar essas informações em uma resposta amigável e conversacional.
Adicione o seguinte código à parte de baixo de agent.py:
# 1. Researcher Agent
comprehensive_researcher = Agent(
name="comprehensive_researcher",
model=model_name,
description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
instruction="""
You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
You have access to two tools:
1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).
First, analyze the user's PROMPT.
- If the prompt can be answered by only one tool, use that tool.
- If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
you MUST use both tools to gather all necessary information.
- Synthesize the results from the tool(s) you use into preliminary data outputs.
PROMPT:
{{ PROMPT }}
""",
tools=[
mcp_tools,
wikipedia_tool
],
output_key="research_data" # A key to store the combined findings
)
# 2. Response Formatter Agent
response_formatter = Agent(
name="response_formatter",
model=model_name,
description="Synthesizes all information into a friendly, readable response.",
instruction="""
You are the friendly voice of the Zoo Tour Guide. Your task is to take the
RESEARCH_DATA and present it to the user in a complete and helpful answer.
- First, present the specific information from the zoo (like names, ages, and where to find them).
- Then, add the interesting general facts from the research.
- If some information is missing, just present the information you have.
- Be conversational and engaging.
RESEARCH_DATA:
{{ research_data }}
"""
)
Etapa 4: o agente de fluxo de trabalho
O agente de fluxo de trabalho atua como gerente de "back-office" do passeio pelo zoológico. Ele recebe a solicitação de pesquisa e garante que os dois agentes definidos acima realizem os trabalhos na ordem correta: primeiro a pesquisa e depois a formatação. Isso cria um processo previsível e confiável para responder à pergunta de um visitante.
Como: é um SequentialAgent, um tipo especial de agente que não pensa por conta própria. A única função dele é executar uma lista de sub_agents (o pesquisador e o formatador) em uma sequência fixa, transmitindo automaticamente a memória compartilhada de um para o outro.
Adicione este bloco de código à parte de baixo de agent.py:
tour_guide_workflow = SequentialAgent(
name="tour_guide_workflow",
description="The main workflow for handling a user's request about an animal.",
sub_agents=[
comprehensive_researcher, # Step 1: Gather all data
response_formatter, # Step 2: Format the final response
]
)
Etapa final: montar o fluxo de trabalho principal 
Esse agente é designado como o root_agent, que a estrutura do ADK usa como ponto de partida para todas as novas conversas. A principal função dele é orquestrar todo o processo. Ele funciona como o controlador inicial, gerenciando o primeiro turno da conversa.
Adicione este bloco final de código à parte de baixo de agent.py:
root_agent = Agent(
name="greeter",
model=model_name,
description="The main entry point for the Zoo Tour Guide.",
instruction="""
- Let the user know you will help them learn about the animals we have in the zoo.
- When the user responds, use the 'add_prompt_to_state' tool to save their response.
After using the tool, transfer control to the 'tour_guide_workflow' agent.
""",
tools=[add_prompt_to_state],
sub_agents=[tour_guide_workflow]
)
Seu arquivo agent.py está pronto. Ao criar dessa forma, você pode ver como cada componente (ferramentas, agentes de worker e agentes de gerenciamento) tem uma função específica na criação do sistema inteligente final. A seguir, a implantação!
7. Preparar o aplicativo para implantação
Com o ambiente local pronto, a próxima etapa é preparar o projeto do Google Cloud para a implantação. Isso envolve uma verificação final da estrutura de arquivos do seu agente para garantir que ela seja compatível com o comando de implantação. Mais importante ainda, você configura uma permissão crítica do IAM que permite que o serviço implantado do Cloud Run aja em seu nome e chame os modelos da Vertex AI. Concluir esta etapa garante que o ambiente de nuvem esteja pronto para executar seu agente.
Carregue as variáveis na sessão do shell executando o comando source.
source .env
Conceda à conta de serviço a função de usuário da Vertex AI, que dá permissão para fazer previsões e chamar os modelos do Google.
# Grant the "Vertex AI User" role to your service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$SERVICE_ACCOUNT" \
--role="roles/aiplatform.user"
8. Implantar o agente usando a CLI do ADK
Com o código local pronto e o projeto do Google Cloud preparado, é hora de implantar o agente. Você vai usar o comando adk deploy cloud_run, uma ferramenta conveniente que automatiza todo o fluxo de trabalho de implantação. Esse único comando empacota seu código, cria uma imagem de contêiner, envia para o Artifact Registry e inicia o serviço no Cloud Run, tornando-o acessível na Web.
Criar um arquivo .gcloudignore
Para reduzir nosso tempo de implantação, vamos criar um arquivo .gcloudignore. Execute os comandos a seguir para implantar o agente.
cloudshell edit .gcloudignore
O comando "cloudshell edit" abre o arquivo .gcloudignore no editor acima do terminal. Escreva o seguinte no arquivo e salve-o. Em seguida, volte ao terminal para executar os comandos de implantação na próxima seção.
.venv/
Implantar
Execute os comandos a seguir para implantar o agente.
# Run the deployment command
adk deploy cloud_run \
--project=$PROJECT_ID \
--region=europe-west1 \
--service_name=zoo-tour-guide \
--with_ui \
.
gcloud run services update zoo-tour-guide \
--region=europe-west1 \
--update-labels=dev-tutorial=codelab-adk
Aceitar comandos
Talvez você receba a seguinte mensagem:
Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [europe-west1] will be created. Do you want to continue (Y/n)?
Digite Y e pressione ENTER.
Talvez você receba a seguinte mensagem:
Allow unauthenticated invocations to [your-service-name] (y/N)?.
Para este laboratório, queremos permitir invocações não autenticadas para facilitar o teste. Digite y e pressione Enter.
Receber o link de implantação
Após a execução, o comando vai fornecer o URL do serviço implantado do Cloud Run. Ele terá esta aparência: https://zoo-tour-guide-123456789.europe-west1.run.app. Copie esse URL para a próxima tarefa.
9. Testar o agente implantado
Com o agente ativo no Cloud Run, faça um teste para confirmar se a implantação foi bem-sucedida e se o agente está funcionando conforme o esperado. Você vai usar o URL público do serviço (algo como https://zoo-tour-guide-123456789.europe-west1.run.app/) para acessar a interface da Web do ADK e interagir com o agente.
Abra o URL público do serviço do Cloud Run no navegador da Web. Como você usou o --with_ui flag, a interface para desenvolvedores do ADK vai aparecer.
Ative Token Streaming no canto superior direito.
Agora você pode interagir com o agente do zoológico.
Digite hello e pressione "Enter" para iniciar uma nova conversa.
Observe o resultado. O agente precisa responder rapidamente com uma saudação:
"Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"
Explicação do fluxo do agente
Seu sistema funciona como uma equipe inteligente de vários agentes. O processo é gerenciado por uma sequência clara para garantir um fluxo tranquilo e eficiente, desde a pergunta do usuário até a resposta final e detalhada.
1. O recepcionista do zoológico (a recepção)
Todo o processo começa com o agente de recepção.
Função:iniciar a conversa. A instrução é cumprimentar o usuário e perguntar sobre qual animal ele quer saber mais.
Ferramenta:quando o usuário responde, o Greeter usa a ferramenta add_prompt_to_state para capturar as palavras exatas (por exemplo, "me fale sobre os leões") e salvá-las na memória do sistema.
A transferência:depois de salvar o comando, ele passa imediatamente o controle para o subagente, o tour_guide_workflow.
2. O pesquisador abrangente (o superpesquisador)
Essa é a primeira etapa do fluxo de trabalho principal e o "cérebro" da operação. Em vez de uma equipe grande, você tem um único agente altamente qualificado que pode acessar todas as informações disponíveis.
Função:analisar a pergunta do usuário e criar um plano inteligente. Ele usa a capacidade de uso de ferramentas do modelo de linguagem para decidir se precisa:
- Dados internos dos registros do zoológico (pelo servidor MCP).
- Conhecimento geral da Web (pela API Wikipedia).
- Ou, para perguntas complexas, as duas.
Ação:executa as ferramentas necessárias para coletar todos os dados brutos necessários. Por exemplo, se você perguntar "Quantos anos têm nossos leões e o que eles comem na natureza?", o Gemini vai chamar o servidor MCP para saber as idades e a ferramenta da Wikipédia para saber a dieta.
3. O formatador de respostas (o apresentador)
Depois que o Comprehensive Researcher reúne todos os fatos, esse é o agente final a ser executado.
Função:ser a voz amigável do guia do zoológico. Ele usa os dados brutos (que podem ser de uma ou ambas as fontes) e os refina.
Ação:sintetiza todas as informações em uma resposta única, coesa e envolvente. Seguindo as instruções, ele primeiro apresenta as informações específicas do zoológico e depois adiciona os fatos gerais interessantes.
O resultado final:o texto gerado por esse agente é a resposta completa e detalhada que o usuário vê na janela de chat.
Se você quiser saber mais sobre como criar agentes, confira os seguintes recursos:
10. Limpar o ambiente
gcloud run services delete zoo-tour-guide --region=europe-west1 --quiet
gcloud artifacts repositories delete cloud-run-source-deploy --location=europe-west1 --quiet
11. Parabéns
Parabéns por concluir o codelab.
O que vimos
- Como estruturar um projeto Python para implantação com a interface de linha de comando do ADK.
- Como implementar um fluxo de trabalho multiagente usando SequentialAgent e ParallelAgent.
- Como se conectar a um servidor MCP remoto usando o MCPToolset para consumir as ferramentas dele.
- Como aumentar os dados internos integrando ferramentas externas, como a API da Wikipédia.
- Como implantar um agente como um contêiner sem servidor no Cloud Run usando o comando adk deploy.
12. Pesquisa
Saída: