代理治理审计器

一个用于审计其他AI代理合规性的ADK代理——它能够发现GCP项目中运行的AI工作负载，包括那些无人登记过的，针对版本化策略包执行11项确定性检查，并生成映射到欧盟《人工智能法案》（第6、9、11、12、13、15、50条）和SOC 2信任服务标准的审计就绪证据包。每项发现都附带不可篡改的证据引用（GCS + SHA-256）。每次写入操作都需人工批准。

每项策略都说明了为何映射到其所声称的条款——并且有两项映射在审查中因过度延伸而被移除，因为过度映射正是让合规报告失去可信度的最快方式。该工具审计的是缺失声明，而非推断违法行为：“未记录风险分类”是可核查的，也是审计师会记录的问题；而“该代理属于附件III高风险类别”则是法律判断，该工具无权作出。

为Gemini Enterprise黑客松而构建——第2赛道（高代码：ADK + 自定义MCP服务器 + Gemini Enterprise Agent Platform上的Agent Runtime）。

为什么

欧盟《人工智能法案》的时间表发生了变化，这让问题变得更加紧迫而非缓解。《欧盟条例（EU）2026/1744》（即“人工智能数字综合法案”，2026年7月27日生效）将附件III高风险义务推迟至2027年12月2日。推迟，但并未取消——而与此同时，第50条透明度义务、第5条禁止性实践以及通用人工智能提供者义务已于今日生效，违规罚款最高可达3500万欧元或全球营业额的7%。

因此，企业大约还有十六个月来为高风险系统建立证据链，而同时已经需要为当前正在运行的代理承担义务。这两者都取决于回答审计师总会问的一个问题——“你们有哪些AI系统，能否证明它们受到治理？”——而诚实的答案通常是*“我们也不完全确定。”*

这个工具就是用来回答这个问题的，并且附带证据。

Related MCP server: EU AI Act Compliance MCP Server

工作原理

上图展示了整体架构。核心设计原则（完整架构文档）：

• LLM绝不决定合规性——代码决定。 通过/未通过由MCP工具代码计算；代理仅负责编排、确定优先级和叙述说明。变更防护机制会在分类阶段试图翻转状态时中止整个运行。

• 证据驱动，由构造保证。 没有evidence_ref的发现项在数据模型中不可能存在——模式定义会拒绝它。

• 默认只读。 唯一的写入路径（补救指令）需要人工签发的单次使用批准令牌，并在服务端强制执行，因此服务器绝不信任代理关于“已获人工批准”的声明。

• 审计器自我审计——它以自身Agent Identity部署，并被自己的扫描发现，在11项检查中通过6项。

一次端到端的审计

设计中有两点是刻意的，而非装饰。分类阶段完全不调用任何MCP工具——真正进行推理的这一步被隔离在流程之外，无法触达外部资源。并且在写入任何内容之前，运行会挂起：此时令牌尚不存在，因此即使代理尝试写入，服务器也会拒绝。

发现机制基于行为，而非名称匹配

这个产品成败的关键问题是*“你是否能发现一个名字不叫agent-something的代理？”* 仅靠名称匹配的答案是“不能”——它会漏掉customer-insights-api，却会把名为agent-proxy的nginx误报为代理。因此，工作负载的分类基于五种信号，每个候选对象都会报告置信度和理由：

第一点正是关键：一个与模型通信的工作负载无法靠一个平淡无奇的名字隐藏自己。演示集群中特意包含了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

在仓库根目录打开终端——即包含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"

每次登录都会打印一个URL供你在浏览器中打开，并要求你将验证码粘贴回来。在第二个同意页面上，勾选每一个权限框（“全选”）——部分同意会以令人困惑的Scope has changed崩溃告终，而且你需要cloud-platform作用域才能让任何功能正常工作。在打印出ADC OK之前不要继续。

→ 如果同意页面报错：陷阱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错误：陷阱0c

4. 配置基础设施

创建已启用的API、服务账号（包括那个故意过度授权的“流氓”账号）、证据存储桶、预算、审计日志接收器和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 在账单预算上失败，这在某些账户上是意料之中的——预算需要账户级权限，而不是项目级权限。在 Console 中创建一次，然后 terraform import，或者注释掉相关资源。别浪费一个晚上。

→ 如果第一次 apply 就遇到一堵 SERVICE_DISABLED 的墙：gotcha 0e —— 通常重新运行一次就好了

5. 部署一切

一条命令就能在 Terraform 基线之上构建并部署整个环境，按依赖顺序执行，并打印每个阶段的耗时。实测：整个四代理集群耗时 6 分 57 秒。

./scripts/deploy-all.sh

然后在 Gemini Enterprise 应用中打开它（Agents → 3-dot → 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 或在门禁处卡住：gotcha 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 是一个被 source 的库，不是脚本。 它定义 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 虚拟环境/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)

在线测试套件驱动真实的流水线，并断言单元测试在结构上无法验证的事情：运行确实到达了门禁，在人工批准之前没有任何修复被执行，批准 token 从未到达聊天层，并且每一个失败发现都带有有效的证据哈希。