用 Google Data Agent Kit 把 BigQuery 交给编码 Agent：插件安装、37 个官方 Skill 与 IAM 只读护栏实操

命令行类的 Agent 走插件市场，IDE 类的走扩展面板，两条路线最终拿到的是同一套 MCP 工具与技能。用 Claude Code 就加市场再装插件，Codex 是同样的两步换成自己的命令，Antigravity 一行搞定；VS Code、Cursor 及其它基于 VS Code 的编辑器在扩展面板里搜「Google Cloud Data Agent Kit」安装，提示重启就重启，装完活动栏会多一个图标。Cloud Shell 与 Cloud Workstations 已经预装，不用管这一步。团队里建议内部统一走哪条路——官方市场里还有一个指向另一仓库的 starter pack，混着装会让之后的排障与配置追溯变麻烦。

# Claude Code
claude plugin marketplace add https://github.com/GoogleCloudPlatform/data-agent-kit-plugin
claude plugin install dak@dak-marketplace

# Codex CLI
codex plugin marketplace add GoogleCloudPlatform/data-agent-kit-plugin
codex plugin add dak@dak-marketplace

# Antigravity CLI
agy plugin install https://github.com/GoogleCloudPlatform/data-agent-kit-plugin

# VS Code / Cursor / 其它基于 VS Code 的 IDE
# 扩展面板搜索 Google Cloud Data Agent Kit，安装后按提示重启 IDE

装完先做一次体检：让 Agent 列一下它现在有哪些工具，确认 MCP 条目真的挂上了。配置写了但没生效依然是最高频的故障，绝大多数情况重启一次 Agent 就好。另外记一笔：官方博客还给出了从官方插件市场安装的备选路线，它指向另一个仓库且当时标注为 beta，选用前看清版本说明。

登录这一步决定了之后所有权限判断的基准。IDE 扩展会在状态栏给出登录入口，或者用命令面板搜索登录命令；命令行插件则依赖 gcloud 的登录与应用默认凭证。关键的分岔在身份选择：用自己的账号最省事，但 Agent 就继承了你的全部权限；官方建议用服务账号并以 impersonation 的方式让 Agent 以它的身份运行，这样行级与列级安全策略照常生效，权限也收得回来。BigQuery MCP 的文档列出了所需角色：调用 MCP 工具要 MCP Tool User，跑作业要 BigQuery Job User，查数据要 BigQuery Data Viewer。

gcloud init
gcloud auth login
gcloud auth application-default login

# 团队场景：让 Agent 以专用服务账号身份运行，而不是用你的凭证
gcloud config set auth/impersonate_service_account \
  [email protected]

只做分析的话，从这三个角色起步就够了，任何带写权限的角色先别给。官方的 Security 章节还建议用 Principal Access Boundary 策略把这个服务账号限定在指定项目内，避免它凭继承关系摸到不该碰的资源。凭证尽量用短期的——Agent 跑的是长任务，长期凭证一旦落到日志或上下文里，回收窗口会非常难受。

装完插件重启 Agent，发任意提示或运行 /dak:dak-setup，它会依次问你要项目 ID、区域与要接入的服务——官方给出的可选项有十一项，包含 BigQuery 与 Knowledge Catalog。回答完按提示重启，配置才完整生效。这一步做完，你的 Agent 就等于拿到了数据目录的钥匙：它能浏览 BigQuery 的表结构、编辑 Cloud Storage 里的文件、看 Spark 集群状态，不必在 IDE 与云控制台之间来回切。服务按需选，别一次全开——每一个服务都是一批工具，工具越多，模型选错的概率与冷启动耗时都会上升。

# 装完重启 Agent，然后
/dak:dak-setup
# 依次回答：项目 ID、区域、要接入的服务（官方列出 11 项可选，
# 含 BigQuery 与 Knowledge Catalog）

# Codex 在这一步需要临时放开沙箱
codex -s danger-full-access

还有一个插件自带的行为你需要知道：Claude Code 的配置里带一个钩子，会在每次工具调用前跑一个用量统计脚本。按 README 的说明，它收集的是技能与工具在什么时间被用过，不含代码与数据取值；介意的话用环境变量关掉。企业环境在推广前先把这条写进内部说明，免得后面有人拿它当数据合规问题来问。

把「先看懂再动手」写进提示词，收益立竿见影。没有 schema 上下文的 Agent 只能猜字段名——customer_id、customerId、client_id 里可能只有一个真的存在；有了 live schema，它会先去表里看列名、类型、分区方式与元数据，再写 SQL。成本是第二道关：一条语法正确的 SELECT * 放在几 TB 的分区表上，可能扫掉你一个月的预算。官方的技能正是冲着这两点写的——BigQuery 那几条要求先应用列裁剪与提前过滤、改写结果语义前先确认、跑大查询前先说明量级；dbt 那条直接写明没有明确确认就不要跑 dbt run；Bigtable 那条要求改生产库前拿到明确确认。

先看懂再动手：说明 sales.orders 的分区字段与数据量级，
写一条按月统计营收的 SQL，先 dry run 告诉我预计扫描多少字节，
我确认后再执行。

SELECT DATE_TRUNC(order_date, MONTH) AS month,
       SUM(revenue) AS total_revenue
FROM analytics-prod.sales.orders
WHERE order_date >= DATE_SUB(CURRENT_DATE(), INTERVAL 12 MONTH)
GROUP BY month
ORDER BY month;

授权粒度也要分开：官方示例里 IDE 会在调用 MCP 工具前征求许可，并让你选「仅此一次」或「始终允许」。稳妥的做法是只读那个工具可以设为始终允许，真正会写会跑作业的那个保持每次确认。在 Claude Code 里还可以用 --disallowedTools 直接禁掉某个工具——但要先确认插件注册的真实工具名，别照抄别人的配置。

这是整套设计里最值得抄的一点。技能里的 accidental-data-loss-prevention 以「STOP AND VERIFY」开头，要求 Agent 在 DROP TABLE、TRUNCATE、没有 WHERE 或带 WHERE 1=1 的 DELETE、删生产存储桶、gcloud projects delete、销毁 KMS 密钥这些不可逆动作前停下、说明影响、拿到明确同意。但那是文本，Agent 可以选择不照做，也可能被数据里嵌的文本带偏。强制的那一层在 IAM：用 deny 策略在读只读属性为假的条件下拒绝 MCP 工具调用权限，组织、文件夹、项目三级都能挂。

# 官方文档给出的条件写法
api.getAttribute('mcp.googleapis.com/tool.isReadOnly', false) == false

# 效果：拒绝 mcp.googleapis.com/tools.call
# 生效层级：组织 / 文件夹 / 项目
# 配套属性：resource.service、tool.name（仅 gcloud 可用）

# deny 规则示意（字段名以你所用版本的官方文档为准）
denyRule:
  deniedPermissions:
    - mcp.googleapis.com/tools.call
  denialCondition:
    expression: |
      api.getAttribute('mcp.googleapis.com/tool.isReadOnly', false) == false

这条策略的价值在于它不依赖模型的记忆与善意：每一次工具调用都要过一遍权限判断。对比之下，写在 system 提示词里的规则只在模型记得住的时候才生效。想做更细的管控，就用配套属性按服务名或工具名再切一层——只是这两个属性目前只在 gcloud 里可用，控制台看不到。

官方与社区已经把边界说得很清楚，照着收尾即可。三条限制：被 deny 的工具仍出现在 tools/list 里；这套控制只覆盖 Google Cloud 的 MCP 服务器，管不到你接的其它 MCP；resource.service 与 tool.name 只有 gcloud 有，控制台缺失。一条未解难题：工具结果里没有幂等键与提交状态，一次超时的写入到底有没有提交，谁都说不清——在 Agent 会因为超时重试的环境里，这是比授权更难的那道关，得靠你自己的重试语义与对账来兜。

# 关掉插件自带的用量统计上报
export DO_NOT_TRACK=1

# Claude Code 侧再兜一层：装完先确认真实工具名，再禁掉你不希望被用到的
claude --disallowedTools "mcp__dak__execute_sql"

推广节奏建议是：从只读开始，让 Agent 先看懂数据、给建议、写查询但不执行；人工确认跑通一段时间、审计记录攒够了，再逐项放开写权限。这条路径与有经验的运维给的建议一致——干净的审计轨迹会让后续扩权容易得多，反之，一上来就给写权限，出过一次事故后整个工具都会被叫停。