Gemini Managed Agents 新增 Hooks、预算与定时触发：如何把托管 Agent 接进模型网关
Google 为 Gemini API Managed Agents 增加环境 Hooks、模型选择、预算上限、定时触发和环境管理能力。本文从真实的 API 治理问题出发，拆解这些能力与模型网关、沙箱、凭据和成本审计应该如何分工。
正文
Gemini Managed Agents 新增 Hooks、预算与定时触发：如何把托管 Agent 接进模型网关
一个普通的模型请求，通常由应用发起、模型返回，网关记录一次调用就结束了。托管 Agent 不一样：一次请求可能在远程 Linux 沙箱里运行多轮推理、执行代码、安装依赖、读写文件、访问网络，然后在几分钟甚至更久之后才完成。
7 月 28 日，Google 为 Gemini API 的 Managed Agents 增加了环境 Hooks、模型选择、免费层、预算控制和定时触发。官方文档同时把 Interactions API、环境持久化、工具调用和计费边界补得更完整。变化的重点不是“又多了几个参数”，而是 Agent 开始像一个可调度的工作负载：有生命周期、有权限、有预算，也有需要被审计的工具事件。
对已经在使用多家模型 API 的团队，问题随之变成：这些控制应该放在 Google 的托管环境里，还是放在自己的模型网关里？一个可维护的答案是分层：托管 Agent 负责执行，网关负责统一身份、路由、预算和观测，Hooks 负责沙箱内的即时策略。
这次更新到底增加了什么
Google 的公告包含五类变化：
- 默认模型变化：
antigravity-preview-05-2026默认使用 Gemini 3.6 Flash，也可以在agent_config.model中显式固定到 Gemini 3.5 Flash 或 Flash-Lite。 - 环境 Hooks：在每次工具执行前或执行后运行命令或 HTTP 处理器。前置 Hook 可以允许或拒绝工具调用，后置 Hook 适合格式化、测试和审计。
- 预算上限：通过
max_total_tokens限制一次托管 Agent 的输入、输出和思考 token 总量。达到上限时，Interaction 返回incomplete，沙箱状态保留，可以带着新预算继续。 - 定时触发：把 Agent、环境、提示词和 cron 计划绑定成持久资源，按计划自动运行，并复用同一个沙箱。
- 环境管理：Environments API 可以列出、查看和删除沙箱，不必等到默认的清理周期才回收资源。
这些能力目前仍处在公开预览范围。文档还特别提醒，托管环境默认允许不受限的出站网络访问；需要通过网络白名单或规则主动收紧边界。
先分清三个控制面
把所有逻辑都塞进 Agent 提示词，或者把所有逻辑都塞进一个 Hook，都会让系统很快失去可解释性。更清晰的分工如下：
| 控制面 | 适合处理 | 不应独自承担 |
|---|---|---|
| 模型网关 | 统一入口、供应商路由、项目配额、预算、重试、密钥、成本和跨模型审计 | 沙箱内某一条命令是否立刻放行 |
| Managed Agent / Interactions API | Agent 循环、代码执行、文件和环境状态、流式步骤、后台任务 | 团队跨应用的总预算与供应商切换 |
| Environment Hooks | 工具调用前的阻断、工具调用后的测试/格式化、沙箱内事件采集 | 取代网关的身份认证、全局限流和账单 |
例如，团队可以规定“生产项目每次任务最多消耗 50,000 token，超出必须转人工”，把这个规则放在网关；同时在沙箱内用前置 Hook 阻止 code_execution 执行危险命令。两条策略分别由不同层执行，日志也更容易解释。
Hooks 是即时闸门，不是完整安全边界
Hooks 的生命周期很简单，但语义差异很重要。
前置 Hook 可以拒绝，后置 Hook 不能撤销
pre_tool_execution 在工具真正运行前触发。脚本从标准输入读取工具名称和参数，输出 {"decision":"allow"} 或 {"decision":"deny","reason":"..."}。拒绝后，工具调用会被跳过，模型能看到拒绝原因并调整方案。
post_tool_execution 在工具完成后触发，适合运行单元测试、格式化代码或发送审计事件，但不能撤销已经发生的文件写入或网络请求。因此，涉及删除、发布、转账等不可逆操作时，阻断逻辑必须放在前置 Hook 或更下游的资源权限层。
配置匹配器要足够窄
.agents/hooks.json 支持用正则匹配多个工具。一个更容易审计的配置会只拦截高风险工具，而不是一开始对所有事件挂脚本：
{
"security-gate": {
"pre_tool_execution": [
{
"matcher": "code_execution|write_file",
"hooks": [
{
"type": "command",
"command": "python3 /.agents/hooks-scripts/gate.py",
"timeout": 10
}
]
}
]
}
}
Google 文档有一个容易被忽略的细节：如果前置脚本输出无法识别的 JSON 或普通文本，运行时会按允许处理。安全脚本必须把异常、超时和解析失败当成失败来监控，并在网关侧记录 Hook 的版本、输入摘要、决定和原因。不能把“脚本没有报错”当成“策略一定生效”。
另外，Hook 只在托管环境内部看到工具事件。它无法替代网关对调用者、项目、供应商、模型和总预算的判断，也无法阻止 Agent 通过未限制的出站网络访问其他服务。
预算控制要按任务而不是按请求看
Managed Agents 的计费不是一次输入加一次输出那么简单。官方说明，模型推理的输入、输出和 Agent 循环中的中间推理 token 都按 Gemini 标准价格计费；预览期间沙箱计算资源不另收费。以 Gemini 3.6 Flash 当前公开价格为例，标准付费层输入为每百万 token 1.50 美元，输出（含思考 token）为每百万 token 7.50 美元。具体价格和免费层资格应以计费页为准。
max_total_tokens 能避免长任务无限扩张，但它只是单个 Interaction 的上限。生产系统还需要三层预算：
- 任务预算：把仓库、用户、环境和任务类型写入路由元数据，为一次 Agent 运行设置上限。
- 项目预算：按日或按月累计所有模型、工具和重试消耗，接近阈值时降级或暂停新的触发器。
- 供应商预算：在多模型网关中给每个供应商保留配额，避免某个定时任务把一条 API 通道打满。
当 Agent 因 max_total_tokens 返回 incomplete 时，系统应把它当作“可恢复的暂停”，而不是失败重试。先保存 Interaction ID、Environment ID 和已用 token，再决定是补充预算继续、切换到成本更低的模型，还是转人工。如果简单地自动重试，最容易出现的是同一任务重复执行和成本翻倍。
定时触发让 Agent 进入后台队列
Scheduled triggers 适合依赖更新检查、夜间测试、周期性报告等任务。它也带来三个以前在交互式 Agent 中不明显的问题：
- 幂等性：同一个 cron 触发可能因网络重试产生重复运行。任务应使用业务日期、仓库提交或外部幂等键去重。
- 状态污染：触发器复用同一沙箱，文件和安装包会跨运行保留。需要明确哪些目录是缓存，哪些文件必须在每次运行前清理或校验。
- 并发与配额：多个触发器可能同时启动，网关要在队列层限制并发，并把排队时间与模型延迟分开统计。
建议把定时资源视为网关中的一种“服务账号”：触发器拥有独立身份、预算和允许访问的模型列表；它的日志至少包含 trigger ID、schedule、Interaction ID、Environment ID、模型、token、Hook 决策和最终状态。
一条可落地的路由链路
可以按下面的顺序接入，而不必一次重写现有 Agent：
- 应用或调度器先向统一网关申请任务，携带项目、仓库、数据等级和幂等键。
- 网关根据任务类型选择
gemini-3.6-flash、gemini-3.5-flash-lite或其他供应商模型，并写入预算和超时策略。需要跨供应商兜底时，在这里决定是否允许切换。 - 网关调用 Interactions API，保存 Interaction ID 和 Environment ID；继续对话时分别传递
previous_interaction_id和环境 ID，不要把两种状态混为一个会话字段。 - 环境使用网络白名单、最小权限凭据和前置 Hook。凭据应通过受控的代理注入，避免写入沙箱文件或提示词。
- 每个工具步骤回传网关的审计事件。网关按项目、任务、模型和供应商累计 token，遇到
incomplete、限流或超时再执行有限次数的恢复策略。 - 任务结束后由网关统一归档结果和成本；环境由 Environments API 主动清理，或者按照明确的保留策略复用。
这套链路的关键是把“模型怎么选”和“命令能不能执行”拆开。模型可以从 Gemini 切到其他供应商，Hook 仍然只负责沙箱工具；某个 Hook 失效时，网关的预算和权限策略仍然有效。
上线前检查清单
- 是否显式固定了模型版本，而不是依赖预览 Agent 的默认值？
- 是否给每个任务设置
max_total_tokens，并把incomplete设计成可恢复状态？ - 是否关闭或限制了默认的出站网络，只允许业务需要的域名？
- 前置 Hook 是否覆盖删除、写文件、发布和外部 API 等高风险工具？
- Hook 脚本的超时、解析失败和版本是否会进入审计日志？
- 定时触发是否具备幂等键、并发上限和独立服务身份？
- 网关是否能按项目、用户、触发器、模型和供应商拆分 token 与费用？
- 是否能通过 Interaction ID 和 Environment ID 重放一次任务的完整步骤？
- 预览功能或供应商不可用时，是否有明确的降级和人工接管路径？
Managed Agents 把“执行代码的 Agent”包装成了一个更完整的 API 资源，但它并没有消除治理工作，只是把治理点从应用代码移动到了模型网关、Interaction、环境和 Hook 之间。越早把这些边界分清，后续增加供应商、切换模型或扩大定时任务规模时，越不需要重新设计整条调用链。