Criar um agente de IA do Google Workspace com o ADK e o MCP

1. Introdução

Neste codelab, você vai aprender a criar um agente de IA de código profissional usando o Kit de Desenvolvimento de Agente (ADK) que se conecta diretamente aos servidores oficiais do MCP do Google Workspace.

O Protocolo de Contexto de Modelo (MCP) é um padrão aberto que permite que modelos de IA usem com segurança ferramentas fornecidas por servidores remotos. O ADK é o framework de código profissional do Google para criar agentes autônomos. Ao combiná-los, você pode criar agentes altamente personalizados com base nos dados do Gmail, Google Drive, Google Agenda, Google Chat e Pessoas.

Para conferir a documentação completa sobre as ferramentas e configurações disponíveis, consulte Configurar servidores MCP do Google Workspace.

Atividades deste laboratório

  • Ative os serviços MCP do Google Workspace no seu projeto na nuvem do Google Cloud.
  • Configure a permissão do OAuth e crie credenciais para testes locais e implantação de produção.
  • Crie um agente ADK local que se conecte aos cinco servidores MCP do Workspace usando tokens estáticos.
  • Crie e implante um agente ADK pronto para produção no Agent Runtime da plataforma de agentes do Gemini Enterprise (GEAP) que usa a injeção de token dinâmico.
  • Registre e teste seu agente personalizado de forma nativa no Gemini Enterprise.

O que é necessário

  • Um navegador da Web (por exemplo, o Chrome).
  • Ter um projeto do Google Cloud com o faturamento ativado.
  • Uma conta do Google Workspace (com os recursos inteligentes ativados).
  • Python 3.11 ou mais recente instalado na máquina local.
  • A CLI do Google Cloud (gcloud) instalada e inicializada.

2. Antes de começar

Criar ou selecionar um projeto na nuvem do Google

Opção do console

No Console do Google Cloud, selecione ou crie um projeto na nuvem do Google Cloud.

Opção da CLI

Crie um novo projeto e defina-o como ativo:

gcloud projects create YOUR_PROJECT_ID
gcloud config set project YOUR_PROJECT_ID

Ative as APIs

Para usar os servidores MCP do Google Workspace, é necessário ativar as APIs padrão do Google Workspace e os serviços MCP dedicados.

Opção do console

Clique nos botões a seguir para ativá-los usando o navegador da Web:

Opção da CLI Execute estes comandos de terminal:

# Enable standard GWS APIs
gcloud services enable chat.googleapis.com \
  drive.googleapis.com \
  calendar-json.googleapis.com \
  people.googleapis.com \
  gmail.googleapis.com

# Enable dedicated MCP services
gcloud services enable calendarmcp.googleapis.com \
  chatmcp.googleapis.com \
  drivemcp.googleapis.com \
  gmailmcp.googleapis.com

Configurar o app do Chat

Para usar o servidor MCP do Google Chat, é necessário configurar um app do Chat no seu projeto do Google Cloud.

  1. No console do Google Cloud, pesquise API Google Chat e clique em API Google Chat > Gerenciar > Configuração.
  2. Configure o app do Chat:
    • Nome do app: ADK Workspace Agent
    • URL do avatar: https://developers.google.com/chat/images/quickstart-app-avatar.png
    • Descrição: MCP server connection for ADK Agent
    • Em Funcionalidade, desative a opção Ativar recursos interativos.
    • Em Registros, selecione Registrar erros no Logging.
  3. Clique em Salvar.

3. Configurar a permissão e os clientes do OAuth

Os servidores MCP do Google Workspace usam o OAuth 2.0 para autenticação segura. É necessário configurar a tela de permissão OAuth e criar dois IDs do cliente separados: um para desenvolvimento local e outro para o agente implantado.

  1. No console do Google Cloud, clique no menu de navegação (ícone de hambúrguer) no canto superior esquerdo. Selecione Plataforma de autenticação do Google > Branding (ou APIs e serviços > Tela de permissão OAuth se a Plataforma de autenticação do Google não estiver visível).
  2. Configure as informações do app:
    • Nome do app: Workspace ADK Agent
    • E-mail de suporte ao usuário: selecione seu e-mail.
  3. Configure o público: selecione Interno.
  4. Configure informações de contato: insira seu endereço de e-mail e clique em Criar.
  5. Acesse Acesso a dados > Adicionar ou remover escopos. Em Adicionar escopos manualmente, adicione os seguintes escopos para conceder acesso a todos os cinco serviços:
    https://www.googleapis.com/auth/calendar.calendarlist.readonly
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/calendar.calendars
https://www.googleapis.com/auth/chat.spaces
https://www.googleapis.com/auth/chat.messages
https://www.googleapis.com/auth/drive.readonly
https://www.googleapis.com/auth/drive.file
https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.compose
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/directory.readonly
https://www.googleapis.com/auth/userinfo.profile
https://www.googleapis.com/auth/contacts.readonly
https://www.googleapis.com/auth/cloud-platform
  6. Clique em Adicionar à tabela, Atualizar e, por fim, Salvar.

Criar o ID do cliente para desenvolvimento local (app para computador)

  1. No console do Google Cloud, acesse Plataforma de autenticação do Google > Clientes (ou APIs e serviços > Credenciais). Clique em Criar credenciais (ou Criar cliente OAuth) e selecione ID do cliente OAuth.
  2. Selecione App para computador como o tipo de aplicativo.
  3. Dê o nome Workspace Agent Local.
  4. Clique em Criar e faça o download do arquivo JSON. Salve-o localmente como client_secret.json.

4. Desenvolvimento e teste de agentes

Esta seção descreve como criar o ambiente do agente. Vamos usar uma abordagem de token estático para testes, em que buscamos um token OAuth usando gcloud e o transmitimos para McpToolset do ADK. Você pode seguir estas etapas usando sua máquina local ou o Google Cloud Shell.

Escolha seu ambiente: máquina local ou Google Cloud Shell para configurar seu ambiente de desenvolvimento. Os dois métodos vão usar um script Python compartilhado para autenticação, garantindo a consistência entre as plataformas.

1. Configurar o diretório do ambiente

Execute os comandos a seguir no terminal para criar um diretório de projeto e instalar os pacotes necessários.

  • Para o Google Cloud Shell:primeiro, clique no ícone Ativar o Cloud Shell (>_) na barra de ferramentas superior direita do console do Google Cloud.
  • Para a máquina local:abra o terminal padrão.
mkdir -p gws-adk-agent/workspace_agent
cd gws-adk-agent
python3 -m venv .venv
source .venv/bin/activate
pip install google-adk poetry google-auth-oauthlib

2. Preparar o arquivo de credenciais

É necessário colocar o arquivo client_secret.json que você fez o download na etapa anterior na raiz do diretório gws-adk-agent.

  • Máquina local:mova ou copie o arquivo client_secret.json transferido para o diretório gws-adk-agent.
  • Google Cloud Shell:crie o arquivo executando o comando a seguir no Cloud Shell (substitua [PASTE_JSON_HERE] pelo conteúdo JSON real):
cat << 'EOF' > client_secret.json
[PASTE_JSON_HERE]
EOF

3. Autenticar e gerar .env (auth.py)

Para processar a autenticação de maneira consistente e evitar problemas de roteamento da CLI específicos do ambiente, usamos um script Python personalizado com as bibliotecas de autenticação oficiais do Google. Esse script gerencia o fluxo do OAuth, salva as Application Default Credentials (ADC) localmente e gera o arquivo .env necessário.

Crie um arquivo chamado auth.py no diretório gws-adk-agent e adicione o seguinte código:

import json
import os
from urllib.parse import urlparse, parse_qs
import google.auth
from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_SECRET_FILE = 'client_secret.json'

SCOPES = [
    "https://www.googleapis.com/auth/cloud-platform",
    "https://www.googleapis.com/auth/calendar",
    "https://www.googleapis.com/auth/chat.spaces.readonly",
    "https://www.googleapis.com/auth/chat.messages",
    "https://www.googleapis.com/auth/drive.readonly",
    "https://www.googleapis.com/auth/gmail.readonly",
    "https://www.googleapis.com/auth/gmail.compose",
    "https://www.googleapis.com/auth/directory.readonly",
    "https://www.googleapis.com/auth/contacts.readonly"
]

# Initialize the flow from the client secrets JSON
flow = InstalledAppFlow.from_client_secrets_file(
    CLIENT_SECRET_FILE,
    scopes=SCOPES,
    redirect_uri='http://localhost:8085/'
)

# Generate the Auth URL
auth_url, expected_state = flow.authorization_url(prompt='consent', access_type='offline')

print("\n=== GOOGLE OAUTH OFFICIAL LIBRARY FLOW ===")
print("1. Copy the following link and paste it into your browser (or click it if supported):\n")
print(auth_url)
print("\n2. Authorize the application.")
print("3. Your browser will redirect to a 'localhost' page (it will show a 'Site can't be reached' error, which is EXPECTED and normal).")
print("4. Copy the ENTIRE URL from your browser's address bar (including the http://localhost:8085/ part).\n")

# Get the redirected URL from the user
redirected_url = input("Paste the full localhost URL here: ").strip()

# Exchange the redirect URL for tokens
print("\nExchanging code for tokens...")
try:
    parsed_url = urlparse(redirected_url)
    query_params = parse_qs(parsed_url.query)

    returned_state = query_params.get('state', [None])[0]
    code = query_params.get('code', [None])[0]

    if not code:
        raise ValueError("No 'code' parameter found in the URL.")
    if returned_state != expected_state:
        raise ValueError("CSRF Warning! State mismatch.")

    flow.fetch_token(code=code)
    creds = flow.credentials
except Exception as e:
    print(f"Authentication failed: {e}")
    exit(1)

if not creds.refresh_token:
    print("\nError: No refresh token returned. You may need to revoke access and try again.")
    exit(1)

# Save Application Default Credentials
adc_data = {
    "client_id": creds.client_id,
    "client_secret": creds.client_secret,
    "refresh_token": creds.refresh_token,
    "type": "authorized_user"
}

adc_dir = os.path.expanduser("~/.config/gcloud")
os.makedirs(adc_dir, exist_ok=True)
adc_path = os.path.join(adc_dir, "application_default_credentials.json")

with open(adc_path, "w") as f:
    json.dump(adc_data, f, indent=2)

# Detect Project ID
try:
    _, project_id = google.auth.default()
except Exception:
    project_id = None

project_id = project_id or os.environ.get("GOOGLE_CLOUD_PROJECT", "YOUR_PROJECT_ID")

# Save to .env for local development (relative to project root)
env_dir = "workspace_agent"
os.makedirs(env_dir, exist_ok=True)
env_path = os.path.join(env_dir, ".env")

with open(env_path, "w") as f:
    f.write("GOOGLE_GENAI_USE_VERTEXAI=1\n")
    f.write(f"GOOGLE_CLOUD_PROJECT={project_id}\n")
    f.write("GOOGLE_CLOUD_LOCATION=us-central1\n")

print(f"\nSuccess! Application Default Credentials saved to: {adc_path}")
print(f"Environment variables saved to: {env_path}")
if project_id == "YOUR_PROJECT_ID":
    print("NOTE: Could not automatically detect Project ID. Please update it manually in .env")

Execute o script no terminal:

python3 auth.py

Criar o código do agente

Independente do ambiente escolhido na etapa anterior, o código do agente permanece exatamente o mesmo. Crie um arquivo chamado agent.py no subdiretório workspace_agent pré-criado e adicione o seguinte código. Esse script usa as Application Default Credentials (ADC) para fornecer autorização, validando e atualizando automaticamente as credenciais na memória por meio de um provedor de cabeçalho dinâmico.

import os
import datetime

import google.auth
from google.auth.transport.requests import Request
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# Enable graceful error handling so timeouts return as tool outputs instead of crashing
os.environ["ADK_ENABLE_MCP_GRACEFUL_ERROR_HANDLING"] = "1"

MODEL = "gemini-2.5-flash"

# Inject User ADC path globally so both ADK and underlying GenAI SDKs
# load it safely, bypassing broken Compute Engine metadata fallbacks.
_adc_path = os.path.expanduser(
    "~/.config/gcloud/application_default_credentials.json"
)
if not os.path.exists(_adc_path):
    raise FileNotFoundError(
        f"User ADC not found at {_adc_path}. "
        "Please run 'python3 auth.py' first to generate credentials."
    )
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = _adc_path

creds, _ = google.auth.default()


class TokenRelay:
    """Manages in-memory caching of Google OAuth access tokens.

    Decouples token refresh logic from credentials validation states to
    prevent infinite refresh loops during automated tool retries.
    """

    def __init__(self, credentials):
        self._creds = credentials
        self._cached_token: str | None = None
        self._expiry: datetime.datetime | None = None

    def get_token(self) -> str:
        now = datetime.datetime.now()
        # Refresh if no cache or expiring within 5 minutes
        if (
            self._cached_token is None
            or self._expiry is None
            or now >= (self._expiry - datetime.timedelta(minutes=5))
        ):
            self._creds.refresh(Request())
            self._cached_token = self._creds.token
            # Token lives for 60 mins; cache for 50 mins safely
            self._expiry = now + datetime.timedelta(minutes=50)
            print("\n[Agent Runtime] Access token refreshed from ADC.")
        return self._cached_token or ""


# Initialize auth relay and perform startup safety check
token_relay = TokenRelay(creds)
token_relay.get_token()


def auth_header_provider(tool_context=None) -> dict[str, str]:
    return {"Authorization": f"Bearer {token_relay.get_token()}"}


# Initialize the 5 GWS MCP servers with dynamic runtime provider
calendar_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://calendarmcp.googleapis.com/mcp/v1",
    ),
    header_provider=auth_header_provider
)
chat_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://chatmcp.googleapis.com/mcp/v1",
    ),
    header_provider=auth_header_provider
)
drive_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://drivemcp.googleapis.com/mcp/v1",
    ),
    header_provider=auth_header_provider
)
gmail_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://gmailmcp.googleapis.com/mcp/v1",
    ),
    header_provider=auth_header_provider
)
people_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://people.googleapis.com/mcp/v1",
    ),
    header_provider=auth_header_provider
)

current_date = datetime.datetime.now().strftime("%Y-%m-%d")

# Define the agent and attach all 5 toolsets
root_agent = LlmAgent(
    model=MODEL,
    name='gws_adk_agent',
    instruction=f"""You are a helpful assistant grounded in the user's Google Workspace data.
    Today's current date is {current_date}. Always calculate relative dates (like 'this week' or 'upcoming meetings') using this reference.
    Use the provided MCP tools to answer questions about their Calendar, Chat, Drive, Gmail, and Contacts.
    If a tool returns an error indicating a timeout, inform the user that the service took too long to respond.""",
    tools=[calendar_mcp, chat_mcp, drive_mcp, gmail_mcp, people_mcp]
)

Executar e testar o agente

Você pode interagir com o agente usando a interface da Web interativa ou diretamente no terminal/shell.

Opção 1: interface da Web interativa

Se você estiver em uma máquina local:

  1. No diretório raiz do projeto gws-adk-agent, inicie a interface da Web do ADK:
    adk web
  2. Abra http://localhost:8000 no navegador para conversar com o agente.

Se você estiver no Google Cloud Shell:

  1. No diretório raiz do projeto gws-adk-agent, inicie a interface da Web do ADK, aplicando explicitamente a porta 8080:
    adk web --port 8080 --allow_origins=*
  2. Clique no botão Visualização da Web no canto superior direito da barra de ferramentas do Cloud Shell e selecione Visualizar na porta 8080 para abrir a interface em uma nova guia.

Opção 2: modo de CLI do terminal (alternativa)

Se você preferir permanecer no terminal ou evitar a configuração de visualizações do navegador da Web, o ADK oferece um modo de chat REPL interativo nativo.

No diretório raiz do projeto gws-adk-agent, execute o comando a seguir (ele funciona de maneira idêntica em uma máquina local e no Google Cloud Shell):

adk run workspace_agent

Você vai acessar uma sessão de chat interativa diretamente no shell:

Running agent gws_adk_agent, type exit to exit.

[user]:

Tentar solicitar o agente

Independente da interface escolhida, tente testar o agente com consultas que aproveitam as ferramentas MCP do Workspace:

What are my upcoming meetings this week?

Summarize the last 3 unread emails in my Gmail.

5. Implantação de produção

Para implantar o agente na produção, não podemos usar um token local codificado. Em vez disso, usamos o header_provider do ADK para extrair dinamicamente o token de acesso do OAuth injetado pela plataforma do Gemini Enterprise quando um usuário interage com o agente.

Criar o código do agente de produção

Crie um pacote de diretório chamado enterprise_ai e um arquivo agent.py dentro dele:

mkdir -p enterprise_ai

Grave o conteúdo a seguir em enterprise_ai/agent.py:

import os
import datetime
import re
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.tool_context import ToolContext

# Enable graceful error handling so timeouts return as tool outputs instead of crashing
os.environ["ADK_ENABLE_MCP_GRACEFUL_ERROR_HANDLING"] = "1"

MODEL = "gemini-2.5-flash"
# This name MUST match the Authorization Name used during Gemini Enterprise registration
CLIENT_AUTH_NAME = "workspace-adk-auth"

def _get_access_token_from_context(tool_context: ToolContext) -> str:
    """Dynamically parses the user bearer token injected into the ToolContext state."""
    escaped_name = re.escape(CLIENT_AUTH_NAME)
    pattern = re.compile(fr"^{escaped_name}_\d+$")
    state_dict = tool_context.state.to_dict() if hasattr(tool_context.state, 'to_dict') else tool_context.state
    matching_keys = [k for k in state_dict.keys() if pattern.match(k)]
    if matching_keys:
        return state_dict.get(matching_keys[0])
    raise Exception(f"No bearer token found in ToolContext state matching pattern {pattern.pattern}")

def auth_header_provider(tool_context: ToolContext) -> dict[str, str]:
    """Provides the dynamic Authorization header for MCP requests."""
    token = _get_access_token_from_context(tool_context)
    return {"Authorization": f"Bearer {token}"}

# Initialize toolsets using the dynamic header_provider
calendar_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://calendarmcp.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)
chat_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://chatmcp.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)
drive_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://drivemcp.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)
gmail_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://gmailmcp.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)
people_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://people.googleapis.com/mcp/v1"),
    header_provider=auth_header_provider
)

current_date = datetime.datetime.now().strftime("%Y-%m-%d")

root_agent = LlmAgent(
    model=MODEL,
    name='enterprise_ai',
    instruction=f"""You are an enterprise assistant grounded securely in the user's Workspace data.
    Today's current date is {current_date}. Always calculate relative dates (like 'this week' or 'upcoming meetings') using this reference.
    Always use the provided MCP tools to fetch context from Calendar, Chat, Drive, Gmail, and People.
    If a tool returns an error indicating a timeout, inform the user that the service took too long to respond.""",
    tools=[calendar_mcp, chat_mcp, drive_mcp, gmail_mcp, people_mcp]
)

Implantar no Agent Runtime da GEAP

Implante seu agente de código profissional usando a CLI do ADK:

adk deploy agent_engine \
  --project=$(gcloud config get-value project) \
  --region=us-central1 \
  --display_name="Workspace ADK Agent" \
  enterprise_ai

Aguarde a conclusão da implantação e copie o nome do recurso do Reasoning Engine gerado na saída do terminal (por exemplo, projects/PROJECT_ID/locations/us-central1/reasoningEngines/ENGINE_ID).

6. Registrar no Gemini Enterprise

Agora, vamos trazer o agente ADK personalizado para o Gemini Enterprise para que os usuários possam conversar com ele de forma nativa.

Criar o ID do cliente para produção (aplicativo da Web)

Para implantar o agente na produção, é necessário criar um ID do cliente do aplicativo da Web. Ao contrário do cliente de computador usado para testes locais, um cliente de aplicativo da Web permite um fluxo OAuth seguro do lado do servidor. Isso permite que o agente hospedado no Agent Runtime da GEAP receba com segurança os tokens de autenticação do usuário encaminhados pelo Gemini Enterprise, usando o URI de redirecionamento especificado. Essa configuração é necessária para que o agente acesse com segurança os dados do Google Workspace em nome do usuário em um ambiente de produção.

  1. No console do Google Cloud, clique no menu de navegação (ícone de hambúrguer) no canto superior esquerdo. Selecione Plataforma de autenticação do Google > Clientes (ou APIs e serviços > Credenciais se a Plataforma de autenticação do Google não estiver visível). Clique em Criar credenciais (ou Criar cliente OAuth) e selecione ID do cliente OAuth.
  2. Selecione Aplicativo da Web como o tipo de aplicativo.
  3. Dê o nome Workspace Agent Production.
  4. Na seção URIs de redirecionamento autorizados, adicione os seguintes URIs:
    • Clique em Adicionar URI e insira https://vertexaisearch.cloud.google.com/oauth-redirect.
    • Clique em Adicionar URI novamente e insira https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
  5. Clique em Criar. No pop-up "Cliente OAuth criado" (ou na lista Clientes ), copie o ID do cliente e a chave secreta do cliente. Você vai precisar deles ao registrar o agente no Gemini Enterprise.

Criar um app do Gemini Enterprise

  1. No console do Google Cloud, acesse a página Gemini Enterprise:

  1. No card Gemini Enterprise, clique em Gerenciar.
  2. Clique em Criar App.
  3. Na seção Gemini Enterprise, clique em Criar.
  4. No campo Nome do app, insira um nome para seu app. O ID do app aparece abaixo do nome dele.
  5. No campo Nome externo da sua empresa ou organização, insira o nome da empresa ou organização. Neste tutorial, use Cymbal Bank.
  6. Selecione Global (Global) como o local do app.
  7. Clique em Continuar.

Registrar o agente personalizado

  1. Abra o console do Gemini Enterprise:

  1. Selecione seu app ativo, acesse Agentes e clique em + Adicionar agente > Adicionar agente personalizado pelo Agent Runtime.
  2. Na seção Autorizações, clique em Adicionar autorização:
    • Nome da autorização: workspace-adk-auth (precisa corresponder exatamente a CLIENT_AUTH_NAME no seu código Python)
    • ID do cliente: cole o ID do cliente do aplicativo da Web de produção criado acima.
    • Chave secreta do cliente: cole a chave secreta do cliente do aplicativo da Web de produção criada acima.
    • URI do token: https://oauth2.googleapis.com/token
    • URI de autorização: crie o URI substituindo YOUR_CLIENT_ID pelo ID do cliente que você copiou na etapa 5 acima:
      https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.calendars%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcalendar.events%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.send%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgmail.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fchat.spaces%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fchat.messages%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.file%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdirectory.readonly&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
  3. Clique em Concluído e em Próxima.
  4. Na seção Configuração:
    • Nome do agente: Workspace Pro Agent
    • Descrição:
      Use this agent to answer questions about your Google Workspace data, including Gmail, Google Drive, Google Calendar, Google Chat, and Contacts. It can find files, summarize emails, check your schedule, and look up contact information.
    • Reasoning Engine do Agent Runtime: cole o nome do recurso do mecanismo que você copiou da saída adk deploy.
  5. Clique em Criar.

Testar o agente no Gemini Enterprise

Você pode interagir com o agente usando a prévia do console do Google Cloud (mais rápida para desenvolvedores) ou o app da Web do Gemini Enterprise (experiência do usuário final).

Opção 1: prévia do console do Google Cloud

  1. No console do Google Cloud, acesse a página Gemini Enterprise:

  1. No menu de navegação, clique em Apps e selecione o app que você acabou de criar.
  2. Clique em Prévia ou em Abrir prévia no canto superior direito.
  3. Na barra de pesquisa, insira a seguinte consulta:
    Search for files in Drive related to 'Project Milestone', summarize them, and tell me if I have any meetings with the project owner today.
  4. Pressione Enter para enviar a consulta e conferir os resultados diretamente no console.

Opção 2: app da Web do Gemini Enterprise

  1. Abra a interface do app da Web do Gemini Enterprise.
  2. Acesse Menu ☰ > Agentes e selecione Workspace Pro Agent em Da sua organização.
  3. Digite a mesma consulta da opção de prévia do console do Google Cloud.
  4. Clique em Autorizar quando solicitado a passar pelo fluxo de consentimento do usuário do OAuth.
  5. O agente vai executar tarefas de maneira integrada em vários serviços usando o protocolo MCP.

7. Limpar

Para evitar cobranças desnecessárias, limpe seus recursos:

Opção do console

Acesse o painel de APIs e serviços, selecione os serviços MCP ativados (por exemplo, MCP da Agenda, MCP do Gmail) e clique em Desativar API. Exclua os IDs do cliente OAuth em Plataforma de autenticação do Google > Clientes e exclua a implantação do Reasoning Engine no console do Gemini Enterprise.

Opção da CLI

Execute os comandos de terminal a seguir para desativar os serviços MCP:

# Disable Workspace MCP services
gcloud services disable calendarmcp.googleapis.com \
  chatmcp.googleapis.com \
  drivemcp.googleapis.com \
  gmailmcp.googleapis.com

8. Parabéns

Parabéns! Você criou, testou e implantou com sucesso um agente de IA ADK de código profissional conectado diretamente aos servidores MCP oficiais do Google Workspace.

O que você aprendeu

  • Como ativar os serviços MCP do Google Workspace no Google Cloud.
  • Como processar credenciais OAuth para testes locais do ADK usando cabeçalhos estáticos.
  • Como implementar a injeção de token dinâmico usando header_provider para agentes de produção.
  • Como implantar um agente ADK no Agent Runtime da GEAP e registrá-lo no Gemini Enterprise.

Documentos de referência