Gemini 3 函数调用为什么要回传 thoughtSignature：Go 多轮工具链的顺序核对

用Go开发对接Gemini 3的服务时，接入函数调用流程最容易被忽略的环节不是工具参数校验，而是模型返回的thoughtSignature字段。很多人第一次请求拿到天气类函数调用结果后，只把执行完的工具结果直接拼回对话上下文，第二轮请求大概率会直接返回400错误。只要把模型推理步骤、对应签名和工具返回结果按原始顺序完整留存，整个工具调用链路才能顺利走到最终的回答输出环节。

先看一次完整的工具调用回合

假设用户提出问题“北京今天适合带伞吗”，模型不会直接给出答案，会优先触发已经注册好的get_weather工具。服务端收到函数调用指令后查询自身的天气数据服务，再把拿到的结果回传给Gemini做后续处理。整个交互流程至少包含四类核心数据：

• 用户输入的原始提问；
• 模型生成的functionCall对象，包含函数名、参数以及对应的签名；
• 应用执行完工具逻辑后产出的functionResult结果；
• 模型基于工具返回内容生成的最终回答文本。

其中第二类数据不能只提取函数名和参数做保存。Gemini 3的推理链路用加密签名维护跨回合的推理连续性，签名字段需要和模型原始推理步骤放在一起完整留存。

Go 代码里先固定工具边界

工具调用属于外部系统交互的副作用边界，不能拿到函数名就直接执行对应逻辑。先完成名称合法性、参数类型和取值范围的校验，再转交给具体业务函数处理。下面的示例只返回模拟的固定天气数据，重点演示回合数据的正确留存方式：

type ToolCall struct {
    ID        string
    Name      string
    Arguments map[string]any
    Signature string
}

func runWeatherTool(call ToolCall) (map[string]any, error) {
    if call.Name != "get_weather" {
        return nil, fmt.Errorf("unsupported tool: %s", call.Name)
    }
    city, ok := call.Arguments["city"].(string)
    if !ok || city == "" {
        return nil, errors.New("city is required")
    }
    return map[string]any{"city": city, "temperature": 27, "rain": false}, nil
}

生产环境代码还需要额外配置城市枚举校验、调用超时时间和返回结果大小限制。这里的Signature字段不需要参与任何业务判断逻辑，也不能被日志系统截断之后再用来拼装下一轮的历史上下文。

无状态模式的回传顺序不能变

如果服务端没有内置会话持久化能力，Go侧服务需要自行维护全量交互历史。正确的拼接顺序是：用户输入 → 模型原始步骤 → 工具结果。不要自行把thought、functionCall拆开之后重新排序。

type TurnHistory struct {
    UserInput      map[string]any
    ModelSteps     []map[string]any
    FunctionResult map[string]any
}

func appendToolTurn(h TurnHistory, steps []map[string]any, result map[string]any) TurnHistory {
    // steps 必须是 SDK 返回的原始模型步骤，包含签名字段。
    h.ModelSteps = append(h.ModelSteps, steps...)
    h.FunctionResult = result
    return h
}

使用Google官方Go SDK开发时，优先完整留存SDK返回对象的完整序列化结果；如果是自行手写JSON适配层，至少要针对签名字段增加非空校验逻辑。很多开发者会犯的一个常见错误是只保存name、arguments和业务结果，看起来可以复现之前的调用过程，实际上已经丢掉了维持模型回合连贯性的核心状态。

把失败拦截点放在第二轮请求前

在发起下一轮Gemini请求之前，可以做三项轻量校验：

1. 是否仍然存在和当前函数调用对应的模型步骤记录；
2. 签名字段是否非空，没有被日志脱敏逻辑替换成省略号之类的占位内容；
3. 函数结果的call_id是否和本轮模型调用的ID匹配。

只要有任意一项校验不通过，直接返回“工具回合状态不完整”提示，留存请求ID和原始响应数据即可。不要随便生成一个新字符串冒充签名去重试，这样只会把明确的状态错误转化成完全无法定位根因的模型异常。

有状态和无状态该怎么选

有状态模式更适合普通对话服务场景：直接用SDK或者官方服务端维护交互ID，应用层只需要把函数结果作为下一轮输入提交即可。无状态模式更适合需要自建审计、跨进程重放或者自定义存储规则的系统，对应的代价是必须完整留存所有模型步骤和签名字段。

常见问题

thoughtSignature 是不是业务自定义字段？

不是。它属于模型回合状态的内置组成部分，业务层不需要解析它的具体内容，只需要完整保存并按要求原样回传即可。

可以只回传 functionCall 不回传 thought 字段吗？

不要自行删减模型返回的步骤内容。严格按照官方SDK的对象模型保留完整步骤之后再提交工具结果，兼容性会更稳定。

签名为空的时候能不能直接重试一次？

先排查是不是序列化、日志脱敏或者字段映射环节出现了数据丢失。如果原始响应里确实没有签名字段，记录模型版本、接口信息和请求ID之后，再按照对应版本文档的指引处理，不能随便生成随机值来替代。

函数结果应该放在上下文的什么位置？

放在对应模型函数调用节点的后面，并且使用同一个调用ID。交互顺序错位比工具返回内容本身异常，更容易导致第二轮请求直接失败。

上线前的最小验收清单

先用一个固定工具完成一轮成功调用流程，再覆盖参数缺失、工具超时、重复回传和历史重放四个边界场景。日志中记录模型版本、会话ID、工具名、call_id和结果状态，不需要记录签名明文。确认多轮调用流程完全跑通之后，再把测试用的天气工具替换成订单查询、库存查询这类真实业务工具。