Gemini API 托管 Agent：3.6 Flash、Hooks 等新功能
英文标题：Gemini API Managed Agents: 3.6 Flash, hooks, and more
Gemini API 的托管 Agent 新增 Hooks 与触发器机制，可在工具调用前后执行本地脚本或通过 HTTP 调用外部端点，用于安全拦截、代码格式化和自动化验证。AI 原生投行 OffDeal 已利用 `post_tool_execution` Hook 在远程沙箱中自动验证公司 Logo，并限制演示文稿只能使用通过审核的图片。托管 Agent 现已向免费层级项目开放，同时提供 `max_total_tokens` 预算上限，以避免多轮自主执行消耗失控，并支持在预算耗尽后从原状态继续执行。
9.8 KB
150.3 KB
中文
在此配置中：
security-gate组会在每次code_execution或write_file调用之前运行gate.py。如果脚本返回{"decision": "deny", "reason": "..."}，则会跳过该工具调用，并将拒绝原因传入模型上下文。auto-format组会在每个工具执行完成后运行auto_lint.py，以强制执行代码样式规范。- Hooks 还支持
http类型的处理器，可直接向外部端点发送 POST 请求。
关于完整的 HTTP Hook 定义及失败处理语义，请参阅 Hooks 文档。
团队已经在使用 Hooks 构建生产级验证流水线。例如，AI 原生投资银行 OffDeal 使用 post_tool_execution Hooks，在远程沙箱内运行自动化图像验证。
“OffDeal 是一家 AI 原生投资银行，而 Archie 是我们银行家每天使用的 AI 分析师。制作可供银行家直接使用的演示文稿，必须具备公司 Logo：包括买方表格、赞助商列、墓碑式交易展示网格；单份演示文稿中通常有 30 个以上 Logo，而每一个都必须对应正确的公司，拥有合适的尺寸和宽高比，包含公司名称，具备透明背景，并且放置在白色幻灯片上时具有高对比度。
在 Agent Hooks 出现之前，我们无法在 Gemini 的托管 Agent 上完成这件事：沙箱位于远程，因此我们的验证代码无处运行。有了 Hooks 后，当 Archie 写入公司列表的那一刻，post_tool_execution Hook 就会在沙箱中触发我们的流水线：获取候选 Logo、执行像素级质量检查、使用 Gemini 视觉能力验证每个 Logo，并发布一份已批准文件清单——这些文件是唯一允许进入演示文稿的图片。”
- OffDeal 创始人兼 CTO Alston Lin
成本控制与自动化功能
免费层级可用性
托管 Agent 现已在免费层级项目中可用。开发者可使用未启用有效计费项目中的 API 密钥，试验 Agent 工作流。
预算控制
由于托管 Agent 会执行多轮自主循环，复杂任务可能消耗大量 Token 预算。为防止任务失控，你可以在 agent_config 中传入 max_total_tokens，为总消耗量（输入 + 输出 + 思考）设置上限。
当 Agent 达到该限制时，执行会安全暂停，交互将返回 status: "incomplete"。环境状态会被保留，因此你可以通过传入带有新预算的 previous_interaction_id，从停止的位置继续执行。
English / 原文
In this configuration:
- The
security-gategroup runsgate.pybefore everycode_executionorwrite_filecall. If the script returns{"decision": "deny", "reason": "..."}, the tool call is skipped and the rejection reason is passed into the model’s context. - The
auto-formatgroup runsauto_lint.pyafter every tool finishes to enforce code styling. - Hooks also support
httptype handlers that POST directly to an external endpoint.
For complete HTTP hook definitions and failure handling semantics, refer to the hooks documentation.
Teams are already using hooks to build production-grade validation pipelines. For example, AI-native investment bank Offdeal uses post_tool_execution hooks to run automated image verification inside the remote sandbox.
"OffDeal is an AI-native investment bank, and Archie is the AI analyst our bankers use every day. A requirement for banker-ready decks is company logos: buyer tables, sponsor columns, tombstone grids, often 30+ logos in a single deck, every one of which must be the right company, the appropriate size and aspect ratio, contain the name, have a transparent background, and have a high contrast when placed on a white slide.
Before agent hooks, we couldn’t do this on Gemini’s managed agents: the sandbox is remote, so our validation code had nowhere to run. With hooks, a post_tool_execution hook triggers our pipeline inside the sandbox the moment Archie writes its company list, fetching candidates, enforcing pixel-level quality checks, verifying each logo with Gemini vision, and publishing a manifest of approved files that are the only images allowed into the deck."
- Alston Lin, Founder & CTO of OffDeal
Cost control and automation features
Free tier availability
Managed agents are now available on free tier projects. Developers can experiment with agentic workflows using an API key from a project without active billing.
Budget controls
Because managed agents execute multi-turn autonomous loops, complex tasks can consume significant token budgets. To prevent runaway tasks, you can pass max_total_tokens inside agent_config to cap total consumption (input + output + thinking).
When the agent reaches the limit, execution safely pauses and the interaction returns status: "incomplete". The environment state is preserved, enabling you to continue where it stopped by passing previous_interaction_id with a fresh budget.