Agent Governance Auditor

Ein ADK-Agent, der andere KI-Agenten auf Compliance prüft — findet die in einem GCP-Projekt laufenden KI-Workloads, einschließlich derer, die niemand registriert hat, führt 11 deterministische Governance-Checks gegen ein versioniertes Policy-Paket aus und erzeugt ein prüfungsfertiges Evidenzpaket, das auf den EU AI Act (Art. 6, 9, 11, 12, 13, 15, 50) und die SOC 2 Trust Services Criteria abgebildet ist. Jeder Befund trägt eine unveränderliche Evidenzzitation (GCS + SHA-256). Jede Schreibaktion ist von einem Menschen genehmigt.

Jede Policy begründet, warum sie auf die von ihr beanspruchten Artikel abbildet — und zwei Zuordnungen wurden bei der Überprüfung entfernt, weil sie zu weit gingen, denn Über-Zuordnung ist das, was einen Compliance-Bericht am schnellsten diskreditiert. Das Tool prüft auf das Fehlen geforderter Erklärungen, niemals auf abgeleitete Rechtsverstöße: „keine dokumentierte Risikoklassifizierung" ist prüfbar und das, was ein Auditor aufschreibt; „dieser Agent ist unter Anhang III hochriskant" ist ein rechtliches Urteil, das es nicht zu fällen befugt ist.

Gebaut für den Gemini-Enterprise-Hackathon — Stream 2 (High-Code: ADK + benutzerdefinierter MCP-Server + Agent Runtime auf der Gemini-Enterprise-Agent-Plattform).

Warum

Der Zeitplan des EU AI Act hat sich verschoben, und das macht das Problem dringlicher statt weniger dringlich. Verordnung (EU) 2026/1744 (der „Digital Omnibus on AI", in Kraft seit 27. Juli 2026) hat die Hochrisiko-Pflichten aus Anhang III auf den 2. Dezember 2027 verschoben. Verschoben, nicht gestrichen — und in der Zwischenzeit sind die Transparenzpflichten aus Artikel 50, die verbotenen Praktiken aus Artikel 5 und die Pflichten für GPAI-Anbieter heute bereits in Kraft, mit Strafen von bis zu 35 Mio. € oder 7 % des weltweiten Umsatzes.

Unternehmen haben also etwa sechzehn Monate Zeit, um eine Evidenzspur für Hochrisikosysteme aufzubauen, während sie bereits jetzt Pflichten für die Agenten tragen, die sie gerade betreiben. Beides hängt von der Beantwortung einer Frage ab, die Auditoren immer stellen — „welche KI-Systeme haben Sie, und können Sie beweisen, dass sie gouverniert sind?" — auf die die ehrliche Antwort meist „wir sind uns nicht ganz sicher" lautet.

Dieses Tool beantwortet sie — mit Evidenz.

Related MCP server: EU AI Act Compliance MCP Server

So funktioniert es

Das obige Diagramm zeigt, was existiert. Zentrale Designregeln (vollständige Architektur):

• Das LLM entscheidet nie über Compliance — der Code tut es. Bestanden/nicht bestanden wird im MCP-Toolcode berechnet; der Agent orchestriert, priorisiert und kommentiert. Ein Mutations-Guard bricht jeden Lauf ab, bei dem die Triage versucht, einen Status zu kippen.

• Grounding durch Konstruktion. Ein Befund ohne evidence_ref kann im Datenmodell nicht existieren — das Schema lehnt ihn ab.

• Standardmäßig schreibgeschützt. Der einzige Schreibpfad (ein Remediation-Auftrag) erfordert ein von einem Menschen erzeugtes Einmal-Genehmigungstoken, das serverseitig erzwungen wird, sodass der Server niemals der Behauptung des Agenten vertraut, dass ein Mensch genehmigt hat.

• Der Auditor prüft sich selbst — er wird unter seiner eigenen Agent Identity bereitgestellt und von seinem eigenen Scan entdeckt, wobei er 6 seiner eigenen 11 Checks besteht.

Eine Prüfung, Ende zu Ende

Zwei Dinge darin sind Design, nicht Dekoration. Die Triage ruft überhaupt kein MCP-Tool auf — dem einen Schritt, der echte Schlussfolgerungen anstellt, wird jeder Zugriff außerhalb des Prozesses verwehrt. Und der Lauf pausiert, bevor irgendetwas geschrieben wird: Es existiert noch kein Token, sodass der Server einen Schreibvorgang ablehnen würde, selbst wenn der Agent einen versuchte.

Erkennung ist verhaltensbasiert, nicht Namensabgleich

Die Frage, an der dieses Produkt lebt oder stirbt, ist: „Würden Sie einen Agenten finden, der nicht agent-something heißt?" Namensabgleich antwortet mit „nein" — er übersieht customer-insights-api und markiert einen nginx namens agent-proxy. Eine Workload wird daher anhand von fünf Signalen klassifiziert, wobei Konfidenz und Gründe für jeden Kandidaten gemeldet werden:

Das erste ist der Punkt: Eine Workload, die mit einem Modell spricht, kann sich nicht hinter einem langweiligen Namen verstecken. Die Demo-Flotte enthält customer-insights-api — einen echten ADK-Agenten ohne agentenartigen Namen und ohne Labels — genau damit diese Behauptung testbar statt bloß behauptet ist.

Was es abdeckt und was nicht

Die Erkennung reicht weiter als die Prüfung, und der Bericht sagt, was was ist:

Die letzte Zeile ist die ehrliche. Eine Workload, die einen externen Anbieter aufruft, berührt Googles Logs nie, und ein Compliance-Auditor fängt das nicht ab — er prüft, ob die Kontrollen, die es hätten stoppen können, eingeschaltet sind, und meldet, wenn sie es nicht sind. GOV-NET-007 ist genau dieser Check.

Die Untergrenze: Die Nutzung eines Modells erfordert Authentifizierung, und Authentifizierung wird protokolliert. Der schlimmste Fall ist also „hier ist einer, den wir nicht zuordnen können — schauen Sie nach", niemals Schweigen.

Schnellstart

Die gesamte Entwicklung findet in einem Container statt — Ubuntu 26.04 LTS mit gcloud, Terraform, Node und einem festgepinnten Python 3.12. Auf Ihrem Rechner wird nichts installiert, und die Umgebung ist auf macOS, Windows (Docker Desktop oder WSL2) und Linux identisch.

Voraussetzungen: Laufendes Docker (OrbStack, Docker Desktop oder WSL2) und dieses Repo geklont. Sonst nichts.

1. Image bauen und eine Shell erhalten

Öffnen Sie ein Terminal im Repo-Root — dem Ordner, der diese README und die Ordner gov_mcp/ auditor/ infra/ enthält:

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

Was diese Flags bewirken:

Ihre Eingabeaufforderung wird zu ubuntu@…:/workspace$. Sie sind drin.

Alles ab hier läuft im Container.

2. Einmalige Einrichtung und Authentifizierung

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"

Jede Anmeldung gibt eine URL aus, die Sie im Browser öffnen, und bittet Sie, einen Code zurückzupasten. Aktivieren Sie auf dem zweiten Zustimmungsbildschirm jedes Berechtigungskästchen („Select all") — teilweise Zustimmung scheitert mit einem verwirrenden Scope has changed-Absturz, und Sie benötigen den cloud-platform-Scope, damit irgendetwas funktioniert. Fahren Sie erst fort, wenn ADC OK ausgegeben wird.

→ falls der Zustimmungsbildschirm einen Fehler meldet: gotcha 0b

3. Erstellen Sie Ihr GCP-Sandbox-Projekt

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

Die Abrechnung muss verknüpft sein, bevor Terraform läuft — das Aktivieren von APIs erfordert sie.

→ falls Sie einen 403 mit der Projektnummer 764086051850 erhalten: gotcha 0c

4. Infrastruktur bereitstellen

Erstellt die aktivierten APIs, Dienstkonten (einschließlich des absichtlich überprivilegierten Schurkenkontos), den Evidenz-Bucket, das Budget, den Audit-Log-Sink und das Artifact-Registry-Repository.

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

Falls apply beim Billing-Budget? Das ist bei manchen Konten normal – Budgets brauchen eine Berechtigung auf Rechnungskonto-Ebene, nicht nur auf Projektebene. Lege es einmal in der Console an und verwende anschließend terraform import – oder kommentiere die Ressource aus. Verbringe keinen Abend damit.

→ Falls das erste apply mit einer Wand aus SERVICE_DISABLED-Fehlern scheitert: gotcha 0e — meist reicht es, den Befehl einfach nochmal laufen zu lassen.

5. Alles deployen

Ein einziger Befehl baut und deployed die gesamte Umgebung auf dem Terraform-Baseline, in guter Abhängigkeitsreihenfolge, und gibt die verstrichene Zeit pro Phase aus. Gemessen: 6m 57s für die volle Vier-Agenten-Flotte.

./scripts/deploy-all.sh

Dann öffne die Gemini Enterprise-App, die registriert wurde (Agents → Drei-Punkte-Menü → Preview) und send:

Führe eine Governance-Audit für dieses Projekt durch.

Der Lauf stoppt am Genehmigungs-Gate. Antworte APPROVE, um die Behebung zu autorisieren, oder APPROVE <finding id> für eine Teilmenge, oder DECLINE. (GE und der Agent Runtime Playground rendern keinen Bestätigungs-Button für ADKs experimentelles „Confirmation-Primitive“ – deshalb akzeptiert das Gate auch eine getippte Antwort.)

Bevorzug du das Terminal oder willst du es ohne Browser steuern:

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

→ falls der deployte Agent eine 401-Fehler meldet oder am Gate hängen bleibt: gotchas 0q und 0r

6. Abbauen, neu aufbauen, wiederholen

Ein weiches Teardown entfernt alles, was ein Deploy-Skript erzeugt hat, und behält alles, was Terraform gehört – du kannst also kompletten Deployment-Pfad in Minuten durchlaufen, ohne 20 Minuten Projekt-Bootstrap. Es ist zugleich die beste Generalprobe für die Demo, weil es dieselbe Sequenz ist.

./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

Evidence will nicht gelöscht – der Bucket hat eine 30-Tage-Retention-Richtlinie und lehnt die Löschung ab. Das ist genau die Immutabilität, die das Design in Anspruch nimmt – und eine abgelehinweise Löschaktion zu sehen, demonstriert es besser als jede Aussage.

„Die Deployment-Kette"

Nützlich, wenn etwas fehlschlägt und du wissen musst, welches Glied du erneut ausführen sollst:

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

Drei Dinge should you know about this chain:

• common.sh is a sourced library, not a script. It defines PROJECT_ID, REGION, IMAGE and build_image(). Es direkt run – und es passiert nichts.

• One image, four deployments: All four Auditee services run the same container; their governance posture lies complete in den gcloud run deploy flags – Labels, service account, environment variables – exactly that, was der Auditor includes. The first Script baut, the R sees can reuse.

• **build_image() skips the Build, when the image already exists. After editing auditees/main.py, a plain Redeploy ships the old image and your change, so noiseless not lands. Force it once: FORCE_BUILD=1 ./auditees/deploy-compliant.sh.

Schritte 2 und 3 funktionieren auch als Einzeleffekt (./auditor/deploy.sh deploys only the agent), and no skript is idempotent – ausführbar each time another time.

Abmelden abd wieder: exit beendet die Sitzung und entfernt den Container. Du den gleich docker run …-Befehl wieder an, um zurückzukehren – dein gcloud-Login und die installierten Packages sind still, because they live in den Volumes agv-cmidul and agv-venv, not in the container. To reset all, start fresh: docker volume rm agv-gcloud agv-venv.

Wenn etwas bricht, check before du debugging: gotchas & sharp edges – däckt alle fatalities, die wir already had, including the Scope has changed Auth-Crash, the mcp.shared.session Import-Error, the gcloud virtualenv/VPN-Failure, and why several checks on a personal project legitimately SKIPPED object.

The steps above are the Happy Path. docs/build-plan.md contains the rest: the work rules, all the obstacles in the blade, docs into what real happened, and a decision log why things are what they are.

Repositorium

scripts/

Test

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)

The live test suite drives the real pipeline and asserts, which unit test structural can’t: the run reaches the gate, nothing bet der approval before there is no remediation, the approval of the token is the chat, and every failing check carries a valid evidence hash.