配置可校验的 Gemini 函数调用闭环

一句话结论

Google 的函数调用文档直接以 model="gemini-3.8-flash" 展示 Python 配置：模型只提出函数名称和结构化实参，应用负责校验并执行函数，再将 function_result 通过 previous_interaction_id 回传。该机制适合把自然语言请求接入受控的外部数据或 API；它不会替应用授予工具权限。

适用场景

• 适合的任务：查询外部数据、创建图表、预约等需要应用调用 API 的任务；也适合把多个独立函数并行调用，或按依赖顺序串联调用。

• 不适合的任务：把模型输出直接当成本机命令、付款、发送消息或删除操作；这些动作必须由应用侧白名单、参数校验和人工授权控制。

• 适用的模型版本：本文只记录该页示例明确写出的 gemini-3.8-flash；不要把其他客户端的模型别名或 SDK 映射当作同一证据。

• 适用的客户端、Agent 或 API：Google Gemini API 的 Interactions API；页面说明 Interactions API 已正式发布，并建议用它访问最新功能和模型。其他 SDK 需自行核对字段映射。

• Preview 状态：该函数调用页面未将此流程标为 Preview；这不等于所有 SDK 版本、地区或第三方平台都同步可用，部署前仍需做 smoke test。

可直接使用的内容

1. 工具声明：把能力收敛为可校验的契约

下面保留 Google Python 示例的核心字段，并以只读天气查询作为安全起点：

from google import genai

weather_function = {
    "type": "function",
    "name": "get_current_temperature",
    "description": "Gets the current temperature for a given location.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The city name, e.g. San Francisco",
            },
        },
        "required": ["location"],
    },
}

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What's the temperature in London?",
    tools=[weather_function],
)

for step in interaction.steps:
    if step.type == "function_call":
        print(f"Function to call: {step.name}")
        print(f"Arguments: {step.arguments}")

声明的最小字段是：type="function"、唯一的 name、清楚的 description、parameters（通常是 object）以及必填参数名组成的 required。参数类型、枚举和值域应与真实函数一致，避免把自然语言描述当作权限控制。

2. 四步调用链：模型提议，应用执行

用户输入 + 工具声明
        ↓
Interactions API 返回 function_call(name, arguments, call_id)
        ↓
应用白名单校验参数，并执行自己的函数
        ↓
以 function_result 回传
        ↓
模型生成最终用户回答，或继续提出下一次工具调用

官方文档明确：模型本身不会执行函数。以下示例展示完整的应用侧闭环；get_current_temperature 的实现应替换为你自己的、已授权的 API 客户端：

import json
from google import genai

weather_function = {
    "type": "function",
    "name": "get_current_temperature",
    "description": "Gets the current temperature for a given location.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The city name, e.g. San Francisco",
            },
        },
        "required": ["location"],
    },
}

def get_current_temperature(location: str) -> dict:
    # 仅示意：生产代码应调用已授权的天气服务并处理超时/错误。
    return {"location": location, "temperature_c": 18, "source": "example"}

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="What's the temperature in London?",
    tools=[weather_function],
)

fc_step = next(s for s in interaction.steps if s.type == "function_call")
if fc_step.name != "get_current_temperature":
    raise ValueError(f"Unexpected function: {fc_step.name}")

location = fc_step.arguments.get("location")
if not isinstance(location, str) or not location.strip():
    raise ValueError("location must be a non-empty string")

result = get_current_temperature(location.strip())
final_interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[{
        "type": "function_result",
        "name": fc_step.name,
        "call_id": fc_step.id,
        "result": [{"type": "text", "text": json.dumps(result)}],
    }],
    tools=[weather_function],
    previous_interaction_id=interaction.id,
)

print(final_interaction.output_text)

3. 用户模板：只描述工具边界，不伪造执行结果

这是适配该函数声明的用户输入模板，不是 Google 声称的 system prompt：

任务：回答用户的天气查询。

工具边界：
- 只有在需要实时温度时请求 get_current_temperature。
- 参数只能包含 location，必须是非空城市名。
- 不要臆造工具返回值，也不要声称工具已执行；等待应用返回 function_result。
- 如果工具失败，明确说明查询失败，并返回可重试或人工处理的下一步。

用户问题：
[填写城市和问题]

4. 需要固定工具选择时

文档给出 generation_config 的 tool_choice 控制模式：auto（默认，由模型决定）、any（始终预测函数调用）和 none（禁止函数调用）。在多工具场景，还可以使用 allowed_tools 缩小允许调用的函数集合：

generation_config = {
    "tool_choice": {
        "allowed_tools": {
            "mode": "any",
            "tools": ["get_current_temperature"],
        },
    },
}

只在应用确实希望模型从限定集合中选工具时使用 any；强制函数调用不代表参数已经通过业务校验。

测试/工作流步骤

1. 在隔离环境配置 Gemini API 凭据；密钥只放环境变量或受保护的密钥存储，不写进提示词和仓库。

2. 用 exact model gemini-3.8-flash 运行只读天气示例，记录请求是否收到 function_call、函数名、参数类型和 call_id。

3. 应用侧先检查函数名白名单，再校验必填字段、类型、长度、枚举和值域；校验失败时不要调用外部 API。

4. 执行函数时设置超时、错误分支和审计字段；将最小必要结果封装为 function_result，通过 previous_interaction_id 回传。

5. 检查最终回答是否区分“模型建议调用”“应用已执行”和“工具返回结果”；工具失败时应保留错误状态，不补猜数据。

6. 另测一组需要并行或组合调用的任务；确认只有无副作用且相互独立的函数才并行，存在依赖时按顺序回传。

7. 对写入、发送、付款、设备控制和删除类工具加入人工确认与幂等键；未经确认不得执行，即使模型发出了合法格式的调用。

原始证据与数据

合法使用与安全边界

• 仅对自己拥有或已获授权的 API、数据和设备注册工具；工具声明不是授权证明。

• 函数名和参数必须做应用侧白名单校验。模型返回的 arguments 是不可信输入，不能直接拼接 SQL、shell、URL 或付款请求。

• 预约、发邮件、控制设备、写入数据库、付款和删除等副作用操作，先展示目标、参数和风险，等待人工确认；必要时加幂等键和重放保护。

• 工具结果也属于外部输入，可能过期、错误或含提示注入。只回传完成任务所需的最小字段，并保留来源、时间和错误状态。

• 日志只保存必要的调用元数据；不要记录 API key、认证头、邮箱、手机号、用户 token 或完整的敏感请求原文。

• previous_interaction_id 只用于关联互动上下文，不应被当作权限令牌。访问权限、速率限制、审计和人工接管仍由应用负责。

• 页面示例不构成生产质量或安全保证。上线前须在沙箱中验证工具选择、参数拒绝、超时、重试、取消和人工接管路径。

来源摘录或观察（合规短引）

该文档将函数调用定义为“自然语言与实际操作和数据之间的桥梁”，并强调执行函数是应用的责任。最重要的工程含义是：把模型的 function_call 当作待审核的结构化请求，而不是已经发生的外部动作。