Gemini API function calling 怎样区分工具调用与最终回答

区分 Gemini API 的工具调用与最终回答，应检查响应里的结构化内容，而不是搜索文本中有没有函数名。对 generateContent REST 响应，重点是 candidates[].content.parts[]：出现 functionCall 表示请求应用处理工具；普通 text 才可能是给用户的回答。一次响应结束，不代表整个工具任务完成。

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

本文限定为非流式 generateContent REST JSON，不把其他 Gemini 接口或 SDK 的便捷属性混进同一段解析代码。示例只是原创分类逻辑，没有调用真实模型、没有执行工具，也没有实测输出。

我会把“生成完了”和“办完了”拆成两件事

假设我要做一个查询商品库存的助手：用户问某个收纳盒还有没有货，模型提出 lookup_stock 调用。我希望接口明确表达“待查询”，而不是在它说了一句“我来查一下”时就把会话关闭。这是我会采用的接口设计场景，不是一次亲历上线事故。

我的取舍是给应用设置 tool_request 与 answer_candidate 两类内部状态，另外保留失败和待处理状态。前者说明有工具请求，后者说明已有可展示文本候选；这些名称是本文应用自己的契约，不是 Gemini 原生响应枚举。

先读 parts 类型，再解释结束原因

content 包含 parts；其中 functionCall 带函数名 name 和参数 args，text 则表示文本。一次响应中不能只看第一个 part，也不应默认工具调用永远只有一个。对我来说，遍历全部 part 的好处是分类逻辑不会依赖文本恰好出现在哪个位置。

finishReason 描述这次生成为什么结束。STOP 不能单独证明没有工具请求；MAX_TOKENS 等情况也不能只因已有文字就直接当完整回答。我的保守方案是先排除不完整结束，再检查结构化调用，把文本当成候选展示内容，而不把一段“正在查询”的话当作最终结论。

一个只分类、不执行工具的函数

def classify_response(payload):
    # 仅处理非流式 generateContent REST JSON；不执行工具或发网络请求
    if "error" in payload:
        return {"kind": "api_error"}

    candidates = payload.get("candidates") or []
    if len(candidates) != 1:
        # 本例应用只允许一个候选，缺失或多个都交给显式处理
        return {"kind": "needs_review", "reason": "candidate_count"}

    candidate = candidates[0]
    content = candidate.get("content") or {}
    parts = content.get("parts") or []
    reason = candidate.get("finishReason")
    if reason != "STOP":
        # 截断、阻止或未知结束不作为完整工具请求执行
        return {"kind": "not_complete", "finish_reason": reason}

    calls, texts = [], []
    for part in parts:
        if "functionCall" in part:
            call = part["functionCall"]
            if not isinstance(call, dict) or not call.get("name"):
                return {"kind": "needs_review", "reason": "bad_call"}
            calls.append(call)
        elif "text" in part:
            # thought 文本不进入给用户的回答
            if not part.get("thought", False):
                texts.append(part["text"])
        else:
            # 多模态和新类型不丢弃，留待适配
            return {"kind": "needs_review", "reason": "unsupported_part"}

    if calls:
        # 有工具调用就不能只因同轮带文本而结束；保留原始 content
        return {"kind": "tool_request", "calls": calls,
                "model_content": content}
    text = "".join(texts)
    if text.strip():
        # 只是最终文本候选，业务层仍需判断任务是否满足
        return {"kind": "answer_candidate", "text": text}
    return {"kind": "needs_review", "reason": "empty_content"}

本例刻意只接受一个候选，并将未知 part 交给 needs_review。它不是所有模型、所有多模态输出的通用解析器；接入更多能力时，应扩展类型处理，而不是把陌生内容静默删掉。解析函数的输入还应先是已成功解码的响应对象，传输错误不在这里伪装成空回答。

如果 parts 有 lookup_stock 的 functionCall，预期分类为 tool_request；若只有正常结束的非思考文本，则为 answer_candidate。即使同时带有说明文字和工具请求，也优先处理待完成调用。以上是代码预期，不是已运行日志。

工具结果回传，不等于把函数名打印出来

分类后，应用应从允许的工具集合找到对应实现，检查参数和业务权限，再决定执行。模型提出的参数不是授权证明。查询工具也要限定可访问数据；有写副作用的工具更不能被任意函数名直接触发。

实际工具结果应作为协议里的 functionResponse 回传，并与原调用匹配；如果调用带 id，响应应按协议保留对应 id。续接对话时保留原始模型 content，不要只重建一个函数名和 args 就丢掉其余元数据。对带思考相关元数据的模型尤其应按相应模型与接口文档保留内容，而不是自行改写。

工具结果回来后，后续模型响应仍可能请求另一个工具，也可能给出答案。应用必须设置调用轮数、超时和失败出口；“一直等到有 text”不是可靠停止条件。失败时返回真实错误状态，不要把工具异常改写成“库存为零”。

我不会把不同接口的字段直接拼在一起

工具选择配置也会影响模型是否允许直接回答。如果配置要求持续走工具，应检查相应接口的工具选择模式，不要把没有最终文本一概归因于模型故障。本文不绑定某个模型名或 SDK 版本，也不将其他接口的 mode 字段直接塞进 generateContent 请求。

相关问题

回答文字里写了 lookup_stock，算工具调用吗？ 不算。普通文字提到函数名，与结构化 functionCall 是两回事。

SDK 已自动执行工具，还会看到最初调用吗？ 要按 SDK 的自动调用设置和返回约定判断；不要将自动循环结束的结果误当成第一轮原始响应。

流式响应能照抄这个函数吗？ 不能。流式片段的内容与结束状态需要按协议汇总处理，不应每收到一点文字就宣布任务完成。

我会把最终决定留给应用层：协议层回答“这是什么内容”，编排层回答“是否还有工具要处理”，业务层回答“是否满足用户问题”。这样做增加了一点状态处理，却能避免把自然语言表象当成执行事实。

参考：generateContent 响应与内容类型、Gemini function calling 指南。