Esegui il deployment di un agente consapevole della governance aziendale con MCP e Cloud Run

1. Introduzione

Questo codelab fa parte di una serie in due parti che esplora come creare un agente GenAI consapevole della governance.

Puoi leggere la prima parte di questa serie, che spiega come stabilire la base dei dati applicando gli aspetti di Dataplex alle tabelle BigQuery e testando le regole localmente tramite la CLI Gemini. 👉 Leggi la parte 1)

Tuttavia, i test in una CLI locale sono solo l'inizio. Per implementare questa soluzione in tutta l'azienda, hai bisogno di una sicurezza centralizzata, di connessioni standardizzate agli strumenti di AI e di un framework applicativo adeguato per orchestrare la logica dell'agente e fornire un'interfaccia di chat familiare.

In questa seconda parte, risolverai queste sfide e passerai alla produzione. Eseguirai il deployment delle regole di governance in un server MCP centrale ospitato su Cloud Run. Poi, utilizzerai l'Agent Development Kit (ADK) di Google per creare l'applicazione dell'agente vera e propria e connetterla agli strumenti MCP, il tutto con un'interfaccia utente web professionale.

be15d5f41f0d716c.png

Prerequisiti

  • Un progetto Google Cloud con la fatturazione abilitata.
  • Conoscenza di base di Cloud Run, service account IAM e Python.
  • I set di dati BigQuery e gli aspetti Dataplex creati nella parte 1. Non preoccuparti se li hai eliminati. Di seguito è riportato uno script rapido per ricrearli.

Cosa imparerai a fare

  • Come utilizzare il Model Context Protocol (MCP) per standardizzare il modo in cui gli agenti AI interagiscono con i dati di Google Cloud.
  • Come eseguire il deployment di un server MCP sicuro su Cloud Run.
  • Come creare un agente AI utilizzando l'Agent Development Kit (ADK) e connetterlo al backend MCP.
  • Come eseguire l'interfaccia utente per sviluppatori integrata dell'ADK per interagire con l'agente controllato.

Che cosa ti serve

  • Accesso a Google Cloud Shell

Concetti fondamentali

  • Model Context Protocol (MCP): considera l'MCP come un "cavo USB-C universale" per gli agenti AI. Invece di scrivere codice di integrazione API personalizzato per ogni singolo modello di AI, MCP fornisce un modo standard per l'AI di connettersi in modo sicuro ai tuoi strumenti di dati aziendali (come Dataplex e BigQuery).
  • Agent Development Kit (ADK): un framework open source flessibile di Google progettato per semplificare lo sviluppo end-to-end di agenti AI. Applica i principi dell'ingegneria del software alla creazione di agenti, consentendoti di orchestrare strumenti complessi, gestire lo stato e avviare facilmente un'interfaccia utente per sviluppatori integrata per test e deployment.

2. Configurazione e requisiti

Avvia Cloud Shell

Sebbene Google Cloud possa essere gestito da remoto dal tuo laptop, in questo codelab utilizzerai Google Cloud Shell, un ambiente a riga di comando in esecuzione nel cloud.

Nella console Google Cloud, fai clic sull'icona di Cloud Shell nella barra degli strumenti in alto a destra:

Attiva Cloud Shell

Bastano pochi istanti per eseguire il provisioning e connettersi all'ambiente. Al termine, dovresti vedere un risultato simile a questo:

Screenshot del terminale Google Cloud Shell che mostra che l'ambiente è connesso

Questa macchina virtuale è caricata con tutti gli strumenti per sviluppatori di cui avrai bisogno. Offre una home directory permanente da 5 GB e viene eseguita su Google Cloud, migliorando notevolmente le prestazioni e l'autenticazione della rete. Tutto il lavoro in questo codelab può essere svolto all'interno di un browser. Non devi installare nulla.

Inizializza l'ambiente

Apri Cloud Shell e imposta le variabili del progetto per assicurarti che tutti i comandi siano indirizzati all'infrastruttura corretta.

export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"

Checkpoint: riprendere o ricompilare?

Poiché si tratta della parte 2, l'agente ha bisogno dei dati controllati della parte 1 per funzionare. Scegli il tuo percorso:

Percorso A: ho appena terminato la parte 1 e le mie risorse sono ancora in esecuzione.

Bene. Vai alla directory di lavoro e sei pronto per procedere.

cd ~/devrel-demos/data-analytics/governance-context

Percorso B: ho saltato la parte 1 OPPURE ho eliminato le risorse (pulizia).

Nessun problema. Di seguito è riportato un blocco di comando "Fast-Track". In questo modo, il data lake BigQuery verrà ricreato automaticamente e i metadati di governance di Dataplex verranno applicati esattamente come nella Parte 1.

# 1. Clone the repo and navigate to the working directory
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

# 2. Rebuild the messy data lake with Terraform
cd terraform
terraform init
terraform apply -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

# 3. Generate and apply Dataplex Aspects (Governance rules)
cd ..
chmod +x ./generate_payloads.sh ./apply_governance.sh
./generate_payloads.sh
./apply_governance.sh

3. Scalabilità con MCP: creazione del piano di controllo dei dati

Finora hai testato correttamente la logica di governance utilizzando Gemini CLI. È un'ottima soluzione per la prototipazione rapida, ma viene eseguita localmente utilizzando le tue credenziali utente personali.

In un ambiente aziendale reale, è necessario un piano di controllo dei dati centralizzato. Per creare questo strumento, utilizzeremo GenAI Toolbox for Databases, un progetto open source ufficiale di Google. Questo toolkit fornisce un server MCP predefinito progettato specificamente per connettere in modo sicuro gli agenti AI ai database Google Cloud e ai servizi di metadati come Dataplex.

Eseguendo il deployment di questo toolbox come server MCP su Cloud Run, otteniamo:

  1. Identità centralizzata:l'agente viene eseguito come service account con limitazioni, non come il tuo account utente personale.
  2. Standardizzazione:qualsiasi client (ADK, Gemini, app personalizzate) può "collegarsi" a questo server utilizzando il protocollo MCP standard.
  3. Ambito controllato (privilegio minimo): non concediamo all'LLM un accesso illimitato a BigQuery. Forziamo la navigazione prima nel catalogo dei metadati di Dataplex.

Configurare la definizione dello strumento (tools.yaml)

La toolbox dell'AI generativa richiede un file di configurazione dichiarativo, tools.yaml. Questo file definisce sources (dove connettersi) e tools (cosa può fare l'AI).

  1. Vai alla directory del server e inserisci il tuo ID progetto nel file di configurazione:
cd ~/devrel-demos/data-analytics/governance-context/mcp_server
envsubst < tools.yaml > tools.tmp && mv tools.tmp tools.yaml
cat tools.yaml

Dovrebbe avere un aspetto identico al seguente snippet. Verifica che il campo del progetto ora corrisponda al tuo ID progetto Google Cloud effettivo.

sources:
  dataplex:
    kind: dataplex
    project: YOUR-PROJECT-ID

tools:
  search_entries:
    kind: dataplex-search-entries
    source: dataplex
    description: Search for entries in Dataplex Catalog.

  lookup_entry:
    kind: dataplex-lookup-entry
    source: dataplex
    description: Retrieve a specific entry from Dataplex Catalog.

  search_aspect_types:
    kind: dataplex-search-aspect-types
    source: dataplex
    description: Find aspect types relevant to a query.

toolsets:
  dataplex-toolset:
    - search_entries
    - lookup_entry
    - search_aspect_types

Definendo questi tre strumenti, possiamo forzare l'AI a essere "di sola lettura" e "governance-first".

Proteggere la configurazione (Secret Manager)

Nell'architettura aziendale, non devi mai incorporare i file di configurazione direttamente nelle immagini container. Archivieremo tools.yaml in modo sicuro in Google Cloud Secret Manager.

gcloud services enable secretmanager.googleapis.com
gcloud secrets create dataplex-tools-config --data-file=tools.yaml

Implementare il privilegio minimo (IAM)

Successivamente, creiamo un service account dedicato per il server MCP di GenAI Toolbox. Questa identità avrà solo le autorizzazioni esatte necessarie per leggere il catalogo Dataplex e accedere ai dati BigQuery.

export MCP_SA=mcp-sa
gcloud iam service-accounts create ${MCP_SA} \
    --display-name="Service Account for Dataplex MCP"
export MCP_SERVICE_ACCOUNT="${MCP_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

# Allow the server to read its own config from Secret Manager
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/secretmanager.secretAccessor"

# Allow the server to read Dataplex Metadata and BigQuery Data
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogViewer"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer"

Esegui il deployment del server MCP in Cloud Run

Ora eseguiamo il deployment della toolbox di AI generativa. Utilizziamo l'immagine container predefinita di Google (database-toolbox/toolbox) e montiamo la nostra configurazione da Secret Manager (--set-secrets) in fase di runtime.

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest

gcloud run deploy governance-mcp \
    --image=$IMAGE \
    --service-account $MCP_SERVICE_ACCOUNT \
    --region=$REGION \
    --no-allow-unauthenticated \
    --set-secrets="/app/tools.yaml=dataplex-tools-config:latest" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080"

Ora hai creato un'API controllata. Anziché concedere al frontend GenAI l'accesso diretto al database, si connetterà a questo URL Cloud Run. L'agente può vedere solo ciò che gli consente di vedere questa casella degli strumenti.

4. Crea il backend dell'agente con ADK

Hai creato un control plane dei dati (MCP) sicuro e controllato in esecuzione su Cloud Run. Ora l'agente AI ha bisogno di un framework per orchestrare la sua logica, ad esempio l'elaborazione degli input dell'utente, la decisione di quando chiamare il server MCP e la formattazione dell'output.

Anziché scrivere tutto questo codice boilerplate da zero, utilizzeremo Agent Development Kit (ADK) di Google. L'ADK è un framework code-first che esegue automaticamente il wrapping della logica dell'agente in un backend FastAPI. Inoltre, è dotato di un'interfaccia utente per sviluppatori integrata, che ti consente di visualizzare immediatamente il processo di ragionamento dell'agente e le chiamate agli strumenti senza dover prima creare un frontend personalizzato.

Esamina la logica dell'agente (agent.py)

Prima di configurare l'infrastruttura, diamo un'occhiata al cuore di questa applicazione.

Vai alla directory e visualizza i contenuti di agent.py. Questo file è il "cervello" del deployment dell'ADK.

cd ~/devrel-demos/data-analytics/governance-context/mcp_server
cat agent.py

Esamina la struttura del codice. Svolge tre funzioni fondamentali con un boilerplate minimo:

  1. Integrazione di MCPToolset:anziché scrivere client HTTP personalizzati per interagire con gli strumenti Dataplex, l'ADK utilizza MCPToolset(server_url=mcp_url). Recupera dinamicamente la definizione di tools.yaml dal server MCP di cui è stato eseguito il deployment e le traduce in chiamate di funzione native per l'LLM.
  2. Istruzioni di sistema:il parametro instructions contiene le regole di governance rigorose (la stessa logica utilizzata nella CLI GEMINI.md). Ordina esplicitamente al modello di eseguire il ciclo di ragionamento dalla fase 1 (ricerca dei metadati) alla fase 2 (query sui dati).
  3. Orchestrazione dell'agente:la classe Agent(...) lega insieme il modello Gemini, il prompt di sistema e gli strumenti MCP. Una volta eseguito il deployment, ADK converte automaticamente questo oggetto in un endpoint FastAPI scalabile.

Separazione dei compiti: configura l'identità del frontend

Per eseguire questo codice in modo sicuro, dobbiamo comunicare all'agente la posizione del server MCP. Costruiremo l'URL in modo dinamico e lo salveremo in un file .env che l'ADK leggerà in fase di runtime.

Creeremo anche un'identità separata (dataplex-agent-sa) per questa applicazione rivolta agli utenti. Questa separazione dei compiti garantisce che l'agente frontend abbia autorizzazioni diverse rispetto al server di governance backend.

Esegui questi comandi per configurare l'ambiente e l'identità:

export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export MCP_SERVER_URL=https://governance-mcp-${PROJECT_NUMBER}.${REGION}.run.app/mcp

export AGENT_SA=dataplex-agent-sa
export AGENT_SERVICE_ACCOUNT="${AGENT_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud iam service-accounts create ${AGENT_SA} \
    --display-name="Service Account for Dataplex Agent "

Configurare le variabili di runtime

Il framework ADK si basa su variabili di ambiente per comprendere il proprio contesto. Dobbiamo impostare esplicitamente l'ID progetto, la regione e abilitare l'utilizzo di Vertex AI. Li aggiungiamo allo stesso file .env.

echo MCP_SERVER_URL=$MCP_SERVER_URL > .env
echo GOOGLE_GENAI_USE_VERTEXAI=1 >> .env
echo GOOGLE_CLOUD_PROJECT=$PROJECT_ID >> .env
echo GOOGLE_CLOUD_LOCATION=$REGION >> .env

Concedi le autorizzazioni

Anche se l'agente delega i controlli di governance al server MCP, ha comunque bisogno di autorizzazioni di base per funzionare. Concediamo esattamente due ruoli:

  1. Utente Vertex AI:per richiamare il modello Gemini per generare risposte in linguaggio naturale.
  2. Cloud Run Invoker:per chiamare in modo sicuro l'API del server MCP. Non ottiene l'accesso diretto a BigQuery o Dataplex.
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

gcloud run services add-iam-policy-binding governance-mcp \
  --region=$REGION \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/run.invoker"

Esegui il deployment in Cloud Run

Infine, eseguiamo il deployment dello stack completo su Cloud Run.

Utilizziamo uvx per eseguire lo strumento ADK senza installare manualmente le dipendenze. Il comando riportato di seguito pacchettizza la logica di agent.py, crea un'immagine container, inserisce il tuo account di servizio e avvia un server FastAPI. Se aggiungi il flag --with_ui, viene incluso anche l'ADK Web Playground per il debug.

Questo comando crea il container e lo esegue il deployment. Il completamento dell'operazione può richiedere 1-3 minuti.

uvx --from google-adk \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=$REGION \
  --service_name=dataplex-agent \
  --with_ui \
  . \
  -- \
  --service-account=$AGENT_SERVICE_ACCOUNT \
  --allow-unauthenticated

Una volta completato questo comando, verrà restituito un URL del servizio (e.g., https://dataplex-agent-xyz.run.app). Fai clic su questo link per aprire l'interfaccia di chat con l'AI generativa completamente controllata.

12a5fa4c2aaf381f.png

Flusso architettonico end-to-end

Ora hai completato il sistema. Quando un utente interagisce con la UI dell'ADK, si verifica la seguente sequenza:

  1. L'utente invia un prompt nell'agente ADK (UI di sviluppo).
  2. L'agente ADK (agent.py) elabora l'input e chiama il modello Gemini.
  3. Gemini determina che ha bisogno di contesto e chiede al server MCP di eseguire gli strumenti Dataplex.
  4. Il server MCP applica le regole di governance di Dataplex e restituisce i metadati.
  5. Gemini sintetizza la risposta attendibile in base ai metadati e la restituisce all'utente.

5. Testare l'agente aziendale

Ora che l'agente è attivo, rivediamo gli scenari di governance testati in precedenza con la CLI. La logica rimane la stessa, ma ora interagisci con l'ADK Web Playground di cui è stato eseguito il deployment, che visualizza lo stato interno e le esecuzioni degli strumenti.

  1. Orchestrazione:l'agente ADK (in esecuzione su Cloud Run) riceve il testo.
  2. Routing degli strumenti:Gemini riconosce che la tua domanda richiede un contesto di dati e inoltra la richiesta al server MCP.
  3. Controllo della governance:il server MCP (in esecuzione su un'istanza Cloud Run separata) esegue query su Dataplex per tipi di aspetto specifici.
  4. Sintesi:i metadati pertinenti vengono restituiti a Gemini per generare la risposta finale.

Verifica la logica di governance

Apri l'URL del servizio generato nel passaggio precedente (e.g., https://dataplex-agent-xyz.run.app) nel browser. Incolla il seguente prompt:

"My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?"

Osserva il processo di ragionamento dell'agente nell'UI per sviluppatori:

  1. Riconoscimento dell'intento:l'agente analizza "in questo momento" e "non posso aspettare fino a domani".
  2. Ricerca metadati:chiama lo strumento MCP search_aspect_types. Cerca asset di dati in cui l'aspetto update_frequency è impostato su REALTIME o STREAMING, anziché su DAILY o MONTHLY.
  3. Selezione:indica che la tabella mkt_realtime_campaign_performance soddisfa questi criteri, mentre fin_monthly_closing_internal (nonostante sia di alta qualità) è troppo lenta per la tua richiesta.
  4. Risposta:l'agente consiglia la tabella in tempo reale.

e0da615724199e.png

Perché è importante:

Senza questi metadati di governance, un LLM probabilmente consiglierebbe la tabella fin_monthly_closing_internal semplicemente perché ha una colonna denominata "ad_spend", ignorando il fatto che i dati hanno 24 ore. Il contesto dei metadati ha impedito un errore aziendale.

Puoi anche testare il prompt "Riunione del consiglio di amministrazione" per vedere come l'agente passa a tabelle diverse in base all'aspetto Livello del prodotto di dati:

"We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?"

6. Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo codelab, segui questi passaggi per eliminare tutta l'infrastruttura creata nella parte 1 e nella parte 2.

Elimina il data lake (Terraform)

Utilizza Terraform per eliminare le tabelle, i set di dati e le definizioni di aspetti Dataplex di BigQuery.

cd ~/devrel-demos/data-analytics/governance-context/terraform
terraform destroy -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

Elimina i servizi Cloud Run

Rimuovi le risorse di calcolo per interrompere la fatturazione attiva per i container in esecuzione.

gcloud run services delete governance-mcp --region=$REGION --quiet
gcloud run services delete dataplex-agent --region=$REGION --quiet

Pulire gli artefatti di build e l'archiviazione di staging

Quando hai eseguito il deployment dell'agente ADK utilizzando uvx, il sistema ha creato automaticamente un'immagine container e ha caricato il codice sorgente in un bucket Cloud Storage temporaneo. Questi artefatti vengono mantenuti anche dopo l'eliminazione del servizio Cloud Run e comportano costi di archiviazione continui.

Rimuovi il repository Artifact Registry e il bucket temporaneo Cloud Storage:

# Delete the repository used for the agent build
gcloud artifacts repositories delete cloud-run-source-deploy \
    --location=$REGION \
    --quiet

# Delete the staging bucket created by Cloud Run source deploy
gcloud storage rm --recursive gs://run-sources-${PROJECT_ID}-${REGION}

Eliminare l'identità, le autorizzazioni e i segreti

Rimuovi prima le associazioni di policy IAM per evitare che nella pagina IAM del progetto rimangano voci "tombstone" (record orfani). Poi, elimina i service account e i secret di configurazione.

# Remove IAM roles granted to the MCP Service Account
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/secretmanager.secretAccessor" --quiet
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogViewer" --quiet
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer" --quiet

# Remove IAM roles granted to the Agent Service Account
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" --quiet

# Delete the Service Accounts
gcloud iam service-accounts delete $MCP_SERVICE_ACCOUNT --quiet
gcloud iam service-accounts delete $AGENT_SERVICE_ACCOUNT --quiet

# Delete the Secret Manager entry
gcloud secrets delete dataplex-tools-config --quiet

Rimuovere la configurazione locale

Infine, pulisci i file di configurazione locali e le variabili di ambiente in Cloud Shell.

# Uninstall the Gemini CLI extension (installed in Part 1)
gemini extensions uninstall dataplex

# Remove local repository files and unset variables
cd ~
rm -rf ~/devrel-demos
unset MCP_SERVER_URL
unset MCP_SERVICE_ACCOUNT
unset AGENT_SERVICE_ACCOUNT

7. Complimenti!

Hai eseguito il deployment di un agente GenAI end-to-end e consapevole della governance.

In questo codelab in due parti, hai superato la semplice ingegneria dei prompt per implementare un'architettura solida e pronta per la produzione. Trattando la governance dei dati come prerequisito per l'AI generativa, hai stabilito un metodo sistematico per impedire al modello di recuperare dati non certificati o inventati.

Concetti chiave

  • AI deterministica tramite metadati:anziché fare affidamento sul LLM per indovinare la tabella corretta in base ai nomi delle colonne, hai applicato un ciclo di ragionamento rigoroso utilizzando GenAI Toolbox for Databases. Esposizione esplicita di soli tre strumenti Dataplex (search_aspect_types, search_entries, lookup_entry) per forzare il modello a verificare le certificazioni dei dati prima di sintetizzare le risposte.
  • Architettura disaccoppiata (MCP): con il deployment del server Model Context Protocol (MCP) su Cloud Run, hai estratto le regole di governance dei dati in un'API centralizzata e standardizzata. L'agente frontend non deve contenere la logica del database, ma solo comunicare tramite lo standard MCP. Ciò significa che puoi collegare qualsiasi modello o client di AI futuro allo stesso backend controllato.
  • Separazione dei compiti:hai applicato il principio del privilegio minimo isolando le identità IAM. L'agente ADK rivolto agli utenti opera con autorizzazioni limitate all'invocazione del modello e al routing API, mentre il server MCP di backend gestisce in modo sicuro le query del catalogo Dataplex e il recupero dei dati BigQuery.
  • Orchestrazione degli agenti con approccio code-first: hai utilizzato Google Agent Development Kit (ADK) per integrare immediatamente la logica dell'agente Python in un backend FastAPI scalabile, utilizzando la sua UI per sviluppatori integrata per visualizzare ed eseguire il debug delle esecuzioni degli strumenti interni dell'agente.

Passaggi successivi