把工具调用做成闭环：Gemini Function Calling 的工程要点

译者按：本文根据 Google AI for Developers 官方文档《Function calling with the Gemini API》整理翻译，聚焦把自然语言请求安全地连接到外部 API 的工程流程。

一、函数调用解决什么问题
函数调用让模型在需要时选择预先声明的函数，并生成结构化参数。应用可以用它执行真实动作（如预约、发邮件）、补充外部知识（数据库、业务 API），或扩展模型能力（计算、制图）。模型负责提出调用建议，真正执行函数仍由应用负责。

二、四步闭环
1. 定义函数声明：给出唯一名称、用途描述、参数类型、属性和必填字段。
2. 把声明连同用户请求发送给模型。
3. 应用读取 function_call 的名称和 arguments，校验参数后执行本地代码或外部 API。
4. 将函数结果作为工具响应回传，让模型生成面向用户的自然语言答复。这个往返可以重复多轮。

三、并行与组合调用
互不依赖的工具适合并行调用，例如同时查询多个库存；有依赖关系的操作则应组合调用，例如先查地点，再按地点查询天气。编排层应记录每次调用的 call id、输入、输出和错误，便于重试与审计。

四、工具选择模式
Gemini 文档提供 auto、any、none 和 validated 等模式：auto 由模型决定是否调用，any 强制选择函数，none 禁止调用，validated 用于约束参数符合声明。生产环境通常让模型先处于 auto，再在高风险动作前切换到更严格的 allowlist。

五、上线前的安全清单
不要把模型输出直接拼成命令；对参数做类型、范围和权限校验；为外部 API 设置超时、幂等键与重试上限；将敏感字段脱敏记录；在发送邮件、扣款、删除数据等动作前增加人工确认。工具描述要清楚，避免把多个副作用塞进一个函数。

六、一个最小实现思路
以 schedule_meeting 为例，声明 attendees、date、time、topic 四个必填参数。收到 function_call 后，服务端先验证日期与参与者权限，再调用日历系统；成功后回传会议编号，失败则回传可解释的错误。这样模型只是可靠的决策接口，业务系统仍掌握最终控制权。

原文：Google AI for Developers，Function calling with the Gemini API
https://ai.google.dev/gemini-api/docs/function-calling