Gemini API 函数调用怎样串联多个工具

Gemini API 串联多个工具的关键，不是把所有能力塞进一个“大函数”，而是把每个工具声明成清晰的输入契约，再由应用接住 function_call、校验参数、执行真实动作，最后把结构化结果交回模型。前一个工具的输出如果决定后一个工具的输入，就按依赖关系串联；互不依赖的工具则可以并行处理。

官方地址：https://ai.google.dev/gemini-api/docs/function-calling

先把工具声明和本地执行拆开

一个可维护的工具调用链至少有四个边界：模型负责判断意图，工具声明负责描述输入，应用 dispatcher 负责校验和执行，外部服务负责返回业务结果。模型给出的参数不能直接拼成 SQL、URL 或写操作请求；先做类型、范围和权限检查，再进入执行层。

工具声明要能表达后续调用需要的输入

以“查询天气后决定是否调节温度”为例，get_weather 提供地点，set_thermostat 接收目标温度。函数名应唯一，description 要说明动作和返回含义，参数尽量使用明确的 string、integer、boolean 或 enum。不要让一个工具同时承担查询、判断和写入三个职责。

from google import genai

# 每个声明只描述一个动作；真实执行仍由应用代码负责。
get_weather = {
    "type": "function",
    "name": "get_weather",
    "description": "查询指定城市的当前温度，返回摄氏度和数据时间。",
    "parameters": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "description": "城市名称，例如 Shanghai"}
        },
        "required": ["city"]
    }
}

set_thermostat = {
    "type": "function",
    "name": "set_thermostat",
    "description": "设置家庭恒温器目标温度，仅允许 16 到 28 摄氏度。",
    "parameters": {
        "type": "object",
        "properties": {
            "temperature": {"type": "integer", "description": "目标摄氏温度"}
        },
        "required": ["temperature"]
    }
}

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="如果上海当前温度高于 20 度，就把恒温器设为 20 度，否则设为 18 度。",
    tools=[get_weather, set_thermostat],
)

# 只读取模型决定调用什么；不要把它当作已经执行成功。
for step in interaction.steps:
    if step.type == "function_call":
        print(step.name, step.arguments)

按依赖关系执行，而不是盲目顺序循环

如果模型先请求 get_weather(city="Shanghai")，应用应先验证城市，再调用天气服务。拿到结果后，才把它作为下一轮上下文交回 Gemini，让模型决定温度动作。若一次返回的多个函数调用互不依赖，可以并行；若后一个参数来自前一个结果，就必须串行。

把函数结果回传到同一交互上下文

应用执行函数后，不能只把结果打印在服务端日志里。要用 SDK 约定的 function result 结构回传，并保留对应的调用 ID；在有状态交互中可使用上一次交互 ID，在无状态模式中则要携带完整历史。结果最好是稳定的 JSON 对象，同时包含业务数据和可处理的错误信息。

import json

def run_tool(name, arguments):
    # 白名单防止模型调用未开放的函数。
    if name == "get_weather":
        city = str(arguments.get("city", "")).strip()
        if not city:
            return {"ok": False, "error": "city_required"}
        # 这里替换为实际天气服务；示例只展示调用链的数据形状。
        return {"ok": True, "city": city, "temperature": 23, "observed_at": "2026-11-03T09:00:00Z"}

    if name == "set_thermostat":
        temperature = arguments.get("temperature")
        # 写操作必须在执行前校验范围，不接受模型的任意数值。
        if not isinstance(temperature, int) or not 16 

上面的 run_tool 只是本地执行边界示意。真正的下一轮请求要使用 Google Gen AI SDK 对应的 function result 类型；不要手写一个看似相似、但 SDK 不认识的字段名。若采用无状态模式，还要原样保留模型返回的函数调用步骤，再追加工具结果。

用循环上限和失败回路控制自动化

组合式调用最容易出问题的地方，是模型不断要求重试，或者工具失败后把错误再喂回模型形成死循环。建议把最大轮数设为一个很小的上限；对网络错误只允许有限次重试，对参数错误直接返回可读错误；写操作则采用幂等键，并在执行前检查用户授权。

• 函数名不在白名单：立即拒绝，不向外部系统发请求。
• 参数缺失或越界：返回结构化错误，让模型修正或向用户追问。
• 外部服务超时：记录超时类别，避免把空结果当成成功结果。
• 需要付款、删除或修改配置：增加人工确认和审计记录。

常见问题

多个工具都能完成同一个动作怎么办？

缩小当前请求暴露的工具集合，并让 description 明确适用场景；不要把十几个相近工具一次性全部交给模型。

工具结果能直接拼进下一次提示词吗？

不建议。优先使用 SDK 定义的结构化 function result，并保留调用 ID、错误状态和关键字段，避免字符串拼接造成歧义。

什么时候应该并行调用？

只有当调用之间没有数据依赖、写入顺序要求和共享资源冲突时才并行；只要后一个参数来自前一个结果，就按串联处理。

为什么模型返回了函数调用却没有真实动作？

这是正常边界：Gemini 只返回调用意图和参数，外部服务必须由你的应用执行，再把结果回传给模型。

把“模型决策”和“应用执行”分开后，Gemini API 的多工具串联就变成一个可控的工作流：声明输入契约，按依赖调度，回传结构化结果，再用权限、幂等和循环上限守住自动化边界。