Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Crea un agente AI di Google Workspace con ADK e MCP

1. Introduzione

In questo codelab imparerai a creare un agente AI pro-code utilizzando l'Agent Development Kit (ADK) che si connette direttamente ai server MCP di Google Workspace ufficiali.

Model Context Protocol (MCP) è uno standard aperto che consente ai modelli di AI di utilizzare in modo sicuro gli strumenti forniti dai server remoti. ADK è il framework pro-code di Google per la creazione di agenti autonomi. Combinandoli, puoi creare agenti altamente personalizzati basati sui tuoi dati di Gmail, Google Drive, Google Calendar, Google Chat e Persone.

Per la documentazione completa sugli strumenti e sulla configurazione disponibili, vedi Configurare i server MCP di Google Workspace.

In questo lab proverai a:

Abilita i servizi Google Workspace MCP nel tuo progetto Google Cloud.
Configura il consenso OAuth e crea le credenziali per i test locali e il deployment di produzione.
Crea un agente ADK locale che si connette ai 5 server MCP di Workspace utilizzando token statici.
Crea ed esegui il deployment di un agente ADK pronto per la produzione in Gemini Enterprise Agent Platform (GEAP) Agent Runtime che utilizza l'inserimento dinamico di token.
Registra e testa il tuo agente personalizzato in modo nativo in Gemini Enterprise.

Che cosa ti serve

Un browser web (ad es. Chrome).
Un progetto Google Cloud con la fatturazione abilitata.
Un account Google Workspace (con le funzionalità intelligenti attivate).
Python 3.11 o versioni successive installato sulla tua macchina locale.
Google Cloud CLI (gcloud) installato e inizializzato.

2. Prima di iniziare

Crea o seleziona un progetto Google Cloud

Opzione della console

Nella console Google Cloud, seleziona o crea un progetto Google Cloud.

Opzione CLI

Crea un nuovo progetto e impostalo come attivo:

gcloud projects create YOUR_PROJECT_ID
gcloud config set project YOUR_PROJECT_ID

Abilita le API

Per utilizzare i server MCP di Google Workspace, devi abilitare sia le API Google Workspace standard sia i servizi MCP dedicati.

Opzione della console

Fai clic sui seguenti pulsanti per abilitarle utilizzando il browser web:

Opzione CLI Esegui questi comandi del terminale:

# 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

Configurare l'app Chat

Per utilizzare il server MCP di Google Chat, devi configurare un'app Chat nel tuo progetto Google Cloud.

Vai ad API Google Chat > Gestisci > Configurazione.
Configura l'app Chat:
- Nome dell'app: ADK Workspace Agent
- URL avatar: https://developers.google.com/chat/images/quickstart-app-avatar.png
- Descrizione: MCP server connection for ADK Agent
- Nella sezione Funzionalità, disattiva l'opzione Attiva funzionalità interattive.
- In Log, seleziona Errori di log in Logging.
Fai clic su Salva.

3. Configurare il consenso e i client OAuth

I server MCP di Google Workspace utilizzano OAuth 2.0 per l'autenticazione sicura. Devi configurare la schermata per il consenso OAuth e creare due ID client separati: uno per lo sviluppo locale e uno per l'agente di cui è stato eseguito il deployment.

Nella console Google Cloud, fai clic sul menu di navigazione (icona a forma di hamburger) nell'angolo in alto a sinistra. Seleziona Google Auth Platform > Branding (o API e servizi > schermata per il consenso OAuth se Google Auth Platform non è visibile).
Configura Informazioni app:
- Nome dell'app: Workspace ADK Agent
- Email per assistenza utenti: seleziona la tua email.
Configura Pubblico: seleziona Interno.
Configura Informazioni di contatto: inserisci il tuo indirizzo email e fai clic su Crea.

Vai ad Accesso ai dati > Aggiungi o rimuovi ambiti. In Aggiungi ambiti manualmente, aggiungi i seguenti ambiti per concedere l'accesso a tutti e cinque i servizi:

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

Fai clic su Aggiungi alla tabella, poi su Aggiorna e infine su Salva.

Creare un ID client per lo sviluppo locale (app desktop)

Nella console Google Cloud, vai a Google Auth Platform > Client (o API e servizi > Credenziali). Fai clic su Crea credenziali (o Crea client) e seleziona ID client OAuth.
Seleziona App per computer come tipo di applicazione.
Assegna il nome Workspace Agent Local.
Fai clic su Crea e scarica il file JSON. Salvalo localmente come client_secret.json.

4. Sviluppo e test di agenti

Questa sezione descrive come creare l'ambiente dell'agente. Per i test utilizzeremo un approccio con token statici, in cui recuperiamo un token OAuth utilizzando gcloud e lo trasmettiamo a McpToolset di ADK. Puoi seguire questi passaggi utilizzando la macchina locale o Google Cloud Shell.

Scegli l'ambiente: Macchina locale o Google Cloud Shell per configurare l'ambiente di sviluppo. Entrambi i metodi utilizzeranno uno script Python condiviso per l'autenticazione per garantire la coerenza tra le piattaforme.

1. Configurare la directory dell'ambiente

Esegui questi comandi nel terminale per creare una directory di progetto e installare i pacchetti richiesti.

Per Google Cloud Shell:innanzitutto, fai clic sull'icona Attiva Cloud Shell (>_) nella barra degli strumenti in alto a destra della console Google Cloud.
Per la macchina locale:apri il terminale standard.

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. Prepara il file delle credenziali

Devi inserire il file client_secret.json scaricato nel passaggio precedente nella directory principale di gws-adk-agent.

Macchina locale:sposta o copia il file client_secret.json scaricato nella directory gws-adk-agent.
Google Cloud Shell: crea il file eseguendo questo comando in Cloud Shell (sostituisci [PASTE_JSON_HERE] con i contenuti JSON effettivi):

cat << 'EOF' > client_secret.json
[PASTE_JSON_HERE]
EOF

3. Autentica e genera .env (`auth.py`)

Per gestire l'autenticazione in modo coerente ed evitare problemi di routing della CLI specifici per l'ambiente, utilizziamo uno script Python personalizzato basato sulle librerie di autenticazione ufficiali di Google. Questo script gestisce il flusso OAuth, salva le credenziali predefinite dell'applicazione (ADC) in locale e genera il file .env richiesto.

Crea un file denominato auth.py nella directory gws-adk-agent e aggiungi il seguente codice:

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")

Esegui lo script nel terminale:

python3 auth.py

Crea il codice agente

Indipendentemente dall'ambiente scelto nel passaggio precedente, il codice dell'agente rimane esattamente lo stesso. Crea un file denominato agent.py all'interno della sottodirectory workspace_agent creata in precedenza e aggiungi il seguente codice. Questo script utilizza le credenziali predefinite dell'applicazione (ADC) per fornire l'autorizzazione, con la convalida e l'aggiornamento automatici delle credenziali esclusivamente in memoria tramite un provider di intestazioni dinamiche.

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

MODEL = "gemini-2.5-flash"

# Load credentials from Application Default Credentials (ADC) saved by auth.py
creds, _ = google.auth.default()

# 1. STARTUP SAFETY: Ensure valid token at import time for static tool discovery (e.g. adk web UI load)
if not creds.valid:
    creds.refresh(Request())
    print("\n[Agent Startup] Access token refreshed from ADC.")

def auth_header_provider(tool_context=None) -> dict[str, str]:
    """2. RUNTIME SAFETY: Dynamically provides auth headers, refreshing if expired during the session."""
    if not creds.valid:
        creds.refresh(Request())
        print("\n[Agent Runtime] Access token refreshed from ADC.")
    return {"Authorization": f"Bearer {creds.token}"}

# Initialize the 5 GWS MCP servers with combined startup headers and dynamic runtime provider
calendar_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://calendarmcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
chat_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://chatmcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
drive_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://drivemcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
gmail_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://gmailmcp.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    header_provider=auth_header_provider
)
people_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://people.googleapis.com/mcp/v1",
        headers={"Authorization": f"Bearer {creds.token}"}
    ),
    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.""",
    tools=[calendar_mcp, chat_mcp, drive_mcp, gmail_mcp, people_mcp]
)

Esegui e testa l'agente

Puoi interagire con l'agente utilizzando l'interfaccia utente web interattiva o direttamente all'interno del terminale/shell.

Opzione 1: interfaccia utente web interattiva

Se utilizzi un computer locale:

Dalla directory radice del progetto gws-adk-agent, avvia l'interfaccia web di ADK:
```
adk web
```
Apri http://localhost:8000 nel browser per chattare con l'agente.

Se ti trovi in Google Cloud Shell:

Dalla directory principale del progetto gws-adk-agent, avvia l'interfaccia web dell'ADK applicando esplicitamente la porta 8080:
```
adk web --port 8080 --allow_origins=*
```
Fai clic sul pulsante Anteprima web in alto a destra nella barra degli strumenti di Cloud Shell e seleziona Anteprima sulla porta 8080 per aprire l'interfaccia in una nuova scheda.

Opzione 2: modalità CLI del terminale (alternativa)

Se preferisci rimanere nel terminale o vuoi evitare di configurare le anteprime del browser web, ADK fornisce una modalità chat REPL interattiva nativa.

Dalla directory principale del progetto gws-adk-agent, esegui il comando seguente (funziona allo stesso modo sia su una macchina locale che su Google Cloud Shell):

adk run workspace_agent

Verrà avviata una sessione di chat interattiva direttamente nella shell:

Running agent gws_adk_agent, type exit to exit.
[user]:

Prova a dare un prompt al tuo agente

Indipendentemente dall'interfaccia scelta, prova a testare l'agente con query che sfruttano gli strumenti MCP di Workspace:

What are my upcoming meetings this week?

Summarize the last 3 unread emails in my Gmail.

5. Deployment di produzione

Per eseguire il deployment dell'agente in produzione, non possiamo utilizzare un token locale hardcoded. Utilizziamo invece header_provider dell'ADK per estrarre dinamicamente il token di accesso OAuth inserito dalla piattaforma Gemini Enterprise quando un utente interagisce con l'agente.

Crea il codice dell'agente di produzione

Crea un pacchetto di directory denominato enterprise_ai e crea un file agent.py al suo interno:

mkdir -p enterprise_ai

Scrivi i seguenti contenuti in enterprise_ai/agent.py:

import datetime
import os
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

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.""",
    tools=[calendar_mcp, chat_mcp, drive_mcp, gmail_mcp, people_mcp]
)

Esegui il deployment in GEAP Agent Runtime

Esegui il deployment dell'agente pro-code utilizzando la CLI ADK:

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

Attendi il completamento del deployment e copia il nome della risorsa Reasoning Engine generato dall'output del terminale (ad es. projects/PROJECT_ID/locations/us-central1/reasoningEngines/ENGINE_ID).

6. Registrati in Gemini Enterprise

Ora, importiamo l'agente ADK personalizzato in Gemini Enterprise in modo che gli utenti possano chattare in modo nativo.

Crea l'ID client per la produzione (applicazione web)

Per eseguire il deployment dell'agente in produzione, devi creare un ID client applicazione web. A differenza del client desktop utilizzato per i test locali, un client di applicazione web consente un flusso OAuth sicuro lato server. In questo modo, l'agente ospitato in GEAP Agent Runtime può ricevere in modo sicuro i token di autenticazione dell'utente inoltrati da Gemini Enterprise, utilizzando l'URI di reindirizzamento specificato. Questa configurazione è necessaria per consentire all'agente di accedere in modo sicuro ai dati di Google Workspace per conto dell'utente in un ambiente di produzione.

Nella console Google Cloud, fai clic sul menu di navigazione (icona a forma di hamburger) nell'angolo in alto a sinistra. Seleziona Google Auth Platform > Client (o API e servizi > Credenziali se Google Auth Platform non è visibile). Fai clic su Crea credenziali (o Crea client) e seleziona ID client OAuth.
Seleziona Applicazione web come tipo di applicazione.
Assegna il nome Workspace Agent Production.
Nella sezione URI di reindirizzamento autorizzati, aggiungi i seguenti URI:
- Fai clic su Aggiungi URI e inserisci https://vertexaisearch.cloud.google.com/oauth-redirect.
- Fai di nuovo clic su Aggiungi URI e inserisci https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
Fai clic su Crea. Nel popup "Client OAuth creato" (o dall'elenco Client), copia l'ID client e il client secret. Ti serviranno per registrare l'agente in Gemini Enterprise.

Crea un'app Gemini Enterprise

Nella console Google Cloud, vai alla pagina Gemini Enterprise:

Nella scheda Gemini Enterprise, fai clic su Gestisci.
Fai clic su Crea app.
Nella sezione Gemini Enterprise, fai clic su Crea.
Nel campo Nome app, inserisci un nome per l'app. L'ID dell'app è riportato sotto il nome dell'app.
Nel campo Nome esterno della tua azienda o organizzazione, inserisci il nome dell'azienda o dell'organizzazione. Per questo tutorial, puoi utilizzare Cymbal Bank.
Seleziona globale (Globale) come località per la tua app.
Fai clic su Continua.

Registra l'agente personalizzato

Apri la console Gemini Enterprise:

Seleziona l'app attiva, vai ad Agenti e fai clic su + Aggiungi agente > Aggiungi agente personalizzato tramite Agent Runtime.

Nella sezione Autorizzazioni, fai clic su Aggiungi autorizzazione:

Nome autorizzazione: workspace-adk-auth (deve corrispondere esattamente a CLIENT_AUTH_NAME nel codice Python)
ID client: incolla l'ID client dell'applicazione web di produzione creato sopra.
Client secret: incolla il client secret dell'applicazione web di produzione creato sopra.
URI token: https://oauth2.googleapis.com/token

URI di autorizzazione: crea l'URI sostituendo YOUR_CLIENT_ID con l'ID client che hai copiato nel passaggio 5:

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

Fai clic su Fine, poi su Avanti.

Nella sezione Configurazione:

Nome agente: Workspace Pro Agent

Descrizione:

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.

Motore di ragionamento di Agent Runtime: incolla il nome risorsa del motore che hai copiato dall'output di adk deploy.

Fai clic su Crea.

Prova l'agente in Gemini Enterprise

Puoi interagire con l'agente utilizzando l'anteprima della console Google Cloud (il modo più rapido per gli sviluppatori) o l'app web Gemini Enterprise (esperienza utente finale).

Opzione 1: anteprima della console Google Cloud

Nella console Google Cloud, vai alla pagina Gemini Enterprise:

Nel menu di navigazione, fai clic su App e seleziona l'app che hai appena creato.
Fai clic su Anteprima o su Apri anteprima in alto a destra.

Nella barra di ricerca, inserisci la seguente query:

Search for files in Drive related to 'Project Milestone', summarize them, and tell me if I have any meetings with the project owner today.

Premi Invio per inviare la query e visualizzare i risultati direttamente nella console.

Opzione 2: app web Gemini Enterprise

Apri l'interfaccia dell'app web Gemini Enterprise.
Vai a Menu ☰ > Agenti e seleziona Agente Workspace Pro in Dalla tua organizzazione.
Digita la stessa query dell'opzione Anteprima della console Google Cloud.
Fai clic su Autorizza quando ti viene chiesto di seguire il flusso di consenso dell'utente OAuth.
L'agente eseguirà le attività senza problemi su più servizi utilizzando il protocollo MCP.

7. Esegui la pulizia

Per evitare addebiti non necessari, libera spazio nelle risorse:

Opzione Console

Vai alla dashboard API e servizi, seleziona i servizi MCP che hai abilitato (ad es. Calendar MCP, Gmail MCP) e fai clic su Disattiva API. Elimina gli ID client OAuth in Google Auth Platform > Client ed elimina il deployment di Reasoning Engine dalla console Gemini Enterprise.

Opzione CLI

Esegui questi comandi del terminale per disattivare i servizi MCP:

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

8. Complimenti

Complimenti! Hai creato, testato e implementato correttamente un agente AI ADK pro-code connesso direttamente ai server MCP ufficiali di Google Workspace.

Cosa hai imparato

Come attivare i servizi MCP di Google Workspace in Google Cloud.
Come gestire le credenziali OAuth per i test ADK locali utilizzando intestazioni statiche.
Come implementare l'inserimento dinamico di token utilizzando header_provider per gli agenti di produzione.
Come eseguire il deployment di un agente ADK in GEAP Agent Runtime e registrarlo in Gemini Enterprise.

Crea un agente AI di Google Workspace con ADK e MCP

1. Introduzione

In questo lab proverai a:

Che cosa ti serve

2. Prima di iniziare

Crea o seleziona un progetto Google Cloud

Opzione della console

Opzione CLI

Abilita le API

Opzione della console

Opzione CLI Esegui questi comandi del terminale:

Configurare l'app Chat

3. Configurare il consenso e i client OAuth

Configurare la schermata per il consenso OAuth

Creare un ID client per lo sviluppo locale (app desktop)

4. Sviluppo e test di agenti

1. Configurare la directory dell'ambiente

2. Prepara il file delle credenziali

3. Autentica e genera .env (auth.py)

Crea il codice agente

Esegui e testa l'agente

Opzione 1: interfaccia utente web interattiva

Se utilizzi un computer locale:

Se ti trovi in Google Cloud Shell:

Opzione 2: modalità CLI del terminale (alternativa)

Prova a dare un prompt al tuo agente

5. Deployment di produzione

Crea il codice dell'agente di produzione

Esegui il deployment in GEAP Agent Runtime

6. Registrati in Gemini Enterprise

Crea l'ID client per la produzione (applicazione web)

Crea un'app Gemini Enterprise

Registra l'agente personalizzato

Prova l'agente in Gemini Enterprise

Opzione 1: anteprima della console Google Cloud

Opzione 2: app web Gemini Enterprise

7. Esegui la pulizia

Opzione Console

Opzione CLI

8. Complimenti

Cosa hai imparato

Documenti di riferimento

3. Autentica e genera .env (`auth.py`)