Agent Governance Auditor

Агент на базе ADK, который проверяет других ИИ-агентов на соответствие требованиям — находит ИИ-нагрузки в GCP-проекте, включая те, которые никто не регистрировал, выполняет 11 детерминированных проверок соответствия на основе версионированного пакета политик, и готовит готовый к передаче аудитору пакет доказательств, сопоставленный с EU AI Act (ст. 6, 9, 11, 12, 13, 15, 50) и критериями Trust Services из SOC 2. Каждая находка снабжается неизменяемой ссылкой на доказательство (GCS + SHA-256). Каждая операция записи получает одобрение человека.

Каждая политика объясняет, почему она связана со заявленными статьями, — а два сопоставления были удалены при ревью за излишне широкое толкование, потому что именно избыточное liaсопоставление быстрее всего дискредитирует комплаенс-отчёт. Инструмент проверяет отсутствие обязательных деклараций, но никогда не делает выводов о предполагаемых юридических нарушениях: «нет документированной классификации риска» — это проверяемо, и именно это фиксирует аудитор; «данный агент является высокорисковым по Приложению III» — это правовое суждение, которое инструмент выносить не вправе.

Создано для хакатона Gemini Enterprise — направление Stream 2 (High-Code: ADK + собственный MCP-сервер + Agent Runtime на платформе Gemini Enterprise Agent Platform).

Зачем

График введения EU AI Act сдвинулся, и это делает проблему более острой, а не менее. Регламент (ЕС) 2026/1744 («Цифровой омнибус по ИИ», вступил в силу 27 июля 2026 года) перенёс высокорисковые обязательства из Приложения III на 2 декабря 2027 года. Отложил, — но не отменил; а тем временем обязательства по прозрачности из статьи 50, запрещённые практики из статьи 5 и обязательства провайдеров GPAI действуют уже сегодня, штрафы достигают €35 млн или 7% глобального оборота.

Таким образом, у компаний есть примерно шестнадцать месяцев, чтобы сформировать доказательную цепочку для высокорисковых систем, уже неся текущие обязательства по агентам, которые работают прямо сейчас. И то и другое упирается в один вопрос, который аудиторы задают всегда, — «какие компьютерные системы у вас есть и можете ли вы доказать, что они регулируются?» — на который честный ответ обычно звучит так: «мы не до конца уверены».

Этот инструмент отвечает на этот вопрос — с доказательствами.

Related MCP server: EU AI Act Compliance MCP Server

Как это работает

Диаграмма выше показывает существующую картину. Ключевые принципы проектирования (полная архитектура):

• Соответствие решает не LLM — код. Подход Pass/fail вычисляется в коде MCP-инструментов; агент оркеструет, выставляет приоритеты и комментирует. Защита от изменений останавливает любой запуск, где триаж пытается изменить статус.

• Привязка по построению. Находка без указанного evidence_ref не может существовать в модели данных — схема её отклоняет.

• Только чтение по умолчанию. Единственный путь записи (порядок исправления) требует одноразовый токен одобрения, созданный человеком, и проверяется на сервере — поэтому сервер никогда не доверяет утверждению агента о том, что человек дал добро.

• Аудитор проверяет самого себя — он разворачивается под собственным Agent Identity и обнаруживает сам себя же в собственном обследовании, проходя 6 из своих 11 проверок.

Один аудит: от начала до конца

В этой схеме две вещи — это суть дизайна, а не украшение. Триаж не обращается вообще ни к какому инструменту MCP — единственному ноге, выполняющей реальные рассуждения, закрыт доступ к чему-либо вне процесса. Запуск приостанавливается, прежде чем что-либо будет записано: токена ещё нет, и сервер отклонил бы запись, даже если бы агент попытался её выполнить.

Обнаружение основано на поведении, а не на совпадении имён

Вопрос, от которого зависит жизнь продукта: *«можете ли вы найти агент, который не называется agent-something?*» Подбор по именам — что он не найдет customer-insights-apiи заточит nginx с именемagent-proxy`. Поэтому рабочая нагрузка классифицируется по специальным признакам, с указанием достоверности и причины по каждой находке:

Первый пункт — главный: та рабочая нагрузка что ведёт диалог с моделью, не может спрятаться за скучным именем. В демонстрационном флоте есть customer-insights-api — настоящий ADK-агент без агентного имени и без меток — именно для того, чтобы это утверждение можно было проверить, а не просто принять на веру.

Что охвачено, а что — нет

Обнаружение продвинулось шире, чем аудит, — и в отчёте всегда указано, где граница:

Последняя строка — самая честная. Рабочая нагрузка, обращающаяся к внешнему провайдеру, никогда не появляется в журналах Google, и аудитор это не ловит, — он проверяет, включены ли механизмы контроля, которые должны были этого избегать, и докладывает, если они выключены. GOV-NET-007 — именно такая проверка.

Гарантированный минимум: использование модели требует аутентификации, а аутентификация логируется. Поэтому худший вариант — «вот объект, который мы не можем идентифицировать — смотрите руками», но никогда не тишина.

Быстрый старт

Все разработки происходят внутри контейнера — Ubuntu 26.04 LTS с gcloud, Terraform, Node и зафиксированным Python 3.12. На свою машину вы ничего не устанавливаете, а окружение идентично на macOS, Windows (Docker Desktop или WSL2) и Linux.

Необходимые условия: запущенный Docker (OrbStack, Docker Desktop или WSL2) и клонированный репозиторий. Больше ничего.

1. Соберите образ и получите shell

Откройте терминал в корне репозитория — в папке, содержащей этот README и папки 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

Что означают эти флаги:

Вашим приглашением станет ubuntu@…:/workspace$. Всё, что вы внутри.

2. Разовая настройка и вход в учётную запись

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"

Каждый раз при входе печатается ссылка для открытия в браузере, а вас просят вставить код назад. На втором экране согласия отметьте все разрешения («Select all») — неполная авторизация упадет со странной ошибкой Scope has changed, а для работы нужна область cloud-platform. Не двигайтесь дальше, пока не появится ADC OK.

→ если экран согласия выдаёт ошибку: gotcha 0b

3. Создайте 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

Биллинг должен быть привязан докаком Terraform — для включения API это необходимо.

→ если при создании проекта с идентификатором 764086051850 вы получите 403: gotcha 0c

4. Подготовьте инфраструктуру

Создаёт включённые API, служебные учётки (включены специально расширенную по правам «rogue» учётку), приёмник журнала аудита а также bucket с землю for evidence, браузер, budget, audit-log sink и репозиторий 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

Если apply падает на биллинговом бюджете, это ожидаемо для некоторых аккаунтов — для бюджетов нужно разрешение на уровне биллингового аккаунта, а не проекта. Создайте его один раз в консоли и выполните terraform import или закомментируйте ресурс. Не тратьте на это вечер.

→ если первый apply падает со стеной SERVICE_DISABLED: gotcha 0e — обычно достаточно просто перезапустить

5. Разверните всё

Одна команда собирает и разворачивает всю инфраструктуру поверх базового уровня Terraform в порядке зависимостей, выводя затраченное время на каждом этапе. Замерено: 6м 57с для полного парка из четырёх агентов.

./scripts/deploy-all.sh

Затем откройте приложение Gemini Enterprise, которое он зарегистрировал (Agents → 3-точечный → Preview), и отправьте:

Проведите аудит соответствия этого проекта.

Выполнение останавливается на этапе утверждения. Ответьте APPROVE, чтобы авторизовать исправление, или APPROVE <finding id> для подмножества, или DECLINE. (GE и Agent Runtime Playground не отображают кнопку подтверждения для экспериментального примитива подтверждения ADK, поэтому шлюз также принимает вводимый ответ.)

Предпочитаете терминал или хотите управлять без браузера:

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

→ если развёрнутый агент выдаёт 401 или зависает на шлюзе: gotchas 0q и 0r

6. Разборка, пересборка, повторение

Мягкая разборка удаляет всё, что создал скрипт развёртывания, и сохраняет всё, чем владеет Terraform, — так что вы можете прогнать весь путь развёртывания за считанные минуты без 20-минутной начальной загрузки проекта. Это также лучшая репетиция демо, потому что последовательность та же.

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

Доказательства намеренно не удаляются: на бакете действует политика хранения в 30 дней, и он откажет. Это та самая неизменяемость, о которой заявляет дизайн, — и наблюдение за отклонением удаления демонстрирует её лучше любых утверждений.

Цепочка развёртывания

Полезно, когда что-то падает и нужно знать, какое звено перезапустить:

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

Три вещи, которые стоит знать об этой цепочке:

• common.sh — это подключаемая библиотека, а не скрипт. Она определяет PROJECT_ID, REGION, IMAGE и build_image(). Прямой запуск ничего не делает.

• Один образ, четыре развёртывания. Все четыре аудируемых сервиса запускают один и тот же контейнер; их политика соответствия полностью определяется флагами gcloud run deploy — метками, сервисным аккаунтом, переменными окружения, — именно это и проверяет аудитор. Поэтому первый скрипт собирает, а остальные переиспользуют.

• build_image() пропускает сборку, если образ уже существует. После редактирования auditees/main.py обычное повторное развёртывание отправит старый образ, и ваше изменение молча не применится. Принудительно один раз: FORCE_BUILD=1 ./auditees/deploy-compliant.sh.

Шаги 2 и 3 также работают автономно (./auditor/deploy.sh повторно разворачивает только агента), и каждый скрипт идемпотентен — повторный запуск безопасен.

Выход и возврат: exit завершает сеанс и удаляет контейнер. Повторно выполните ту же команду docker run …, чтобы вернуться, — ваш вход в gcloud и установленные пакеты всё ещё там, потому что они хранятся в томах agv-gcloud и agv-venv, а не в контейнере. Чтобы стереть всё и начать с чистого листа: docker volume rm agv-gcloud agv-venv.

Когда что-то ломается, загляните в gotchas & sharp edges перед отладкой — там описаны ошибки, с которыми мы уже столкнулись, включая сбой аутентификации Scope has changed, ошибку импорта mcp.shared.session, сбой gcloud virtualenv/VPN и почему несколько проверок обоснованно сообщают SKIPPED в личном проекте.

Шаги выше — это счастливый путь. docs/build-plan.md содержит остальное: правила эксплуатации, все грабли, на которые мы реально наступили, и журнал решений, объясняющий, почему всё устроено именно так.

Репозиторий

scripts/

Тестирование

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)

Живой набор тестов запускает реальный конвейер и проверяет то, что модульные тесты структурно не могут: что выполнение доходит до шлюза, что ничего не исправляется до одобрения человеком, что токен одобрения никогда не попадает в чат и что каждая неудачная находка содержит корректный хэш доказательства.