Implementa un agente que tenga en cuenta la administración empresarial con MCP y Cloud Run

1. Introducción

Este codelab es parte de una serie de dos partes en la que se explora cómo compilar un agente de IA generativa que tenga en cuenta la administración.

(Puedes leer la primera parte de esta serie, en la que se explica cómo establecer la base de datos aplicando aspectos de Dataplex a las tablas de BigQuery y probando las reglas de forma local a través de la CLI de Gemini. 👉 Leer la Parte 1)

Sin embargo, la prueba en una CLI local es solo el comienzo. Para implementarla en toda tu empresa, necesitas seguridad centralizada, conexiones estandarizadas de herramientas de IA y un framework de aplicación adecuado para organizar la lógica del agente y proporcionar una interfaz de chat familiar.

En esta segunda parte, resolverás estos desafíos y escalarás a la producción. Implementarás tus reglas de administración en un servidor de MCP central alojado en Cloud Run. Luego, usarás el Kit de desarrollo de agentes (ADK) de Google para compilar la aplicación del agente real y conectarla a tus herramientas de MCP, con una IU web profesional.

be15d5f41f0d716c.png

Requisitos previos

  • Un proyecto de Google Cloud con facturación habilitada.
  • Conocimientos básicos de Cloud Run, cuentas de servicio de IAM y Python.
  • Los conjuntos de datos de BigQuery y los aspectos de Dataplex creados en la Parte 1 (no te preocupes si los borraste, ya que te proporcionamos una secuencia de comandos de acceso rápido a continuación para volver a crearlos).

Qué aprenderás

  • Cómo usar el Protocolo de contexto del modelo (MCP) para estandarizar la forma en que los agentes de IA interactúan con los datos de Google Cloud
  • Cómo implementar un servidor de MCP seguro en Cloud Run
  • Cómo compilar un agente de IA con el Kit de desarrollo de agentes (ADK) y conectarlo a tu backend de MCP
  • Cómo ejecutar la IU para desarrolladores integrada del ADK para interactuar con tu agente administrado

Requisitos

  • Acceso a Google Cloud Shell

Conceptos clave

  • Protocolo de contexto del modelo (MCP): Piensa en el MCP como un "cable USB-C universal" para los agentes de IA. En lugar de escribir código de integración de API personalizado para cada modelo de IA, el MCP proporciona una forma estándar para que la IA se conecte de forma segura a tus herramientas de datos empresariales (como Dataplex y BigQuery).
  • Kit de desarrollo de agentes (ADK): Es un framework flexible de código abierto de Google diseñado para simplificar el desarrollo integral de agentes de IA. Aplica principios de ingeniería de software a la creación de agentes, lo que te permite organizar herramientas complejas, administrar el estado y lanzar fácilmente una IU para desarrolladores integrada para pruebas e implementación.

2. Configuración y requisitos

Iniciar Cloud Shell

Si bien Google Cloud y Spanner se pueden operar de manera remota desde tu laptop, en este codelab usarás Google Cloud Shell, un entorno de línea de comandos que se ejecuta en la nube.

En el Google Cloud Console, haz clic en el ícono de Cloud Shell en la barra de herramientas en la parte superior derecha:

Activar Cloud Shell

El aprovisionamiento y la conexión al entorno deberían tomar solo unos minutos. Cuando termine el proceso, debería ver algo como lo siguiente:

Captura de pantalla de la terminal de Google Cloud Shell que muestra que el entorno se conectó

Esta máquina virtual está cargada con todas las herramientas de desarrollo que necesitarás. Ofrece un directorio principal persistente de 5 GB y se ejecuta en Google Cloud, lo que permite mejorar considerablemente el rendimiento de la red y la autenticación. Todo tu trabajo en este codelab se puede hacer en un navegador. No es necesario que instales nada.

Inicializa el entorno

Abre Cloud Shell y configura las variables de tu proyecto para asegurarte de que todos los comandos apunten a la infraestructura correcta.

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

Punto de control: ¿Reanudar o volver a compilar?

Como esta es la Parte 2, tu agente necesita los datos administrados de la Parte 1 para funcionar. Elige tu ruta de acceso:

Ruta de acceso A: Acabo de terminar la Parte 1 y mis recursos aún se están ejecutando.

¡Genial! Navega hasta el directorio de trabajo y estarás listo para continuar.

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

Ruta de acceso B: Omití la Parte 1 O borré mis recursos (limpié).

No hay problema. Proporcionamos un bloque de comandos de "acceso rápido" a continuación. Esto volverá a compilar automáticamente el data lake de BigQuery y aplicará los metadatos de administración de Dataplex exactamente como lo hicimos en la 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. Escala con MCP: Compila el plano de control de datos

Hasta ahora, probaste correctamente tu lógica de administración con la CLI de Gemini. Esto es excelente para la creación rápida de prototipos, pero se ejecuta de forma local con tus credenciales de usuario personales.

En un entorno empresarial real, necesitas un plano de control de datos centralizado. Para compilarlo, usaremos la Caja de herramientas de IA generativa para bases de datos, un proyecto oficial de código abierto de Google. Esta caja de herramientas proporciona un servidor de MCP prediseñado diseñado específicamente para conectar agentes de IA de forma segura a bases de datos de Google Cloud y servicios de metadatos como Dataplex.

Cuando implementamos esta caja de herramientas como nuestro servidor de MCP en Cloud Run, logramos lo siguiente:

  1. Identidad centralizada: El agente se ejecuta como una cuenta de servicio restringida, no como tu cuenta de usuario personal.
  2. Estandarización: Cualquier cliente (ADK, Gemini, apps personalizadas) puede "conectarse" a este servidor con el protocolo MCP estándar.
  3. Alcance controlado (privilegio mínimo): No le damos al LLM acceso abierto a BigQuery. Lo obligamos a navegar primero por el catálogo de metadatos de Dataplex.

Configura la definición de la herramienta (tools.yaml)

La Caja de herramientas de IA generativa requiere un archivo de configuración declarativo, tools.yaml. Este archivo define las sources (dónde conectarse) y las tools (qué puede hacer la IA).

  1. Navega hasta el directorio del servidor y, luego, inserta el ID del proyecto en el archivo de configuración:
cd ~/devrel-demos/data-analytics/governance-context/mcp_server
envsubst < tools.yaml > tools.tmp && mv tools.tmp tools.yaml
cat tools.yaml

Debería ser idéntico al siguiente fragmento. Verifica que el campo del proyecto ahora coincida con tu ID del proyecto de Google Cloud real.

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

Si definimos estas tres herramientas, podemos obligar a la IA a ser "de solo lectura" y "priorizar la administración".

Protege la configuración (Secret Manager)

En la arquitectura empresarial, nunca debes incorporar archivos de configuración directamente en imágenes de contenedor. Almacenaremos tools.yaml de forma segura en Secret Manager de Google Cloud.

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

Implementa el privilegio mínimo (IAM)

A continuación, creamos una cuenta de servicio dedicada para el servidor de MCP de la Caja de herramientas de IA generativa. Esta identidad solo tendrá los permisos exactos necesarios para leer el catálogo de Dataplex y acceder a los datos de 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"

Implementa el servidor de MCP en Cloud Run

Ahora, implementamos la Caja de herramientas de IA generativa. Usamos la imagen de contenedor prediseñada de Google (database-toolbox/toolbox) y activamos nuestra configuración desde Secret Manager (--set-secrets) en el tiempo de ejecución.

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"

Ya estableciste una API administrada. En lugar de otorgar acceso directo a la base de datos a tu frontend de IA generativa, se conectará a esta URL de Cloud Run. El agente solo puede ver lo que le permite ver esta caja de herramientas.

4. Compila el backend del agente con el ADK

Estableciste un plano de control de datos (MCP) seguro y administrado que se ejecuta en Cloud Run. Ahora, tu agente de IA necesita un framework para organizar su lógica, como procesar las entradas del usuario, decidir cuándo llamar al servidor de MCP y dar formato al resultado.

En lugar de escribir todo este código estándar desde cero, usaremos el Kit de desarrollo de agentes (ADK) de Google. El ADK es un framework centrado en el código que ajusta automáticamente la lógica de tu agente en un backend de FastAPI. Además, incluye una IU para desarrolladores integrada, lo que te permite visualizar al instante el proceso de razonamiento del agente y las llamadas a herramientas sin compilar primero un frontend personalizado.

Inspecciona la lógica del agente (agent.py)

Antes de configurar la infraestructura, veamos el núcleo de esta aplicación.

Navega hasta el directorio y genera el contenido de agent.py. Este archivo es el "cerebro" de tu implementación del ADK.

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

Observa la estructura del código. Realiza tres funciones esenciales con un código estándar mínimo:

  1. Integración de MCPToolset: En lugar de escribir clientes HTTP personalizados para interactuar con tus herramientas de Dataplex, el ADK usa MCPToolset(server_url=mcp_url). Esto recupera de forma dinámica la definición tools.yaml de tu servidor de MCP implementado y la traduce en llamadas a funciones nativas para el LLM.
  2. Instrucciones del sistema: El parámetro instructions contiene las reglas de administración estrictas (la misma lógica que usamos en la CLI GEMINI.md). Ordena explícitamente al modelo que ejecute el bucle de razonamiento de la fase 1 (búsqueda de metadatos) a la fase 2 (consulta de datos).
  3. Organización de agentes: La clase Agent(...) vincula el modelo de Gemini, la instrucción del sistema y las herramientas de MCP. Cuando se implementa, el ADK convierte automáticamente este objeto en un extremo de FastAPI escalable.

Separación de tareas: Configura la identidad del frontend

Para ejecutar este código de forma segura, debemos indicarle al agente dónde se encuentra tu servidor de MCP. Construiremos la URL de forma dinámica y la guardaremos en un archivo .env que el ADK leerá en el tiempo de ejecución.

También crearemos una identidad independiente (dataplex-agent-sa) para esta aplicación orientada al usuario. Esta separación de tareas garantiza que el agente de frontend tenga permisos diferentes del servidor de administración de backend.

Ejecuta los siguientes comandos para configurar el entorno y la identidad:

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 "

Configura las variables de tiempo de ejecución

El framework del ADK se basa en variables de entorno para comprender su contexto. Debemos configurar explícitamente el ID del proyecto, la región y habilitar el uso de Vertex AI. Los agregamos al mismo archivo .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

Otorga permisos

Aunque el agente delega las verificaciones de administración al servidor de MCP, aún necesita permisos básicos para operar. Otorgamos exactamente dos roles:

  1. Usuario de Vertex AI: Para invocar el modelo de Gemini para generar respuestas en lenguaje natural
  2. Invocador de Cloud Run: Para llamar de forma segura a tu API del servidor de MCP (no obtiene acceso directo a BigQuery ni a 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"

Implementa en Cloud Run

Por último, implementamos la pila completa en Cloud Run.

Usamos uvx para ejecutar la herramienta del ADK sin instalar dependencias de forma manual. El siguiente comando empaqueta la lógica de agent.py, compila una imagen de contenedor, inserta tu cuenta de servicio y lanza un servidor de FastAPI. Si agregas la marca --with_ui, también agrupa el ADK Web Playground para la depuración.

Este comando compila el contenedor y lo implementa. Puede tardar entre 1 y 3 minutos en completarse.

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 vez que se complete este comando, generará una URL de servicio (e.g., https://dataplex-agent-xyz.run.app). Haz clic en ese vínculo para abrir tu interfaz de chat de IA generativa completamente administrada.

12a5fa4c2aaf381f.png

Flujo arquitectónico integral

Ya completaste el sistema. Cuando un usuario interactúa con la IU del ADK, se produce la siguiente secuencia:

  1. El usuario envía una instrucción en el agente del ADK (IU de desarrollo).
  2. El agente del ADK (agent.py) procesa la entrada y llama al modelo de Gemini.
  3. Gemini determina que necesita contexto y le pide al servidor de MCP que ejecute las herramientas de Dataplex.
  4. El servidor de MCP aplica las reglas de administración de Dataplex y muestra los metadatos.
  5. Gemini sintetiza la respuesta de confianza en función de los metadatos y se la muestra al usuario.

5. Prueba el agente empresarial

Ahora que tu agente está activo, volvamos a los casos de uso de administración que probamos antes con la CLI. La lógica sigue siendo la misma, pero ahora interactúas con el ADK Web Playground implementado, que visualiza el estado interno y las ejecuciones de herramientas.

  1. Organización: El agente del ADK (que se ejecuta en Cloud Run) recibe tu texto.
  2. Enrutamiento de herramientas: Gemini reconoce que tu pregunta requiere contexto de datos y reenvía la solicitud al servidor de MCP.
  3. Verificación de administración: El servidor de MCP (que se ejecuta en una instancia de Cloud Run independiente) consulta a Dataplex para obtener tipos de aspectos específicos.
  4. Síntesis: Los metadatos pertinentes se muestran a Gemini para generar la respuesta final.

Verifica la lógica de administración

Abre la URL de servicio que generaste en el paso anterior (e.g., https://dataplex-agent-xyz.run.app) en tu navegador. Pega la siguiente instrucción:

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

Observa el proceso de razonamiento del agente en la IU para desarrolladores:

  1. Reconocimiento de la intención: El agente analiza "ahora mismo" y "no puedo esperar hasta la noche".
  2. Búsqueda de metadatos: Llama a la herramienta de MCP search_aspect_types. Busca recursos de datos en los que el aspecto update_frequency esté configurado como REALTIME o STREAMING, en lugar de DAILY o MONTHLY.
  3. Selección: Identifica que la tabla mkt_realtime_campaign_performance cumple con estos criterios, mientras que fin_monthly_closing_internal (a pesar de ser de alta calidad) es demasiado lenta para tu solicitud.
  4. Respuesta: El agente recomienda la tabla en tiempo real.

e0da615724199e.png

Por qué es importante:

Sin estos metadatos de administración, es probable que un LLM recomiende la tabla fin_monthly_closing_internal simplemente porque tiene una columna llamada "ad_spend", sin tener en cuenta que los datos tienen 24 horas de antigüedad. El contexto de tus metadatos evitó un error comercial.

También puedes probar la instrucción "Board Meeting" para ver cómo el agente cambia a diferentes tablas según el aspecto de nivel de producto de datos:

"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. Limpia

Para evitar que se generen cargos en tu cuenta de Google Cloud por los recursos que se usaron en este codelab, sigue estos pasos para destruir toda la infraestructura creada en la Parte 1 y la Parte 2.

Destruye el data lake (Terraform)

Usa Terraform para desglosar las tablas, los conjuntos de datos y las definiciones de aspectos de Dataplex de BigQuery.

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

Borra los servicios de Cloud Run

Quita los recursos de procesamiento para detener cualquier facturación activa de los contenedores en ejecución.

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

Limpia los artefactos de compilación y el almacenamiento de etapa de pruebas

Cuando implementaste el agente del ADK con uvx, el sistema compiló automáticamente una imagen de contenedor y subió tu código fuente a un bucket temporal de Cloud Storage. Estos artefactos persisten incluso después de que se borra el servicio de Cloud Run y generarán costos de almacenamiento continuos.

Quita el repositorio de Artifact Registry y el bucket de etapa de pruebas de 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}

Borra la identidad, los permisos y los secretos

Quita primero las vinculaciones de políticas de IAM para evitar que las entradas de "lápida" (registros huérfanos) permanezcan en la página de IAM de tu proyecto. Luego, borra las cuentas de servicio y los secretos de configuración.

# 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

Quita la configuración local

Por último, limpia los archivos de configuración locales y las variables de entorno en 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. ¡Felicitaciones!

Implementaste correctamente un agente de IA generativa integral que tiene en cuenta la administración.

En este codelab de dos partes, fuiste más allá de la ingeniería de instrucciones simple para implementar una arquitectura sólida y lista para la producción. Al tratar la administración de datos como un requisito previo para la IA generativa, estableciste un método sistemático para evitar que el modelo recupere datos no certificados o alucinados.

Conclusiones principales

  • IA determinista a través de metadatos: En lugar de depender del LLM para adivinar la tabla correcta en función de los nombres de las columnas, aplicaste un bucle de razonamiento estricto con la Caja de herramientas de IA generativa para bases de datos. Al exponer explícitamente solo tres herramientas de Dataplex (search_aspect_types, search_entries, lookup_entry), obligaste al modelo a verificar las certificaciones de datos antes de sintetizar las respuestas.
  • Arquitectura desacoplada (MCP): Cuando implementaste el servidor de Protocolo de contexto del modelo (MCP) en Cloud Run, abstrajiste tus reglas de administración de datos en una API centralizada y estandarizada. El agente de frontend no necesita contener lógica de base de datos, solo necesita comunicarse a través del estándar de MCP. Esto significa que puedes conectar cualquier modelo o cliente de IA futuro al mismo backend administrado.
  • Separación de tareas: Aplicaste el principio de privilegio mínimo aislando las identidades de IAM. El agente del ADK orientado al usuario opera con permisos restringidos a la invocación de modelos y el enrutamiento de APIs, mientras que el servidor de MCP de backend controla de forma segura las consultas de catálogos de Dataplex y la recuperación de datos de BigQuery.
  • Organización de agentes centrada en el código: Utilizaste el Kit de desarrollo de agentes (ADK) de Google para ajustar al instante la lógica de tu agente de Python en un backend de FastAPI escalable, utilizando su IU para desarrolladores integrada para visualizar y depurar las ejecuciones de herramientas internas del agente.

Próximos pasos