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 a integração perfeita entre serviços externos, fontes de dados, ferramentas e aplicativos. Você vai aprender a integrar o MCP aos seus agentes do Kit de Desenvolvimento de Agente (ADK, na sigla em inglês) usando ferramentas fornecidas por servidores atuais do MCP para aprimorar seus fluxos de trabalho do ADK. Além disso, você vai aprender a expor ferramentas do ADK, como load_web_page, usando um servidor personalizado do MCP. O resultado é uma integração maior com clientes desse protocolo.

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:

• Usar servidores atuais do MCP no ADK: um agente do ADK atua como um cliente do MCP, aproveitando as ferramentas fornecidas por servidores externos do MCP.
• Expor ferramentas do ADK usando um servidor do MCP: criar um servidor do MCP que encapsule ferramentas do ADK, tornando-as acessíveis a qualquer cliente do protocolo.

Objetivos

Neste laboratório, você vai aprender a:

• Usar um agente do ADK como cliente do MCP para interagir com ferramentas de servidores atuais do MCP.
• Configurar e implantar seu próprio servidor do MCP para expor ferramentas do ADK a outros clientes.
• Conectar agentes do ADK a ferramentas externas usando a comunicação padronizada do MCP.
• Permitir a interação perfeita entre LLMs e ferramentas usando o Protocolo de Contexto de Modelo.

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.

Tarefa 1: instalar o ADK e configurar o ambiente

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

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. 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 na janela do editor de código.

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

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

1. Instale o ADK executando o comando a seguir no terminal do Cloud Shell.

   Observação: especifique a versão para garantir que a versão do ADK que você instalar seja igual à que foi usada neste laboratório. Você pode conferir o número e as notas da versão mais recente no repositório adk-python. sudo python3 -m pip install google-adk==1.5.0

2. Cole os comandos a seguir no terminal do Cloud Shell para copiar o 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 gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_mcp_tools.zip . unzip adk_mcp_tools.zip

3. Instale outros requisitos do laboratório com:

   python3 -m pip install -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 um servidor do MCP do Google Maps com agentes do ADK (o ADK como cliente do MCP) no adk web

Nesta seção, você vai integrar as ferramentas de um servidor externo do MCP usado pelo 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): você pode usar o parâmetro tool_filter ao criar uma MCPToolset para selecionar um subconjunto específico de ferramentas do servidor do MCP, em vez de expor todas elas ao seu agente.

Gere a chave de API e ative as APIs

Nesta subseção, você vai gerar uma nova chave de API chamada GOOGLE_MAPS_API_KEY.

1. Abra a guia do navegador que mostra o console do Google Cloud (não o editor do Cloud Shell).

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

3. Pesquise Credenciais na barra de pesquisa na parte de cima da página. Selecione o resultado.

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

   A caixa de diálogo Chave de API criada vai mostrar a chave que você acabou de criar. Salve essa chave localmente para usar mais tarde no laboratório.

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

   Por padrão, a chave recém-criada será chamada de API Key 1. Selecione a chave, renomeie-a como GOOGLE_MAPS_API_KEY e clique em Salvar.

   

Defina seu agente com uma MCPToolset para o Google Maps

Nesta subseção, você vai configurar o agente para usar a MCPToolset no Google Maps, permitindo que ele forneça rotas e informações baseadas em localização.

1. No painel do explorador de arquivos do editor do Cloud Shell, encontre a pasta adk_mcp_tools. Clique nela para abrir.

2. Navegue até o diretório adk_mcp_tools/google_maps_mcp_agent.

3. Cole o comando a seguir em um arquivo de texto simples e atualize o valor YOUR_ACTUAL_API_KEY com a chave de API do Google Maps que você gerou e salvou na etapa anterior:

   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={{{ project_0.default_region | Region}}} GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_API_KEY" MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF

4. Copie e cole o comando atualizado no terminal do Cloud Shell para executá-lo e gravar um arquivo .env que vai fornecer detalhes de autenticação para esse diretório de agente.

5. Copie o arquivo .env para o outro diretório de agente que você vai usar neste laboratório executando o seguinte comando:

   cp google_maps_mcp_agent/.env adk_mcp_server/.env

6. Em seguida, adicione o código abaixo ao lugar indicado no arquivo agent.py para incluir a ferramenta do Google Maps no seu agente. Assim, seu agente vai usar a MCPToolset com o Google Maps para fornecer rotas ou informações baseadas em localização.

   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. No diretório do projeto adk_mcp_tools, inicie a interface do desenvolvedor do Kit de Desenvolvimento de Agente com o seguinte comando:

   adk web

   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)

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

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

10. Inicie uma conversa com o agente e execute estes 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:

    

11. Clique no ícone do agente ao lado do balão de chat do agente com um raio, que indica uma chamada de função. Isso vai abrir o inspetor de eventos para esse evento:

    

12. Observe que o gráfico do agente indica várias ferramentas diferentes, identificadas pelo emoji de chave inglesa (🔧). Mesmo que você tenha importado apenas uma MCPToolset, esse conjunto de ferramentas veio com as diferentes ferramentas listadas aqui, como maps_place_details e maps_directions.

    

13. Na guia Solicitação, você pode conferir a estrutura da solicitação. Use as setas na parte de cima do inspetor de eventos para navegar pelas ideias, chamadas de função e respostas do agente.

14. Quando terminar de fazer perguntas ao agente, feche a guia da interface.

15. Volte para o painel do terminal do Cloud Shell e pressione CTRL + C para interromper 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 expõe o ADK)

Nesta seção, você vai aprender a expor a ferramenta load_web_page do ADK usando um servidor personalizado do MCP. Com esse padrão, você pode encapsular ferramentas existentes do ADK e torná-las 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. Volte para a guia do editor do Cloud Shell e selecione o diretório adk_mcp_tools/adk_mcp_server.

2. Um arquivo Python chamado adk_server.py foi preparado e comentado para você. Analise o arquivo e leia os comentários para entender como o código encapsula uma ferramenta e a disponibiliza como um servidor do MCP. Observe que ele permite que os clientes do MCP listem as ferramentas disponíveis e invoquem a ferramenta do ADK de forma assíncrona, gerenciando solicitações e respostas em um formato compatível com o MCP.

Teste o servidor personalizado do MCP com um agente do ADK

3. Clique no arquivo agent.py no diretório adk_mcp_server.

4. Atualize o caminho para o arquivo adk_server.py.

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

5. Em seguida, adicione o seguinte código ao lugar indicado no arquivo agent.py para incluir a MCPToolset no seu agente. Um agente do ADK atua como um cliente do servidor MCP. Esse agente do ADK vai usar a MCPToolset para se conectar ao script adk_server.py.

   tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command="python3", # Command to run your MCP server script args=[PATH_TO_YOUR_MCP_SERVER_SCRIPT], # Argument is the path to the script ), timeout=15, ), tool_filter=['load_web_page'] # Optional: ensure only specific tools are loaded ) ],

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

   python3 ~/adk_mcp_tools/adk_mcp_server/adk_server.py

   Saída:

   

7. Abra uma nova guia do terminal do Cloud Shell clicando no botão na parte de cima da janela do terminal do Cloud Shell.

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

   cd ~/adk_mcp_tools adk web

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

10. No menu suspenso Selecione um agente à esquerda, escolha adk_mcp_server.

11. Consulte o agente com:

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

    Saída:

    

    O que acontece aqui:

    • O agente do ADK (web_reader_mcp_client_agent) usa a MCPToolset para se conectar ao seu adk_server.py.
    • O servidor do MCP vai receber a solicitação call_tool, executar a ferramenta load_web_page do ADK e retornar o resultado.
    • O agente do ADK vai retransmitir essas informações. Você verá os registros da interface da web do ADK (e do terminal dela) e do terminal adk_server.py na guia do terminal do Cloud Shell em que ele está sendo executado.

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

Parabéns!

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

Manual atualizado em 6 de outubro de 2025

Laboratório testado em 6 de outubro 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.