GENAI124

Visão geral

Neste laboratório, você vai conhecer o Protocolo de Contexto de Modelo (MCP), 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 ADK usando ferramentas fornecidas por servidores MCP atuais para melhorar seus fluxos de trabalho ADK. Além disso, você vai aprender a expor ferramentas do ADK, como load_web_page, por meio de um servidor MCP personalizado, permitindo uma integração mais ampla com clientes MCP.

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

O Protocolo de Contexto de Modelo (MCP) é um padrão aberto criado para padronizar a forma como os modelos de linguagem grandes (LLMs), como o Gemini e o Claude, se comunicam com aplicativos, fontes de dados e ferramentas externas. Pense nisso como um mecanismo de conexão universal que simplifica a maneira como os LLMs obtêm 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 MCP e consumidos por um cliente MCP (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 MCP atuais no ADK: um agente do ADK atua como um cliente MCP, aproveitando as ferramentas fornecidas por servidores MCP externos.
• Expor ferramentas do ADK usando um servidor MCP: criar um servidor MCP que encapsula ferramentas do ADK, tornando-as acessíveis a qualquer cliente MCP.

Objetivos

Neste laboratório, você vai aprender a:

• Usar um agente ADK como cliente MCP para interagir com ferramentas de servidores MCP existentes.
• Configurar e implantar seu próprio servidor MCP para expor ferramentas ADK a outros clientes.
• Conectar agentes do ADK a ferramentas externas usando a comunicação MCP padronizada.
• 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

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

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

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

3. Clique em Continuar.

4. Se for preciso autorizar o Cloud Shell, clique em Autorizar.

5. No canto superior direito do painel do terminal do Cloud Shell, clique no botão Abrir em uma nova janela .

6. No terminal do Cloud Shell, insira o seguinte código para abrir o Editor no seu diretório principal:

   cloudshell workspace ~

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

8. Durante o restante deste laboratório, você pode trabalhar nesta janela como seu ambiente de desenvolvimento integrado 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

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

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

10. 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 gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/adk_mcp_tools.zip . unzip adk_mcp_tools.zip

11. 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 o servidor MCP do Google Maps com agentes ADK (ADK como cliente MCP) no adk web

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

MCPToolset

A classe MCPToolset é o principal mecanismo do ADK para integrar ferramentas de um servidor 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 MCP especificado. Confira como funciona:

• Gerenciamento de conexões: na inicialização, a MCPToolset estabelece e gerencia a conexão com o servidor 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 MCP para saber quais ferramentas estão disponíveis (usando o método MCP list_tools). Em seguida, ele converte os esquemas dessas ferramentas 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 ferramentas 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 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 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 exibirá a chave recém-criada. 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 para o Google Maps, permitindo que ele forneça rotas e informações baseadas em localização.

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

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

8. Cole o comando a seguir em um arquivo de texto simples e atualize o valor de YOUR_ACTUAL_API_KEY com a chave de API do Google Maps que você gerou e salvou em uma 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" EOF

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

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

11. Em seguida, adicione o seguinte código onde indicado no arquivo agent.py para adicionar a ferramenta do Google Maps ao seu agente. Isso vai permitir que seu agente use a MCPToolset para 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, ), ) ],

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

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

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

15. Inicie uma conversa com o agente e execute 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 novamente. What's the route from Paris, France to Berlin, Germany?

    Saída:

    

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

    

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

    

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

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

20. 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 MCP com ferramentas do ADK (servidor MCP que expõe o ADK)

Nesta seção, você vai aprender a expor a ferramenta load_web_page do ADK usando um servidor MCP criado sob medida. Com esse padrão, você pode encapsular ferramentas existentes do ADK e torná-las acessíveis a qualquer aplicativo cliente MCP padrão.

Crie o script do servidor 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 MCP. Observe que ele permite que os clientes do MCP listem as ferramentas disponíveis e invoquem a ferramenta ADK de forma assíncrona, lidando com solicitações e respostas em um formato compatível com o MCP.

Teste o servidor MCP personalizado 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 onde indicado no arquivo agent.py para adicionar a MCPToolset ao 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 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:

   

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, selecione adk_mcp_server.

11. Consulte o agente com:

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

    Saída:

    

    O que acontece aqui:

    1. O agente do ADK (web_reader_mcp_client_agent) usa a MCPToolset para se conectar ao seu adk_server.py.
    2. O servidor MCP vai receber a solicitação call_tool, executar a ferramenta load_web_page do ADK e retornar o resultado.
    3. O agente do ADK vai retransmitir essas informações. Você vai 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 MCP, tornando-as acessíveis a uma ampla variedade de clientes compatíveis com 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ê descobriu como se conectar a um servidor MCP, usar as ferramentas dele no seu agente e expor ferramentas do ADK, como load_web_page, por meio de um servidor MCP personalizado.

Com essas habilidades, você pode ampliar seus agentes do ADK com serviços externos avançados, melhorando seus fluxos de trabalho de desenvolvimento da Web.

Manual atualizado em 3 de setembro de 2025

Laboratório testado em 3 de setembro 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.