如何给AI Agent加安全护栏Google Antigravity SDK Hooks与Policies策略系统完整指南【免费下载链接】antigravity-sdk-pythonA Python library for building AI agents that leverage the full power of Google Antigravity.项目地址: https://gitcode.com/gh_mirrors/an/antigravity-sdk-python如果你正在用Google Antigravity SDK构建自己的 AI Agent一定会担心一个问题让 Agent 执行 shell 命令、读写文件时如何防止它闯祸答案就藏在 SDK 内置的Hooks 钩子与Policies 策略系统中——这是一套声明式、优先级排序的安全护栏机制能让你精确控制 Agent 的每一个工具调用。本文将用通俗的语言带你从零看懂这套系统并给出可直接上生产的安全配置模板 ️。一、为什么 AI Agent 需要安全护栏想象你雇了一位执行力极强、但有时会理解偏差的实习生你说清理一下项目它可能真的去执行rm -rf你说看看配置它可能悄悄改写了生产环境的密钥文件。AI Agent 拥有run_command、edit_file、create_file等 powerful 工具默认行为如果不加约束风险极高。Google Antigravity SDK 的解法分两层层级机制作用生命周期层Hooks 钩子在会话、轮次、工具调用等关键节点拦截实现观察、审批、改写决策层Policies 策略用声明式规则表达允许 / 拒绝 / 询问用户自动转化为钩子执行核心源码位于 google/antigravity/hooks/ 目录官方架构说明见 google/antigravity/hooks/README.md。二、Hooks 钩子Agent 生命周期的检查站1. 三种钩子类型各司其职SDK 把所有钩子严格分为三类定义在 google/antigravity/hooks/hooks.py类型能改数据能阻断执行典型用途代表钩子Inspect 观察型❌❌日志、监控、审计PostToolCallHook、PostTurnHookDecide 决策型❌✅权限校验、安全护栏PreToolCallDecideHook、PreTurnHookTransform 转换型✅✅数据清洗、错误恢复OnToolErrorHook、OnInteractionHook记忆口诀观察型只看不动决策型只批不改转换型又看又管。2. 九大生命周期钩子点一览SDK 提供了 9 个开箱即用的装饰器覆盖 Agent 的完整生命周期钩子装饰器触发时机类型on_session_start/on_session_end会话开始 / 结束观察型pre_turn用户提交 Prompt 之后、模型响应之前决策型post_turn模型完成一轮回复后观察型pre_tool_call_decide每次工具调用执行前决策型 ⭐post_tool_call工具调用完成后观察型on_tool_error工具执行失败时转换型on_interactionAgent 需要向用户提问时转换型on_compaction上下文压缩上下文窗口超限发生时观察型⭐ 其中pre_tool_call_decide是安全护栏的主战场Agent 每次调用工具前都会经过它你可以返回允许或拒绝并附上理由。3. 一个 10 行代码的最小钩子示例完整可运行示例见 examples/getting_started/hooks.pyfrom google.antigravity.hooks import hooks hooks.pre_tool_call_decide async def guard(data): # 危险命令一律拒绝 if rm -rf in str(data.args): return types.HookResult(allowFalse, message禁止执行删除命令) return types.HookResult(allowTrue)把这个函数放进LocalAgentConfig(hooks[guard])护栏即刻生效。4. 执行顺序与安全细节google/antigravity/hooks/hook_runner.py 中的HookRunner强制规定执行顺序避免检查时通过、执行时被篡改TOCTOU漏洞先跑 Decide 钩子审批 → 再执行工具 → 最后跑 Inspect 钩子记录。另外注意几个贴心设计子 Agent 也受管控子 Agent 轨迹内的每一次工具调用父级的钩子同样会触发策略对子 Agent 一视同仁Fail-Closed 失败关闭钩子评估过程中一旦抛异常系统默认拒绝执行宁可错杀不放过分层上下文钩子之间可通过SessionContext会话级→TurnContext轮次级→OperationContext单次操作级的层级化键值共享状态实现跨事件的状态传递与日志关联。三、Policies 策略系统声明式的安全规则引擎手写钩子虽然灵活但日常 80% 的需求其实只有一句话这个工具能不能用 为此 SDK 在 google/antigravity/hooks/policy.py 提供了声明式策略 API三种决策对应三种交通灯决策含义构造函数DENY直接拒绝并返回拒绝理由policy.deny(tool, when..., name...)ASK_USER暂停执行向用户征求批准policy.ask_user(tool, handler...)APPROVE无条件放行policy.allow(tool, when...)1. 优先级模型安全永远优先多条策略冲突时按具体度 安全性排序共9 级优先级同级内首个命中即短路优先级范围决策示例1具体工具DENYdeny(run_command)2具体工具ASK_USERask_user(run_command)3具体工具APPROVEallow(run_command)4前缀通配DENYdeny(server_cfg)5前缀通配ASK_USERask_user(server_cfg)6前缀通配APPROVEallow(server_cfg)7全局通配DENYdeny_all()8全局通配ASK_USERask_user(*)9全局通配APPROVEallow_all()设计哲学一目了然越具体越优先越危险越优先。即使你写了allow_all()一条具体的deny(run_command, when...)依然能拦住危险操作 2.when谓词按参数内容精准拦截策略不仅能管哪个工具还能管什么样的参数。when参数接收一个判断函数拿到工具调用的完整参数policies [ # 默认全拒 policy.deny_all(), # 放行读目录 policy.allow(list_dir), # 允许执行命令但带 rm 的一律拦截 policy.allow(run_command), policy.deny(run_command, whenlambda args: rm in args.get(CommandLine, ), nameblock-rm), # 写关键文件前先问用户 policy.ask_user(edit_file, whenlambda a: a.get(path, ).endswith(.key), handlermy_approval_fn), ] config LocalAgentConfig(policiespolicies)这段默认拒绝 逐项放行的经典姿势完整可运行版本见 examples/getting_started/policies.py——它演示了拦截rm -rf、审批production.key文件写入、封禁自定义工具等 5 个场景。⚠️ 安全提示如果when谓词执行时抛异常策略会视为命中fail-closed确保安全底线不被意外绕过。3. 内置安全预设三行代码搞定常见场景预设函数行为适用场景policy.confirm_run_command()拒绝run_command其余放行SDK 默认策略开箱即用policy.allow_all()放行所有工具调用仅限本地可信开发环境policy.deny_all()全拒配合具体allow使用生产环境白名单模式policy.workspace_only(paths)文件工具限制在工作目录内防止 Agent 越界读写系统文件policy.safe_defaults(handler)只读工具放行写操作逐一询问交互式会话值得了解的是SDK默认就是保守的——LocalAgentConfig未指定策略时自动启用confirm_run_command()即 shell 命令默认被拒。想解锁自主执行能力必须显式传入policies[policy.allow_all()]。四、选型指南Deny 工具 vs 禁用工具新手最容易混淆的一点policy.deny()和CapabilitiesConfig.disabled_tools都能禁止工具但作用层级完全不同机制作用层级模型看得到工具吗最佳用途disabled_tools模型上下文构建前❌ 完全不可见工具与 Agent 职责无关彻底移除policy.deny()运行时逐次决策✅ 可见但被拒条件性限制按参数、按审批一句话原则Agent 永远不需要的工具 → 禁用需要但要看情况才放行 → 用策略。详细对比参见 skills/google-antigravity-sdk/references/safety_policies.md。五、生产环境推荐模板Deny by Default参考官方安全策略文档给出的默认拒绝模板这是最稳妥的上生产姿势policies [ policy.deny_all(), # 1. 默认全拒 policy.allow(view_file), # 2. 只放行只读 policy.allow(code_search), policy.ask_user(run_command, handlermy_approval), # 3. 高危操作人工审批 ] config LocalAgentConfig(policiespolicies)配套建议交互会话中用ask_user挂上人工确认终端 y/n 确认可参考 examples/getting_started/human_in_the_loop.py自动化流水线中用程序化审批函数替代人工实现无人值守但仍有闸门 上线前用examples/getting_started/policies.py的四段式验证流程自测安全命令放行、危险命令拦截、关键文件触发审批、自定义工具封禁全部符合预期再发车。六、总结给你的 Agent 上三道锁锁机制一句话总结第一道Hooks在 Agent 生命周期的 9 个检查站拦截观察、审批、改写第二道Policies9 级优先级的声明式规则DENY 优先、首个命中短路第三道Fail-Closed任何评估异常一律拒绝安全底线绝不失守Hooks 是手Policies 是规则两者叠加构成了 Google Antigravity SDK 最完整的安全护栏体系。掌握它们你的 AI Agent 就能既放手干活、又不越雷池 【免费下载链接】antigravity-sdk-pythonA Python library for building AI agents that leverage the full power of Google Antigravity.项目地址: https://gitcode.com/gh_mirrors/an/antigravity-sdk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
