GENAI124

Visão geral

Neste laboratório, você vai conhecer o Protocolo de Contexto de Modelo (MCP, na sigla em inglês), um padrão aberto que permite integração total entre serviços externos, fontes de dados, ferramentas e aplicativos. Você aprenderá a integrar o MCP aos seus agentes do Kit de Desenvolvimento de Agente (ADK, na sigla em inglês), aproveitando ferramentas de servidores do MCP existentes para aprimorar os fluxos de trabalho do ADK. Além disso, você vai descobrir como disponibilizar ferramentas do ADK, como load_web_page, por meio de um servidor do MCP personalizado, viabilizando uma integração mais abrangente com clientes do MCP.

O que é o Protocolo de Contexto de Modelo (MCP)?

O Protocolo de Contexto de Modelo (MCP, na sigla em inglês) é um padrão aberto criado para uniformizar a comunicação dos modelos de linguagem grandes (LLMs, na sigla em inglês), como o Gemini e o Claude, com aplicativos, fontes de dados e ferramentas externas. Pense nele como um mecanismo de conexão universal que simplifica a maneira como os LLMs recebem contexto, executam ações e interagem com vários sistemas.

O MCP segue uma arquitetura cliente-servidor, definindo como os dados (recursos), modelos interativos (comandos) e funções úteis (ferramentas) são expostos por um servidor do MCP e consumidos por um cliente desse protocolo (que pode ser um aplicativo host de um LLM ou um agente de IA).

Este laboratório aborda dois padrões de integração principais:

• Uso de servidores MCP existentes no ADK: um agente do ADK atua como um cliente do MCP, aproveitando as ferramentas fornecidas por servidores do MCP externos.
• Disponibilização de ferramentas do ADK por meio de um servidor do MCP: criação de um servidor do MCP que encapsula ferramentas do ADK, tornando-as acessíveis a qualquer cliente do MCP.

Objetivos

Neste laboratório, você aprenderá a fazer o seguinte:

• Usar um agente do ADK como cliente do MCP para interagir com ferramentas de servidores do MCP existentes.
• Configurar e implantar seu próprio servidor do MCP para expor ferramentas do ADK a outros clientes.
• Conectar agentes do ADK a ferramentas externas por meio da comunicação padronizada do MCP.
• Permitir a interação total entre os LLMs e as ferramentas usando o MCP.

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.

Tarefa 1: instalar o ADK e configurar o ambiente

Neste ambiente de laboratório, a API Vertex AI, a API Routes e a API Directions já foram ativadas para você.

Prepare uma guia do Editor do Cloud Shell

1. No console do Google Cloud, 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 Abrir o Editor () na parte superior 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.
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ê trabalha nesta janela como seu ambiente de desenvolvimento integrado (IDE, na sigla em inglês) 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

Nesta seção, você vai executar os comandos apresentados a seguir no terminal do Cloud Shell.

1. Execute o comando a seguir no terminal do Cloud Shell para copiar o diretório do projeto do Cloud Storage:

   gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/* .

2. Execute os comandos a seguir para instalar o Kit de Desenvolvimento de Agente (ADK) e as demais dependências necessárias para executar os aplicativos de exemplo:

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

Clique em Verificar meu progresso para conferir o objetivo. Instalar o ADK e configurar o ambiente

Tarefa 2: usar o servidor do MCP para Google Maps com agentes do ADK (o ADK como cliente do MCP) na interface de desenvolvimento do ADK

Esta seção demonstra como integrar ferramentas de um servidor do MCP externo para Google Maps aos seus agentes do ADK. Esse é o padrão de integração mais comum quando o agente do ADK precisa usar recursos fornecidos por um serviço que expõe uma interface do MCP. Você vai saber como a classe MCPToolset pode ser diretamente adicionada à lista de ferramentas do seu agente para garantir uma conexão perfeita com o servidor do MCP, a descoberta das ferramentas dele e a disponibilização delas para o agente usar. O foco desses exemplos está principalmente nas interações dentro do ambiente de desenvolvimento adk web.

MCPToolset

A classe MCPToolset é o principal mecanismo do ADK para integrar ferramentas de um servidor do MCP. Quando você inclui uma instância de MCPToolset na lista de ferramentas do seu agente, ela lida automaticamente com a interação com o servidor do MCP especificado. Confira como funciona:

• Gerenciamento de conexões: na inicialização, a MCPToolset estabelece e gerencia a conexão com o servidor do MCP. Pode ser um processo de servidor local (usando StdioServerParameters para comunicação por entrada/saída padrão) ou um servidor remoto (usando SseServerParams para eventos enviados pelo servidor). O conjunto de ferramentas também lida com o encerramento correto dessa conexão quando o agente ou aplicativo é encerrado.
• Descoberta e adaptação de ferramentas: depois de conectada, a MCPToolset consulta o servidor do MCP para saber quais ferramentas estão disponíveis (usando o método list_tools do MCP). Em seguida, ele converte os esquemas dessas ferramentas do MCP descobertas em instâncias BaseTool compatíveis com o ADK.
• Exposição ao agente: essas ferramentas adaptadas são disponibilizadas ao seu LlmAgent como se fossem nativas do ADK.
• Proxy de chamadas de ferramentas: quando o LlmAgent decide usar uma dessas ferramentas, a MCPToolset faz o proxy da chamada de forma transparente (usando o método call_tool do MCP) para o servidor do MCP, envia os argumentos necessários e retorna a resposta do servidor para o agente.
• Filtragem (opcional): use o parâmetro tool_filter ao criar uma classe MCPToolset para selecionar um subconjunto específico de ferramentas do servidor do MCP, em vez de disponibilizar todas elas ao agente.

Gere uma chave de API e ative as APIs

O servidor do MCP para Google Maps requer uma chave de API para se comunicar com os serviços do Google Maps. Nesta etapa, você vai gerar uma nova chave de API chamada GOOGLE_MAPS_API_KEY e, por questões de segurança, limitar o uso dela apenas às APIs Directions e Routes.

1. Acesse a guia do navegador console do Google Cloud em vez do Editor do Cloud Shell.

2. Você pode fechar o painel do terminal do Cloud Shell nesta guia do navegador para ganhar mais espaço no console.

3. Procure por Credenciais na barra de pesquisa na parte superior da página. Selecione essa opção nos resultados.

4. Na página Credenciais, clique em Criar credenciais na parte superior da página e selecione Chave de API.

5. Em Nome, digite GOOGLE_MAPS_API_KEY.

6. Em APIs que podem ser acessadas usando esta chave, selecione as seguintes APIs:

   • API Directions
   • API Routes

7. Clique em Criar.

   A caixa de diálogo Chave de API criada mostra a chave de API que você acabou de gerar. Não se esqueça de copiar e salvar essa chave localmente para usá-la mais tarde no laboratório.

8. Clique em Fechar na caixa de diálogo.

   

Configure o agente com uma classe MCPToolset para o Google Maps

Agora você vai configurar o agente para usar as ferramentas do Google Maps. Ao adicionar a classe MCPToolset, você capacita o agente a descobrir e chamar dinamicamente as APIs Maps sempre que necessário.

1. Cole o comando a seguir em um documento de texto simples no seu computador e atualize o valor YOUR_ACTUAL_API_KEY pela chave de API Google Maps gerada e salva anteriormente:

   cd ~/adk_mcp_tools cat << EOF > google_maps_mcp_agent/.env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id | Project }}} GOOGLE_CLOUD_LOCATION=global GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_API_KEY" MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF

2. Copie e cole o comando atualizado no terminal do Cloud Shell e execute-o para gerar um arquivo .env, que fornece os detalhes de autenticação para este diretório de agente.

3. Copie o arquivo .env para o outro diretório de agente para usá-lo mais tarde neste laboratório executando o seguinte comando:

   cp google_maps_mcp_agent/.env adk_mcp_server/.env

4. No painel do explorador de arquivos do Editor do Cloud Shell, localize a pasta adk_mcp_tools. Clique nela para abrir.

5. Acesse o diretório adk_mcp_tools/google_maps_mcp_agent.

6. Abra o arquivo agent.py e adicione o código apresentado a seguir logo após o comentário ## Adicionar a MCPToolset (em uma nova linha após a linha 53) para configurar a conexão do agente com o servidor do MCP do Google Maps:

   tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command='npx', args=[ "-y", "@modelcontextprotocol/server-google-maps", ], env={ "GOOGLE_MAPS_API_KEY": google_maps_api_key } ), timeout=15, ), ) ],

7. Salve o arquivo.

8. No diretório do projeto adk_mcp_tools, inicie a interface de desenvolvimento do Kit de Desenvolvimento de Agente com o seguinte comando:

   adk web --allow_origins "regex:https://.*.cloudshell.dev" --otel_to_cloud --reload_agents

   Saída:

   INFO: Started server process [2434] INFO: Waiting for application startup. +----------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://localhost:8000.| +----------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

9. Para acessar a interface da web em uma nova guia, clique no link http://127.0.0.1:8000 exibido na saída do terminal.

10. Uma nova guia do navegador será aberta com a interface de desenvolvimento do ADK. No menu suspenso Selecionar um agente à esquerda, selecione o google_maps_mcp_agent.

11. Inicie uma conversa com o agente e envie os seguintes comandos:

    Get directions from GooglePlex to SFO. Observação: se a chamada de API expirar na primeira vez que você a usar, clique em + Nova sessão no canto superior direito da interface do desenvolvedor do ADK e tente de novo. What's the route from Paris, France to Berlin, Germany?

    Saída:

    

12. Clique no ícone do agente ao lado do balão do chat que contém um raio, o qual indica uma chamada de função. Essa ação abre o Inspetor de Eventos para o evento em questão.

    

    Observe que o gráfico do agente mostra várias ferramentas diferentes, identificadas pelo emoji de chave inglesa (🔧). Embora você tenha importado apenas uma classe MCPToolset, esse conjunto de ferramentas já inclui as diversas opções que você vê listadas aqui, como maps_place_details e maps_directions.

    

    Na guia Evento, você pode conferir a estrutura da solicitação. Use as setas no topo do Inspetor de Eventos para explorar o raciocínio, as chamadas de função e as respostas do agente.

13. Quando terminar de fazer perguntas ao agente, feche a guia do navegador da interface de desenvolvimento.

14. Retorne ao painel do terminal do Cloud Shell e pressione CTRL+C para encerrar o servidor.

Clique em Verificar meu progresso para conferir o objetivo. Criar a chave de API e implantar o agente do ADK

Tarefa 3: criar um servidor do MCP com ferramentas do ADK (servidor do MCP que disponibiliza o ADK)

Nesta seção, você vai descobrir como disponibilizar a ferramenta load_web_page do ADK por meio de um servidor do MCP personalizado. Esse padrão permite que você encapsule ferramentas do ADK existentes, tornando-as acessíveis a qualquer aplicativo cliente padrão do MCP.

Crie o script do servidor do MCP e implemente a lógica do servidor

1. Retorne ao Editor do Cloud Shell e selecione o diretório adk_mcp_tools/adk_mcp_server.

2. Abra o arquivo Python chamado adk_server.py. Este arquivo contém a lógica do servidor do MCP personalizado. Analise o código para compreender como ele encapsula a ferramenta do ADK e a disponibiliza.

   Reserve um tempo para analisar esse arquivo, lendo os comentários para entender como o código encapsula uma ferramenta e a disponibiliza como um servidor do MCP. Observe como ele permite que os clientes do MCP listem as ferramentas disponíveis, além de invocarem a ferramenta do ADK de forma assíncrona, tratando solicitações e respostas em um formato em conformidade com o MCP.

Teste o servidor do MCP personalizado com um agente do ADK

1. Abra o arquivo agent.py no diretório adk_mcp_server.

2. Na linha 31, atualize o valor de PATH_TO_YOUR_MCP_SERVER_SCRIPT pelo caminho abaixo para que o agente consiga se conectar ao script de servidor personalizado:

   /home/{{{project_0.startup_script.updated_lab_username | Username}}}/adk_mcp_tools/adk_mcp_server/adk_server.py

3. Em seguida, adicione o código apresentado a seguir na linha 55 do arquivo agent.py, ou seja, logo após o trecho ## Adicionar a MCPToolset abaixo:, para integrar a classe MCPToolset ao agente. Um agente do ADK atua como um cliente para o servidor do MCP. Este agente do ADK usa a classe MCPToolset para se conectar ao script adk_server.py.

   tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command="python3", # Comando para executar o script do servidor do MCP args=[PATH_TO_YOUR_MCP_SERVER_SCRIPT], # O argumento é o caminho para o script ), timeout=15, ), tool_filter=['load_web_page'] # Opcional: garante que apenas ferramentas específicas sejam carregadas ) ],

4. Salve o arquivo.

5. Para executar o servidor do MCP, inicie o script adk_server.py executando o seguinte comando no terminal do Cloud Shell:

   python3 ~/adk_mcp_tools/adk_mcp_server/adk_server.py

   Saída:

   

6. Abra uma nova guia do terminal do Cloud Shell clicando no botão na parte superior da janela do terminal do Cloud Shell.

7. No terminal do Cloud Shell, do diretório do projeto adk_mcp_tools, inicie a interface de desenvolvimento do Kit de Desenvolvimento de Agente com o seguinte comando:

   export PATH=$PATH:"/home/${USER}/.local/bin" cd ~/adk_mcp_tools adk web --allow_origins "regex:https://.*.cloudshell.dev" --otel_to_cloud --reload_agents Observação: o “PATH” foi adicionado a este comando para redefini-lo, já que o novo terminal do Cloud Shell pode apresentar um erro se você executar o restante do comando sem ele. Geralmente, isso se manifestaria como um erro de comando “adk web” não encontrado.

8. Para acessar a interface da web em uma nova guia, clique no link http://127.0.0.1:8000 exibido na saída do terminal.

9. No menu suspenso Selecionar um agente à esquerda, selecione o adk_mcp_server.

10. Envie o seguinte comando para o agente:

    Load the content from http://example.com.

    Saída:

    

    O que acontece aqui:

    • O agente do ADK (web_reader_mcp_client_agent) usa o MCPToolset para estabelecer a conexão com o arquivo adk_server.py.
    • O servidor do MCP recebe a solicitação call_tool, executa a ferramenta load_web_page do ADK e retorna o resultado.
    • Em seguida, o agente do ADK transmite essas informações. Você deverá ver os logs tanto da interface web do ADK (e do terminal dela) quanto do terminal do adk_server.py na guia do terminal do Cloud Shell em que cada um está em execução.

    Isso prova que as ferramentas do ADK podem ser encapsuladas em um servidor do MCP, o que as torna acessíveis a uma ampla variedade de clientes compatíveis com o MCP, inclusive agentes do ADK.

Parabéns!

Neste laboratório, você aprendeu a integrar ferramentas externas do Protocolo de Contexto de Modelo (MCP) aos agentes do Kit de Desenvolvimento de Agente (ADK) usando a classe MCPToolset. Você descobriu como se conectar a um servidor do MCP, usar as ferramentas dele no agente e disponibilizar ferramentas do ADK, como load_web_page, por meio de um servidor do MCP personalizado. Com essas habilidades, você pode ampliar os agentes do ADK com serviços externos avançados, aprimorando seus fluxos de trabalho de desenvolvimento web.

Manual atualizado em 21 de abril de 2026

Laboratório testado em 21 de abril 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.