Déployer un agent compatible avec la gouvernance d'entreprise avec MCP et Cloud Run

1. Introduction

Cet atelier de programmation fait partie d'une série en deux parties qui explique comment créer un agent d'IA tenant compte de la gouvernance.

(Vous pouvez lire la première partie de cette série, qui explique comment établir la base de données en enregistrant un type d'aspect du Knowledge Catalog, en appliquant des aspects aux tables BigQuery et en testant les règles localement via l'interface de ligne de commande AGY. 👉 Lire la partie 1

Toutefois, les tests dans une CLI locale ne sont qu'un début. Pour déployer cette solution dans toute votre entreprise, vous avez besoin d'une sécurité centralisée, de connexions standardisées aux outils d'IA et d'un framework d'application approprié pour orchestrer la logique de l'agent et fournir une interface de chat familière.

Dans cette deuxième partie, vous allez résoudre ces problèmes et passer à la production. Au lieu de déployer un serveur MCP personnalisé, vous connecterez votre agent directement au serveur MCP Knowledge Catalog géré par Google. Vous utiliserez ensuite le kit de développement d'agents (ADK) de Google pour créer l'application d'agent proprement dite, charger vos règles de gouvernance à partir de votre compétence d'agent local et la déployer sur Cloud Run, avec une UI Web professionnelle.

.

Lorsqu'un utilisateur interagit avec l'UI de l'ADK, la séquence suivante se produit :

8912d1983c34ee8e.png

Points abordés

  • Découvrez comment utiliser le protocole MCP (Model Context Protocol) pour standardiser la façon dont les agents d'IA interagissent avec les données Google Cloud.
  • Comment l'agent ADK se connecte au serveur MCP du Knowledge Catalog géré par Google.
  • Comment charger vos règles de gouvernance de manière dynamique à partir de la compétence d'agent partagée.
  • Découvrez comment déployer votre agent sur Cloud Run et exécuter le playground Web intégré d'ADK.

Prérequis

  • Un projet Google Cloud avec facturation activée.
  • un accès à Google Cloud Shell ;
  • Connaissances de base de Cloud Run, des comptes de service IAM et de Python.
  • Les ensembles de données BigQuery et les aspects Knowledge Catalog créés dans la partie 1. (Ne vous inquiétez pas si vous les avez supprimés. Nous vous fournissons un script ci-dessous pour les recréer rapidement.)

Concepts clés

  • MCP (Model Context Protocol) : considérez le protocole MCP comme un "câble USB-C universel" pour les agents d'IA. Au lieu d'écrire du code d'intégration d'API personnalisé pour chaque modèle d'IA, MCP fournit une méthode standard permettant à l'IA de se connecter de manière sécurisée à vos outils de données d'entreprise (comme Knowledge Catalog et BigQuery).
  • Agent Development Kit (ADK) : framework Open Source flexible de Google conçu pour simplifier le développement de bout en bout des agents d'IA. Il applique les principes de l'ingénierie logicielle à la création d'agents, ce qui vous permet d'orchestrer des outils complexes, de gérer l'état et de lancer facilement une interface utilisateur de développement intégrée pour les tests et le déploiement.
  • Gemini Enterprise Agent Platform(GEAP) : environnement d'hébergement et d'orchestration de niveau entreprise pour déployer des agents d'IA sur Google Cloud.

2. Préparation

Démarrer Cloud Shell

Bien que Google Cloud puisse être utilisé à distance depuis votre ordinateur portable, nous allons nous servir de Google Cloud Shell pour cet atelier de programmation, un environnement de ligne de commande exécuté dans le cloud.

Dans la console Google Cloud, cliquez sur l'icône Cloud Shell dans la barre d'outils supérieure :

Activer Cloud Shell

Le provisionnement et la connexion à l'environnement prennent quelques instants seulement. Une fois l'opération terminée, le résultat devrait ressembler à ceci :

Capture d'écran du terminal Google Cloud Shell montrant que l'environnement est connecté

Cette machine virtuelle contient tous les outils de développement nécessaires. Elle comprend un répertoire d'accueil persistant de 5 Go et s'exécute sur Google Cloud, ce qui améliore nettement les performances du réseau et l'authentification. Vous pouvez effectuer toutes les tâches de cet atelier de programmation dans un navigateur. Vous n'avez rien à installer.

Initialiser l'environnement

Ouvrez Cloud Shell et définissez les variables de votre projet pour vous assurer que toutes les commandes ciblent la bonne infrastructure.

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

Activer les API requises

Activez l'ensemble minimal d'API Google Cloud requises pour gérer votre base de données, exécuter des modèles Vertex AI et héberger l'agent ADK sur Cloud Run.

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

Point de contrôle : reprendre ou reconstruire ?

Comme il s'agit de la partie 2, votre agent a besoin des données régies de la partie 1 pour fonctionner. Veuillez choisir votre option :

Parcours A : Je viens de terminer la partie 1 et mes ressources sont toujours en cours d'exécution

Parfait ! Accédez au répertoire de travail. Vous êtes prêt à continuer.

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

Parcours B : J'ai ignoré la partie 1 OU j'ai supprimé mes ressources (nettoyage)

Aucun problème. Vous trouverez ci-dessous un bloc de commandes "Fast-Track". Cela reconstruira automatiquement le lac de données BigQuery, enregistrera le type d'aspect et appliquera les métadonnées de gouvernance exactement comme nous l'avons fait dans la partie 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. Plan de contrôle des données centralisé (MCP géré)

Dans un véritable environnement d'entreprise, vous avez besoin d'un plan de contrôle des données sécurisé et centralisé. Au lieu de créer et de déployer un conteneur serveur MCP personnalisé sur Cloud Run, nous allons connecter notre agent directement au serveur MCP Knowledge Catalog géré par Google.

En utilisant ce point de terminaison géré, nous obtenons les avantages suivants :

  1. Aucune maintenance : vous n'avez pas besoin de gérer les conteneurs, le scaling ni les correctifs pour le serveur MCP.
  2. Normalisation : l'agent se connecte à un point de terminaison de l'API Google standard et sécurisé à l'aide du Model Context Protocol (transport SSE).
  3. Champ d'application contrôlé : le serveur MCP n'expose que les outils de métadonnées nécessaires (search_entries, lookup_context, lookup_entry), ce qui permet d'appliquer une boucle de raisonnement axée sur la gouvernance et en lecture seule.

Le serveur MCP du Knowledge Catalog géré par Google est accessible via l’URL sécurisée suivante :

https://dataplex.googleapis.com/mcp

Comme il s'agit d'une API Google propriétaire, l'agent doit s'authentifier à l'aide d'un jeton d'accès OAuth2 Google Cloud standard plutôt que d'un jeton d'identité. Nous gérerons cette authentification automatiquement dans le code de notre application.

4. Créer le backend de l'agent avec ADK

Vous disposez d'un plan de contrôle des données sécurisé et géré. Votre agent d'IA a maintenant besoin d'un framework pour orchestrer sa logique, comme le traitement des entrées utilisateur, la décision du moment où appeler le serveur MCP et la mise en forme de la sortie.

Nous allons utiliser l'Agent Development Kit (ADK) de Google. L'ADK est un framework axé sur le code qui encapsule automatiquement la logique de votre agent dans un backend FastAPI et fournit une interface Web intégrée pour des tests instantanés.

Ouvrir le code de l'agent dans l'éditeur Cloud Shell

Plutôt que de vider l'intégralité du fichier dans le terminal, ouvrez-le dans l'éditeur Cloud Shell pour pouvoir inspecter, modifier et comprendre facilement le code.

Exécutez la commande ci-dessous dans le terminal et examinez la structure du code dans l'éditeur. L'application est conçue à l'aide de l'Agent Development Kit (ADK) de 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

(Remarque : agent.py contient du code récurrent en haut pour gérer l'authentification Google Cloud OAuth2 et l'actualisation des jetons, ce qui permet à l'agent de communiquer de manière sécurisée avec l'API Knowledge Catalog gérée par Google).

1. Chargement des compétences natives

Pour créer un agent hautement optimisé, nous chargeons les instructions de gouvernance à partir du répertoire de compétences de l'agent externe à l'aide de load_skill_from_dir natif d'ADK. Cette approche permet la divulgation progressive :

  • Métadonnées de niveau 1 : l'agent ne charge que le nom et la description de la compétence au démarrage. Ce contexte minimal permet au LLM d'identifier quand utiliser la compétence sans consommer de grandes quantités de jetons à l'avance.
  • Instructions de niveau 2 : l'ensemble complet d'instructions dans SKILL.md n'est récupéré de manière dynamique au moment de l'exécution que lorsque le modèle le juge pertinent.
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. Orchestration des agents

L'ADK vous permet d'orchestrer des comportements d'agent complexes en enchaînant plusieurs agents. Nous définissons un workflow SequentialAgent composé de deux agents spécialisés :

  • governance_researcher: Équipé de governance_skill_toolset et du MCP Knowledge Catalog tools. Il vérifie si la requête relève du catalogue de données et du champ d'application de la conformité, puis interroge Knowledge Catalog à l'aide de variables d'environnement injectées dans ses instructions système.
  • compliance_formatter: Responsable de la traduction des résultats de recherche de métadonnées JSON brutes en une réponse claire, ou de l'explication des limites du champ d'application si la demande est hors champ.
# 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,
    ]
)

Configurer les variables d'exécution

Pour exécuter l'agent, nous devons lui indiquer où se trouve votre serveur MCP géré et configurer son projet et sa région. Nous enregistrerons ces variables dans un fichier .env que l'ADK lira au moment de l'exécution.

Exécutez la commande suivante pour générer le fichier .env. Notez que MCP_SERVER_URL pointe directement vers le point de terminaison de l'API Knowledge Catalog gérée par 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. Exécuter et tester l'agent localement

Avant de déployer votre agent dans le cloud, vous devez l'exécuter en local dans Cloud Shell pour vérifier son comportement. Étant donné que l'agent dépend de plusieurs packages Python (y compris les bibliothèques Google Cloud Logging et ADK), nous allons configurer un environnement virtuel local pour installer ces dépendances.

Lorsqu'il s'exécute en local dans Cloud Shell, l'agent utilise automatiquement vos identifiants utilisateur Google Cloud actifs. Il dispose donc déjà des autorisations nécessaires pour accéder à Vertex AI et à Knowledge Catalog.

  1. Accédez au répertoire mcp_server, créez un environnement virtuel et installez les dépendances :
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. Démarrez la session de chat interactive dans votre terminal :
adk run .
  1. Une fois la session lancée, une invite s'affiche. Saisissez une requête pour tester la logique de gouvernance de l'agent :
I need the Q1 revenue summary for our internal board meeting.

L'agent traitera votre demande, interrogera le catalogue de connaissances via le serveur MCP géré et affichera sa recommandation et son raisonnement directement dans le terminal.

  1. Pour quitter la session interactive, saisissez exit ou quit (ou appuyez sur Ctrl+C). Une fois la session terminée, vous pouvez désactiver l'environnement virtuel :
deactivate

6. Déployer l'agent en production

Maintenant que vous avez vérifié l'agent en local, vous êtes prêt à le déployer sur Google Cloud pour l'utiliser en production.

Créer un compte de service

Pour des raisons de sécurité, l'agent déployé ne doit pas s'exécuter avec vos identifiants personnels. Nous allons créer une identité distincte (knowledge-catalog-agent-sa) pour l'agent, en respectant le principe du moindre privilège.

Exécutez les commandes suivantes pour créer le compte de service :

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"

Accorder des autorisations

Même si l'agent délègue les vérifications de gouvernance au serveur MCP, il a toujours besoin d'autorisations de base pour fonctionner.

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"

Déployer dans Cloud Run

Enfin, nous déployons l'agent sur Cloud Run. La commande suivante crée l'image de conteneur à l'aide du fichier Dockerfile dans votre répertoire actuel, l'importe dans Artifact Registry et la déploie dans Cloud Run. Cette opération peut prendre entre une et trois minutes.

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

Une fois cette commande exécutée, une URL du service (par exemple, https://knowledge-catalog-agent-xyz.run.app) s'affiche. Cliquez sur ce lien pour ouvrir votre interface de chat d'IA générative entièrement régie.

12a5fa4c2aaf381f.png

7. Tester l'agent Live

Maintenant que votre agent est actif, testons les scénarios de gouvernance. La logique reste la même, mais vous interagissez désormais avec l'ADK Web Playground déployé, qui visualise l'état interne et les exécutions d'outils.

Ouvrez l'URL du service que vous avez générée à l'étape précédente (par exemple, https://knowledge-catalog-agent-xyz.run.app) dans votre navigateur. Collez le prompt suivant :

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

Observez le processus de raisonnement de l'agent dans l'UI du développeur :

  1. Reconnaissance de l'intention : l'agent analyse les expressions "tout de suite" et "ne peut pas attendre la nuit".
  2. Recherche de métadonnées : l'outil MCP search_entries est appelé avec la requête [PROJECT_ID].us-central1.official-data-product-spec.update_frequency=REALTIME_STREAMING.
  3. Sélection : indique que le tableau mkt_realtime_campaign_performance répond à ces critères.
  4. Réponse : l'agent recommande le tableau en temps réel.

e0da615724199e.png

Pourquoi est-ce important ?

Sans ces métadonnées de gouvernance, un LLM recommanderait probablement la table fin_monthly_closing_internal simplement parce qu'elle comporte une colonne nommée "ad_spend", en ignorant le fait que les données datent de 24 heures. Le contexte de vos métadonnées a empêché une erreur métier.

Vous pouvez également tester la requête "Board Meeting" (Réunion du conseil d'administration) pour voir comment l'agent passe à différentes tables en fonction de l'aspect "Niveau du produit de données" :

"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. Effectuer un nettoyage

Pour éviter que l'infrastructure créée dans cet atelier de programmation soit facturée sur votre compte Google Cloud, suivez les étapes ci-dessous pour la détruire.

Détruire le lac de données

Utilisez le script de nettoyage pour supprimer les tables et ensembles de données BigQuery, ainsi que les définitions d'aspect Knowledge Catalog.

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

Supprimer des services Cloud Run

Supprimez les ressources de calcul pour arrêter toute facturation active du conteneur en cours d'exécution.

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

Nettoyer les artefacts de compilation et l'espace de stockage intermédiaire

Lorsque vous avez déployé l'agent ADK, le système a automatiquement créé une image de conteneur et importé votre code source dans un bucket Cloud Storage temporaire.

Supprimez le dépôt Artifact Registry et le bucket de préproduction 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}

Supprimer l'identité et les autorisations

Supprimez d'abord les liaisons de stratégie IAM, puis supprimez les comptes de service.

# 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

Supprimer la configuration locale

Enfin, nettoyez les fichiers de configuration locaux et les variables d'environnement dans 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. Félicitations !

Vous avez déployé un agent d'IA générative de bout en bout, respectueux de la gouvernance.

Dans cet atelier de programmation en deux parties, vous avez dépassé l'ingénierie de prompt simple pour implémenter une architecture robuste et prête pour la production. En traitant la gouvernance des données comme une condition préalable à l'IA générative, vous avez établi une méthode systématique pour empêcher le modèle de récupérer des données non certifiées ou hallucinées.

Points à retenir

  • IA déterministe via les métadonnées : au lieu de s'appuyer sur le LLM pour deviner la table correcte en fonction des noms de colonnes, vous avez appliqué une boucle de raisonnement stricte à l'aide du serveur MCP Knowledge Catalog géré par Google, ce qui a forcé le modèle à vérifier les certifications de données avant de recommander des tables.
  • Architecture découplée : l'agent de l'interface utilisateur n'a pas besoin de contenir de logique de base de données. Il n'a besoin de communiquer que via la norme MCP. Cela signifie que vous pouvez brancher n'importe quel futur modèle ou client d'IA sur le même backend contrôlé.
  • Séparation des tâches : vous avez appliqué le principe du moindre privilège en isolant les identités IAM. L'agent ADK destiné aux utilisateurs fonctionne avec des autorisations limitées à l'invocation de modèles et au routage d'API.
  • Orchestration d'agents axée sur le code : vous avez utilisé le Google Agent Development Kit (ADK) pour encapsuler instantanément la logique de votre agent Python dans un backend FastAPI évolutif, en utilisant son UI de développement intégrée pour visualiser et déboguer les exécutions d'outils internes de l'agent.

Étape suivante