生产级托管代理：钩子、预算与沙箱可靠性实战

2026 年 7 月 28 日，Google 宣布 Gemini API 的 Managed Agents 默认升级为 Gemini 3.6 Flash，并带来三件生产级利器：环境钩子（在代理每次工具调用前后运行你的脚本）、预算控制与定时触发、以及免费层。加上此前发布的后台任务与远程 MCP Server 集成，一个 API 调用就能在隔离沙箱里协调推理、代码执行、装包、文件管理和网页检索。本文用真实代码演示如何把这些能力接进生产。

一个 API 调用，隔离沙箱里完成全部工作

一、一个 API 调用跑完整代理

代码示例1 展示了 Managed Agents 的用法：client.interactions.create 一次调用，代理在远程沙箱里审计依赖、升级过期包、跑 npm test 验证构建。默认模型已经切到 Gemini 3.6 Flash（antigravity-preview-05-2026），不需要改任何代码；想省钱可以显式指定 gemini-3.5-flash-lite。对于不想自建代理基础设施的团队，这是 2026 年最快的上手路径。

# One API call coordinates reasoning, code execution, package
# installation, file management, and web retrieval in a sandbox.
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
  agent: "antigravity-preview-05-2026",
  input: "Audit all dependencies in package.json, upgrade outdated packages, " +
         "and verify the build by running npm test.",
  environment: "remote",
  agent_config: {
    type: "antigravity",
    model: "gemini-3.5-flash-lite",   // pin a cheaper model explicitly
  },
});

console.log(interaction.output_text);
// Gemini 3.6 Flash is the new default; no code changes required.

二、环境钩子：拦截、检查、审计

环境钩子让代理的每次工具调用都过你的代码。代码示例2 的 .agents/hooks.json 定义了两组钩子：security-gate 组在每次 code_execution 或 write_file 之前运行 gate.py；auto-format 组在每个工具结束后跑 auto_lint.py 强制代码风格。matcher 支持正则，可以用 | 匹配多个工具或用 * 全量匹配，还支持 http 类型直接把事件 POST 到外部端点。

# Environment hooks: run your own scripts before/after every tool call.
# .agents/hooks.json
{
  "hooks": [
    {
      "matcher": "code_execution|write_file",
      "event": "pre_tool_execution",
      "group": "security-gate",
      "command": "python gate.py"
    },
    {
      "matcher": "*",
      "event": "post_tool_execution",
      "group": "auto-format",
      "command": "python auto_lint.py"
    }
  ]
}
# The matcher supports regex: "|" targets multiple tools, "*" catches all.
# Groups run in parallel; http type handlers can POST to external endpoints.

三、拒绝即上下文：让代理自我纠错

代码示例3 是 gate.py 的 deny 逻辑：代理试图往 secrets/ 目录写文件时，钩子返回 {"decision": "deny", "reason": "..."}，工具调用被跳过，拒绝原因会进入模型上下文——代理可以据此自我修正。这比事后审计高一个量级：不是记录「发生了什么」，而是决定「什么允许发生」。

# gate.py — deny a tool call before it executes
#!/usr/bin/env python3
import json, sys

payload = json.load(sys.stdin)
tool = payload.get("tool", "")
args = payload.get("args", {})

if tool == "write_file" and "secrets/" in args.get("path", ""):
    print(json.dumps({
        "decision": "deny",
        "reason": "Writing into secrets/ is forbidden for agents"
    }))
    sys.exit(0)

print(json.dumps({"decision": "allow"}))
# A deny decision skips the tool call and passes the reason
# into the model's context — the agent can self-correct.

四、预算、定时与 MCP：生产三件套

代码示例4 展示了生产化配置：max_cost_usd、max_steps、max_tokens 把代理关进成本笼子；cron 定时触发让夜间维护任务自动跑；远程 MCP Server 让代理读 Postgres、查 Jira。真实案例是 AI 原生投行 Offdeal：用 post_tool_execution 钩子在沙箱里自动验证每份 deck 里 30+ 个公司 Logo 的正确性——每个 Logo 都必须公司对、尺寸对、透明背景、白底高对比。

# Budget controls + scheduled triggers keep managed agents in bounds
# (conceptual config for the Gemini API)
{
  "agent": {
    "model": "gemini-3.6-flash",
    "budget": {
      "max_cost_usd": 25.0,
      "max_steps": 200,
      "max_tokens": 200000
    },
    "schedule": {
      "cron": "0 2 * * *",          // nightly maintenance window
      "timezone": "UTC"
    },
    "mcp_servers": ["remote:postgres", "remote:jira"]
  }
}
# Offdeal, an AI-native investment bank, uses post_tool_execution hooks
# to verify 30+ company logos per deck automatically inside the sandbox.

五、给团队的落地建议

第一，从默认模型开始跑通一个真实任务，再按成本需求换 Flash-Lite；第二，先写 security-gate 钩子（挡 secrets 写入、挡高危命令），再补 auto-format 钩子；第三，所有代理任务都配预算上限；第四，把重复的夜间任务改成定时触发；第五，用远程 MCP 接入内部系统时，确保钩子仍然覆盖这些工具调用。

六、总结

托管代理把「可靠」从口号变成了基础设施：沙箱隔离执行环境，钩子在工具调用前后设卡，预算把成本锁死，定时器把运维自动化。加上默认模型升级到 3.6 Flash，2026 年的托管代理第一次让人觉得「可以放心交给它跑生产任务」——前提是你把钩子和预算配好。