Agent Governance Auditor

Un agente ADK que audita otros agentes de IA para verificar su cumplimiento — detecta las cargas de trabajo de IA que se ejecutan en un proyecto de GCP, incluidas las que nadie registró, ejecuta 11 comprobaciones de gobernanza deterministas contra un paquete de políticas versionado, y produce un paquete de evidencia listo para auditoría mapeado a la Ley de IA de la UE (arts. 6, 9, 11, 12, 13, 15, 50) y a los Criterios de Servicios de Confianza de SOC 2. Cada hallazgo lleva una cita de evidencia inmutable (GCS + SHA-256). Cada acción de escritura requiere aprobación humana.

Cada política explica por qué se mapea a los artículos que reclama — y dos mapeos se eliminaron durante la revisión por excederse, porque el sobre-mapeo es lo que desacredita más rápido un informe de cumplimiento. La herramienta audita la ausencia de declaraciones requeridas, nunca infracciones legales inferidas: «no hay clasificación de riesgo documentada» es comprobable y es lo que un auditor hace constar; «este agente es de alto riesgo según el Anexo III» es un juicio legal que no está autorizada a emitir.

Construido para el hackathon de Gemini Enterprise — Stream 2 (High-Code: ADK + servidor MCP personalizado + Agent Runtime en la plataforma de agentes de Gemini Enterprise).

Por qué

El calendario de la Ley de IA de la UE se ha movido, y eso hace que el problema sea más urgente, no menos. El Reglamento (UE) 2026/1744 (el «Ómnibus Digital sobre IA», en vigor el 27 de julio de 2026) aplazó las obligaciones de alto riesgo del Anexo III hasta el 2 de diciembre de 2027. Aplazadas, no canceladas — y mientras tanto, las obligaciones de transparencia del artículo 50, las prácticas prohibidas del artículo 5 y las obligaciones de los proveedores de GPAI están todas vigentes hoy, con sanciones que alcanzan los 35 millones de euros o el 7 % del volumen de negocios mundial.

Por lo tanto, las empresas tienen aproximadamente dieciséis meses para construir un rastro de evidencia para los sistemas de alto riesgo, mientras ya cargan con obligaciones sobre los agentes que ejecutan ahora mismo. Ambas cosas dependen de responder a una pregunta que los auditores siempre hacen — «¿qué sistemas de IA tienes y puedes demostrar que están gobernados?» — a la que la respuesta honesta suele ser «no estamos del todo seguros».

Esta herramienta la responde, con evidencia.

Related MCP server: EU AI Act Compliance MCP Server

Cómo funciona

El diagrama anterior muestra lo que existe. Reglas de diseño principales (arquitectura completa):

• El LLM nunca decide el cumplimiento — lo hace el código. El aprobado/suspenso se calcula en el código de la herramienta MCP; el agente orquesta, prioriza y narra. Un guardián de mutaciones aborta cualquier ejecución en la que el triaje intente cambiar un estado.

• Fundamentación por construcción. Un hallazgo sin evidence_ref no puede existir en el modelo de datos — el esquema lo rechaza.

• Solo lectura por defecto. La única vía de escritura (una orden de remediación) requiere un token de aprobación de un solo uso emitido por un humano, aplicado en el servidor para que este nunca confíe en la afirmación del agente de que un humano aprobó.

• El auditor se audita a sí mismo — se despliega con su propia identidad de agente y es descubierto por su propio barrido, superando 6 de sus 11 comprobaciones.

Una auditoría, de principio a fin

Dos cosas en ese diagrama son diseño, no decoración. El triaje no llama a ninguna herramienta MCP — al único paso que hace razonamiento real se le niega cualquier alcance fuera del proceso. Y la ejecución se suspende antes de que se escriba nada: todavía no existe ningún token, por lo que el servidor rechazaría una escritura incluso si el agente lo intentara.

El descubrimiento es conductual, no por coincidencia de nombre

La pregunta de la que depende la vida o la muerte de este producto es «¿encontrarías un agente que no se llame agent-something?». La coincidencia de nombre responde «no» — pierde customer-insights-api y marca un nginx llamado agent-proxy. Así que una carga de trabajo se clasifica según cinco señales, con la confianza y las razones informadas para cada candidato:

La primera es la clave: una carga de trabajo que habla con un modelo no puede esconderse detrás de un nombre aburrido. La flota de demostración incluye customer-insights-api — un agente ADK real sin nombre de agente ni etiquetas — precisamente para que esta afirmación sea comprobable en lugar de solo enunciada.

Qué cubre y qué no cubre

El descubrimiento llega más lejos que la auditoría, y el informe dice cuál es cuál:

La última fila es la honesta. Una carga de trabajo que llama a un proveedor externo nunca toca los registros de Google, y un auditor de cumplimiento no detecta eso — comprueba si los controles que habrían podido detenerlo están activados, e informa cuando no lo están. GOV-NET-007 es exactamente esa comprobación.

El suelo: usar un modelo requiere autenticarse, y la autenticación queda registrada. Así que el peor caso es «aquí hay uno que no podemos atribuir — ve a mirar», nunca el silencio.

Inicio rápido

Todo el desarrollo ocurre dentro de un contenedor — Ubuntu 26.04 LTS con gcloud, Terraform, Node y una versión fijada de Python 3.12. No se instala nada en tu máquina, y el entorno es idéntico en macOS, Windows (Docker Desktop o WSL2) y Linux.

Requisitos previos: Docker en ejecución (OrbStack, Docker Desktop o WSL2) y este repositorio clonado. Nada más.

1. Construye la imagen y obtén una shell

Abre una terminal en la raíz del repositorio — la carpeta que contiene este README y las carpetas gov_mcp/ auditor/ infra/:

cd path/to/agent-governance-auditor      # wherever you cloned it

# Build. First time ~3-5 min; afterwards it's instant (layer cache), so it's
# safe to just always run it.
docker build -t agv-dev docker/

# Start a shell inside the container.
docker run -it --rm \
  -v "$PWD":/workspace \
  -v agv-gcloud:/home/ubuntu/.config/gcloud \
  -v agv-venv:/opt/venv \
  -p 8080:8080 -p 8000:8000 -p 6274:6274 -p 6277:6277 \
  agv-dev bash

docker run -it --rm `
  -v "${PWD}:/workspace" `
  -v agv-gcloud:/home/ubuntu/.config/gcloud `
  -v agv-venv:/opt/venv `
  -p 8080:8080 -p 8000:8000 -p 6274:6274 -p 6277:6277 `
  agv-dev bash

Qué hacen esas banderas:

Tu prompt se convierte en ubuntu@…:/workspace$. Ya estás dentro.

Todo lo que sigue se ejecuta dentro del contenedor.

2. Configuración única y autenticación

bash docker/post-create.sh    # creates the python env, installs deps, runs the tests

# BOTH logins are required and they are NOT interchangeable:
#   the first authenticates the gcloud CLI
#   the second writes Application Default Credentials, which Terraform and
#   every google-cloud-* python client read instead
gcloud auth login --no-launch-browser
gcloud auth application-default login --no-launch-browser

gcloud auth application-default print-access-token >/dev/null && echo "ADC OK"

Cada inicio de sesión imprime una URL para abrir en tu navegador y te pide que pegues un código de vuelta. En la segunda pantalla de consentimiento, marca todas las casillas de permisos («Seleccionar todo») — el consentimiento parcial falla con un confuso error Scope has changed, y necesitas el alcance cloud-platform para que cualquier cosa funcione. No continúes hasta que se imprima ADC OK.

→ si la pantalla de consentimiento da error: gotcha 0b

3. Crea tu proyecto sandbox de GCP

export PROJECT_ID="agent-gov-auditor-$(date +%y%m%d)"   # must be globally unique
gcloud projects create "$PROJECT_ID" --name="agent-governance-auditor"
gcloud config set project "$PROJECT_ID"

gcloud billing accounts list                             # copy your account id
gcloud billing projects link "$PROJECT_ID" --billing-account=XXXXXX-XXXXXX-XXXXXX

# REQUIRED: attribute ADC API calls to your project. User credentials carry no
# project of their own, so without this Terraform gets a 403 SERVICE_DISABLED
# blaming Google's shared ADC client project (764086051850).
gcloud auth application-default set-quota-project "$PROJECT_ID"

gcloud config set run/region us-central1

La facturación debe estar vinculada antes de que se ejecute Terraform — habilitar las API lo requiere.

→ si te encuentras con un 403 al nombrar el proyecto 764086051850: gotcha 0c

4. Aprovisiona la infraestructura

Crea las API habilitadas, las cuentas de servicio (incluida la rogue deliberadamente sobre-permisionada), el bucket de evidencia, el presupuesto, el sumidero de registros de auditoría y el repositorio de Artifact Registry.

cd infra
cp terraform.tfvars.example terraform.tfvars
# edit terraform.tfvars: project_id, billing_account_id, region
terraform init
terraform plan
terraform apply

Si apply falla en el presupuesto de facturación, eso es esperado en algunas cuentas: los presupuestos necesitan permiso a nivel de cuenta de facturación, no a nivel de proyecto. Créalo una vez en la consola y haz terraform import, o comenta el recurso. No pierdas una noche con ello.

→ si el primer apply falla con un muro de SERVICE_DISABLED: gotcha 0e — normalmente basta con volver a ejecutarlo

5. Desplegar todo

Un comando construye y despliega todo el conjunto sobre la base de Terraform, en orden de dependencias, imprimiendo el tiempo transcurrido por etapa. Medido: 6m 57s para la flota completa de cuatro agentes.

./scripts/deploy-all.sh

Luego abre la aplicación Gemini Enterprise que registró (Agents → 3-dot → Preview) y envía:

Ejecuta una auditoría de gobernanza de este proyecto.

La ejecución se detiene en la puerta de aprobación. Responde APPROVE para autorizar la remediación, o APPROVE <finding id> para un subconjunto, o DECLINE. (GE y el Agent Runtime Playground no muestran ningún botón de confirmación para la primitiva de confirmación experimental de ADK, por eso la puerta también acepta una respuesta escrita.)

¿Prefieres la terminal o quieres manejarlo sin navegador?

python scripts/query_agent_runtime.py        # multi-turn chat against the deployed agent

→ si el agente desplegado da 401 o se detiene en la puerta: gotchas 0q y 0r

6. Desmontar, reconstruir, repetir

Un desmontaje suave elimina todo lo que creó un script de despliegue y conserva todo lo que posee Terraform, de modo que puedes ejercitar toda la ruta de despliegue en minutos sin un arranque de proyecto de 20 minutos. También es el mejor ensayo para la demo, porque es la misma secuencia.

./scripts/teardown-workloads.sh     # prompts first; --yes to skip
terraform -chdir=infra plan         # expect NO changes — proves the split is clean
./scripts/deploy-all.sh             # back up in ~6 minutes

La evidencia deliberadamente no se elimina: el cubo tiene una política de retención de 30 días y la rechazará. Esa es la inmutabilidad que el diseño afirma, y ver cómo se rechaza una eliminación lo demuestra mejor que cualquier afirmación.

La cadena de despliegue

Útil cuando algo falla y necesitas saber qué eslabón volver a ejecutar:

scripts/deploy-all.sh
├─ 1. auditee fleet
│      auditees/deploy-{compliant,legacy,rogue,insights}.sh
│        └─ each sources auditees/common.sh → build_image()
│             └─ gcloud builds submit  (Dockerfile + main.py + requirements.txt)
│                  └─ Artifact Registry
│           then gcloud run deploy, with posture set by FLAGS only
├─ 2. gov_mcp/deploy.sh                  → Cloud Build → Cloud Run (MCP server)
├─ 3. auditor/deploy.sh                  → Agent Runtime + its two IAM bindings
└─ 4. scripts/setup-gemini-enterprise.sh → GE app + agent registration + sharing

Tres cosas que vale la pena saber sobre esa cadena:

• common.sh es una biblioteca incluida, no un script. Define PROJECT_ID, REGION, IMAGE y build_image(). Ejecutarlo directamente no hace nada.

• Una imagen, cuatro despliegues. Los cuatro auditados ejecutan el mismo contenedor; su postura de gobernanza vive enteramente en las banderas de gcloud run deploy — etiquetas, cuenta de servicio, variables de entorno — que es exactamente lo que el auditor inspecciona. Así que el primer script construye y el resto reutiliza.

• build_image() omite la construcción cuando la imagen ya existe. Después de editar auditees/main.py, un redespliegue simple envía la imagen antigua y tu cambio no se aplica silenciosamente. Fuerza una vez: FORCE_BUILD=1 ./auditees/deploy-compliant.sh.

Los pasos 2 y 3 también funcionan de forma independiente (./auditor/deploy.sh redespliega solo el agente), y cada script es idempotente: volver a ejecutarlo es seguro.

Salir y volver: exit termina la sesión y elimina el contenedor. Vuelve a ejecutar el mismo comando docker run … para regresar: tu inicio de sesión de gcloud y los paquetes instalados siguen ahí, porque viven en los volúmenes agv-gcloud y agv-venv en lugar de en el contenedor. Para borrar todo y empezar limpio: docker volume rm agv-gcloud agv-venv.

Cuando algo se rompe, revisa gotchas y bordes afilados antes de depurar: cubre los fallos que ya hemos encontrado, incluyendo el fallo de autenticación Scope has changed, el error de importación mcp.shared.session, el fallo de gcloud virtualenv/VPN, y por qué varias comprobaciones reportan legítimamente SKIPPED en un proyecto personal.

Los pasos anteriores son el camino feliz. docs/build-plan.md contiene el resto: las reglas operativas, cada gotcha que realmente encontramos y un registro de decisiones que explica por qué las cosas son como son.

Repositorio

scripts/

Pruebas

pytest evals/ -q              # 171 offline, no GCP needed, free
pytest evals/agent -m live    # 8 end-to-end agent evals (~100s, ~$0.02, needs ADC)

La suite en vivo impulsa el pipeline real y afirma lo que las pruebas unitarias estructuralmente no pueden: que la ejecución llega a la puerta, que nada se remedia antes de que un humano apruebe, que el token de aprobación nunca llega al chat, y que cada hallazgo fallido lleva un hash de evidencia válido.