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 AI conforme alla governance.

(Puoi leggere la prima parte di questa serie, che spiega come stabilire le basi dei dati registrando un tipo di aspetto di Knowledge Catalog, applicando gli aspetti alle tabelle BigQuery e testando le regole localmente tramite l'interfaccia a riga di comando AGY. 👉 Leggi la parte 1)

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

In questa seconda parte, risolverai queste sfide e passerai alla produzione. Anziché eseguire il deployment di un server MCP personalizzato, collegherai l'agente direttamente al server MCP di Knowledge Catalog gestito da Google. Poi, utilizzerai Agent Development Kit (ADK) di Google per creare l'applicazione dell'agente, caricare le regole di governance dalla skill dell'agente locale ed eseguirne il deployment in Cloud Run, con un'interfaccia utente web professionale

.

Quando un utente interagisce con l'interfaccia utente ADK, si verifica la seguente sequenza:

8912d1983c34ee8e.png

Obiettivi didattici

  • Come utilizzare Model Context Protocol (MCP) per standardizzare il modo in cui gli agenti AI interagiscono con i dati di Google Cloud.
  • Come l'agente ADK si connette al server MCP di Knowledge Catalog gestito da Google.
  • Come caricare dinamicamente le regole di governance dalla skill dell'agente condivisa.
  • Come eseguire il deployment dell'agente in Cloud Run ed eseguire il playground web integrato di ADK.

Che cosa ti serve

  • Un progetto Google Cloud con la fatturazione abilitata.
  • Accesso a Google Cloud Shell.
  • Conoscenza di base di Cloud Run, account di servizio IAM e Python.
  • I set di dati BigQuery e gli aspetti di Knowledge Catalog creati nella parte 1. (Non preoccuparti se li hai eliminati, di seguito forniamo uno script rapido per ricrearli.)

Concetti fondamentali

  • Model Context Protocol (MCP): considera MCP come un "cavo USB-C universale" per gli agenti AI. Invece di scrivere codice di integrazione API personalizzato per ogni singolo modello AI, MCP fornisce un modo standard per l'AI di connettersi in modo sicuro agli strumenti di dati aziendali (come Knowledge Catalog e BigQuery).
  • Agent Development Kit (ADK): un framework open source flessibile di Google progettato per semplificare lo sviluppo end-to-end degli agenti AI. Applica i principi di 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.
  • Gemini Enterprise Agent Platform(GEAP): l'ambiente di hosting e orchestrazione di livello enterprise per il deployment di agenti AI su Google Cloud.

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 qualcosa di simile a questo:

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

Questa macchina virtuale viene fornita con tutti gli strumenti per sviluppatori di cui avrai bisogno. Offre una home directory permanente da 5 GB e viene eseguita in 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 destinati all'infrastruttura corretta.

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

Abilita le API richieste

Abilita il set minimo di API Google Cloud necessarie per gestire le basi dei dati, eseguire i modelli Vertex AI e ospitare l'agente ADK in Cloud Run.

gcloud services enable \
    dataplex.googleapis.com \
    bigquery.googleapis.com \
    aiplatform.googleapis.com \
    run.googleapis.com \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com

Punto di controllo: riprendere o ricreare?

Poiché questa è la parte 2, l'agente ha bisogno dei dati gestiti della parte 1 per funzionare. Scegli il 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 continuare.

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

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

Nessun problema. Di seguito è riportato un blocco di comandi "Fast-Track". Ricreerà automaticamente il data lake BigQuery, registrerà il tipo di aspetto e applicherà i metadati di governance esattamente come abbiamo fatto 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 BigQuery datasets and tables
chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

# 3. Register the Knowledge Catalog aspect type
gcloud dataplex aspect-types create official-data-product-spec \
    --location="${REGION}" \
    --project="${PROJECT_ID}" \
    --metadata-template-file-name="aspect_template.json"

# 4. Generate and apply aspects (governance rules)
chmod +x ./generate_payloads.sh ./apply_governance.sh
./generate_payloads.sh
./apply_governance.sh

3. Il piano di controllo dei dati centralizzato (MCP gestito)

In un ambiente aziendale reale, hai bisogno di un piano di controllo dei dati sicuro e centralizzato. Anziché creare ed eseguire il deployment di un contenitore del server MCP personalizzato in Cloud Run, collegheremo il nostro agente direttamente al server MCP di Knowledge Catalog gestito da Google.

Utilizzando questo endpoint gestito, otteniamo:

  1. Nessuna manutenzione: non è necessario gestire container, scalabilità o applicazione di patch per il server MCP.
  2. Standardizzazione: l'agente si connette a un endpoint API Google standard e sicuro utilizzando Model Context Protocol (trasporto SSE).
  3. Ambito controllato: il server MCP espone solo gli strumenti di metadati necessari (search_entries, lookup_context, lookup_entry), applicando un loop di ragionamento di sola lettura e basato sulla governance.

Il server MCP di Knowledge Catalog gestito da Google è accessibile tramite il seguente URL sicuro:

https://dataplex.googleapis.com/mcp

Poiché si tratta di un'API Google proprietaria, l'agente deve eseguire l'autenticazione utilizzando un token di accesso OAuth2 standard di Google Cloud anziché un token ID. Gestiremo automaticamente questa autenticazione nel codice dell'applicazione.

4. Crea il backend dell'agente con ADK

Hai un piano di controllo dei dati sicuro e gestito. 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.

Utilizzeremo Agent Development Kit (ADK) di Google. ADK è un framework code-first che esegue automaticamente il wrapping della logica dell'agente in un backend FastAPI e fornisce un'interfaccia web integrata per i test immediati.

Apri il codice dell'agente nell'editor di Cloud Shell

Anziché scaricare l'intero file nel terminale, apriamolo nell'editor di Cloud Shell in modo che tu possa ispezionare, modificare e comprendere facilmente il codice.

Esegui il comando riportato di seguito nel terminale ed esamina la struttura del codice nell'editor. L'applicazione è creata utilizzando Agent Development Kit (ADK) di Google:

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

# Copy the governance skill directory inside the application bundle so it packages during Cloud Run deployment
mkdir -p skills
cp -r ../.agents/skills/knowledge-catalog-governance skills/

cloudshell edit agent.py

(Nota: agent.py contiene codice boilerplate nella parte superiore per gestire l'autenticazione OAuth2 di Google Cloud e l'aggiornamento dei token, garantendo che l'agente possa comunicare in modo sicuro con l'API di Knowledge Catalog gestita da Google).

1. Caricamento delle skill native

Per creare un agente altamente ottimizzato, carichiamo le istruzioni di governance dalla directory delle skill dell'agente esterno utilizzando load_skill_from_dir nativo di ADK. Questo approccio consente la divulgazione progressiva:

  • Metadati L1: l'agente carica solo il nome e la descrizione della skill all'avvio. Questo contesto minimo consente all'LLM di identificare quando utilizzare la skill senza consumare grandi quantità di token in anticipo.
  • Istruzioni L2: il set completo di istruzioni all'interno di SKILL.md viene recuperato dinamicamente in fase di runtime solo quando il modello determina che è pertinente.
base_dir = Path(__file__).parent
governance_skill = load_skill_from_dir(
    base_dir / "skills" / "knowledge-catalog-governance"
)

# Bundle the skill and MCP tools together into a SkillToolset
governance_skill_toolset = skill_toolset.SkillToolset(
    skills=[governance_skill],
    additional_tools=[tools]
)

2. Orchestrazione dell'agente

ADK ti consente di orchestrare comportamenti complessi degli agenti concatenando più agenti. Definiamo un flusso di lavoro SequentialAgent composto da due agenti specializzati:

  • governance_researcher: dotato di governance_skill_toolset e degli tools MCP di Knowledge Catalog. Verifica se la query rientra nell'ambito del catalogo dati e della conformità, quindi esegue query su Knowledge Catalog utilizzando le variabili di ambiente inserite nelle istruzioni di sistema.
  • compliance_formatter: responsabile della traduzione dei risultati di ricerca dei metadati JSON non elaborati in una risposta pulita o della spiegazione dei limiti dell'ambito se la richiesta è fuori ambito.
# 1. Researcher Agent (has access to the encapsulated SkillToolset)
governance_researcher = LlmAgent(
    name="governance_researcher",
    model=model_name,
    description="Dynamically interprets metadata schema (Booleans/Enums) and searches for assets using strict syntax.",
    instruction=f"""
    You are a governance researcher. Your job is to verify Knowledge Catalog metadata rules and find compliant assets for the user's query.
    
    YOUR ACTIVE ENVIRONMENT CONTEXT:
    - Google Cloud Project ID: {project_id}
    - Location (Region): {location}

    YOUR WORKFLOW:
    1. First, check if the user query is related to data analytics assets, database tables, or data compliance.
       - If YES: Call `load_skill` with `name="knowledge-catalog-governance"` to load the rules, then use search/lookup tools to locate a certified compliant table.
       - If NO (e.g., general chit-chat, unrelated tasks): Skip skill loading and output a JSON object indicating it is out of scope:
         {"error": "out_of_scope", "message": "The query does not pertain to data catalog search or governance compliance."}
    2. Populate the required projectId and location parameters in tool calls with the active environment parameters.
    3. Return the verified table's metadata in JSON format as your final research output.
    """,
    tools=[governance_skill_toolset, tools],
    output_key="research_data"
)

# 2. Formatter Agent (formats the output or explains out-of-scope errors)
compliance_formatter = LlmAgent(
    name="compliance_formatter",
    model=model_name,
    description="Formats the JSON research data into a helpful response for the user.",
    instruction="""
    You are the **Intelligent Data Governance Specialist**.
    Your job is to explain the findings of the governance research clearly to the user.

    **YOUR GOAL:**
    1. If the researcher found a matching table (valid JSON with table metadata):
       - Explain the logical connection between the User's Request, the Governance Schema (translated criteria), and the Recommended Table.
       - Use the following RESPONSE TEMPLATE:
         - **Analysis:** "I analyzed the metadata schema and translated your request into the following technical criteria:..."
         - **Recommendation:** "Based on this, I recommend the following table:"
           - **Table:** [Insert Table Name]
           - **Description:** [Insert Table Description]
         - **Verification:** "This asset is a verified match because: [Explain the verification details]."
    2. If the researcher returned an 'out_of_scope' error or no matching tables were found:
       - Apologize politely and explain that no data asset currently matches the strict governance criteria defined in `official-data-product-spec`.
       - Clearly state what domain of questions this agent is certified to answer (e.g., Data Catalog Search and Data Governance compliance).
    """
)

# 3. Orchestrated Workflow (Exported as root_agent)
root_agent = SequentialAgent(
    name="governance_workflow",
    description="Workflow to learn metadata rules, search with strict syntax, and recommend assets.",
    sub_agents=[
        governance_researcher,
        compliance_formatter,
    ]
)

Configura le variabili di runtime

Per eseguire l'agente, dobbiamo indicare dove si trova il server MCP gestito e configurare il progetto e la regione. Salveremo queste variabili in un file .env che ADK leggerà in fase di runtime.

Esegui il comando seguente per generare il file .env. Tieni presente che MCP_SERVER_URL punta direttamente all'endpoint API di Knowledge Catalog gestito da Google:

export MCP_SERVER_URL="https://dataplex.googleapis.com/mcp"

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

5. Esegui e testa l'agente in locale

Prima di eseguire il deployment dell'agente nel cloud, devi eseguirlo localmente in Cloud Shell per verificarne il comportamento. Poiché l'agente dipende da diversi pacchetti Python (incluse le librerie Google Cloud Logging e ADK), configureremo un ambiente virtuale locale per installare queste dipendenze.

Quando viene eseguito localmente in Cloud Shell, l'agente utilizza automaticamente le credenziali utente di Google Cloud attive, quindi dispone già delle autorizzazioni necessarie per accedere a Vertex AI e Knowledge Catalog.

  1. Vai alla directory mcp_server, crea un ambiente virtuale e installa le dipendenze:
cd ~/devrel-demos/data-analytics/governance-context/mcp_server

# Create a virtual environment using uv
uv venv
source .venv/bin/activate

# Install the dependencies listed in requirements.txt
uv pip install -r requirements.txt
  1. Avvia la sessione di chat interattiva nel terminale:
adk run .
  1. Una volta avviata la sessione, vedrai un prompt. Digita una query per testare la logica di governance dell'agente:
I need the Q1 revenue summary for our internal board meeting.

L'agente elaborerà la richiesta, eseguirà query su Knowledge Catalog tramite il server MCP gestito e genererà la raccomandazione e il ragionamento direttamente nel terminale.

  1. Per uscire dalla sessione interattiva, digita exit o quit (oppure premi Ctrl+C). Dopo aver chiuso, puoi disattivare l'ambiente virtuale:
deactivate

6. Esegui il deployment dell'agente in produzione

Ora che hai verificato l'agente localmente, puoi eseguirne il deployment in Google Cloud per l'utilizzo in produzione.

Crea un account di servizio

Per motivi di sicurezza, l'agente di cui è stato eseguito il deployment non deve essere eseguito con le tue credenziali personali. Creeremo un'identità separata (knowledge-catalog-agent-sa) per l'agente, rispettando il principio del privilegio minimo.

Esegui i seguenti comandi per creare il service account:

export AGENT_SA=knowledge-catalog-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 Knowledge Catalog Agent"

Concedi le autorizzazioni

Anche se l'agente delega i controlli di governance al server MCP, ha comunque bisogno delle autorizzazioni di base per funzionare.

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogAdmin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/mcp.toolUser"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/viewer"

Esegui il deployment in Cloud Run

Infine, eseguiamo il deployment dell'agente in Cloud Run. Il comando seguente crea l'immagine container utilizzando il Dockerfile nella directory corrente, la carica in Artifact Registry ed esegue il deployment in Cloud Run. Il completamento potrebbe richiedere 1-3 minuti.

gcloud run deploy knowledge-catalog-agent \
  --source . \
  --project=$PROJECT_ID \
  --region=$REGION \
  --service-account=$AGENT_SERVICE_ACCOUNT \
  --allow-unauthenticated \
  --clear-base-image \
  --labels created-by=adk

Al termine del comando, verrà generato un URL del servizio (ad es. https://knowledge-catalog-agent-xyz.run.app). Fai clic su questo link per aprire l'interfaccia di chat GenAI completamente gestita.

12a5fa4c2aaf381f.png

7. Testa l'agente live

Ora che l'agente è attivo, testiamo gli scenari di governance. La logica rimane la stessa, ma ora stai interagendo con il playground web ADK di cui è stato eseguito il deployment, che visualizza lo stato interno e le esecuzioni degli strumenti.

Apri l'URL del servizio generato nel passaggio precedente (ad es. https://knowledge-catalog-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'interfaccia utente per sviluppatori:

  1. Riconoscimento dell'intent: l'agente analizza "in questo momento" e "non vedo l'ora che arrivi la notte".
  2. Ricerca dei metadati: chiama lo strumento MCP search_entries con la query: [PROJECT_ID].us-central1.official-data-product-spec.update_frequency=REALTIME_STREAMING
  3. Selezione: identifica che la tabella mkt_realtime_campaign_performance soddisfa questi criteri.
  4. Risposta: l'agente consiglia la tabella in tempo reale.

e0da615724199e.png

Perché è importante:

Senza questi metadati di governance, un LLM consiglierebbe probabilmente 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 del livello del prodotto 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?"

8. Libera spazio

Per evitare che al tuo account Google Cloud vengano addebitati costi, segui questi passaggi per eliminare tutta l'infrastruttura creata in questo codelab.

Elimina il data lake

Utilizza lo script di pulizia per eliminare le tabelle BigQuery, i set di dati e le definizioni degli aspetti di Knowledge Catalog.

cd ~/devrel-demos/data-analytics/governance-context
chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh

Elimina i servizi Cloud Run

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

gcloud run services delete knowledge-catalog-agent --region=$REGION --quiet

Libera spazio dagli artefatti di build e dall'archiviazione di gestione temporanea

Quando hai eseguito il deployment dell'agente ADK, il sistema ha creato automaticamente un'immagine container e ha caricato il codice sorgente in un bucket Cloud Storage temporaneo.

Rimuovi il repository Artifact Registry e il bucket di gestione temporanea di 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}

Elimina identità e autorizzazioni

Rimuovi prima i binding dei criteri IAM, poi elimina i service account.

# 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

gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogViewer" --quiet

gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/mcp.toolUser" --quiet

gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer" --quiet

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

Rimuovi la configurazione locale

Infine, libera spazio nei file di configurazione locali e nelle variabili di ambiente in Cloud Shell.

# Uninstall the AGY CLI plugin
agy plugin uninstall dataplex

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

9. Complimenti!

Hai eseguito il deployment di un agente GenAI end-to-end conforme alla governance.

In questo codelab in due parti, hai superato la semplice progettazione dei prompt per implementare un'architettura robusta e pronta per la produzione. Trattando la governance dei dati come prerequisito per GenAI, hai stabilito un metodo sistematico per impedire al modello di recuperare dati non certificati o generati da allucinazioni.

Concetti principali

  • AI deterministica tramite i metadati: anziché fare affidamento sull'LLM per indovinare la tabella corretta in base ai nomi delle colonne, hai applicato un loop di ragionamento rigoroso utilizzando il server MCP di Knowledge Catalog gestito da Google, forzando il modello a verificare le certificazioni dei dati prima di consigliare le tabelle.
  • Architettura disaccoppiata: 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 AI futuro allo stesso backend gestito.
  • Separazione dei compiti: hai applicato il principio del privilegio minimo isolando le identità IAM. L'agente ADK rivolto agli utenti opera con autorizzazioni limitate alla chiamata del modello e al routing API.
  • Orchestrazione degli agenti code-first: hai utilizzato Google Agent Development Kit (ADK) per eseguire immediatamente il wrapping della logica dell'agente Python in un backend FastAPI scalabile, utilizzando l'interfaccia utente per sviluppatori integrata per visualizzare ed eseguire il debug delle esecuzioni degli strumenti interni dell'agente.

Passaggi successivi