GLM-5.3工具调用第二轮就失忆？上下文回传排查
GLM-5.3多轮工具调用总丢上下文？拆解reasoning_content、tool_calls与clear_thinking，区分协议历史与展示历史，附消息回传结构和最小测试。
将 GLM 接入应用实现单次问答难度不高，但最容易踩适配坑的场景，是模型发起工具调用之后，应用如何组装下一轮请求。
模型返回工具名称与入参、后端成功拿到查询结果后，很多开发者只把工具返回结果塞进下一轮消息，丢掉原始助手回合；或是存储对话时仅保存content，直接舍弃reasoning_content、tool_calls字段。前端聊天界面看着记录完整，但送入模型的上下文链路已经断裂。
对于 GLM-5.3 来说，这不是可以忽略的小细节。
智谱官方文档明确说明，在思考和工具调用交错执行的场景，必须完整保留、原样回传推理内容；开启保留式思考之后，推理内容要保证完整、顺序不可改动。
本文以 GLM-5.3 旗舰模型为核心，讲解多轮工具调用场景下消息存储、回传的落地方案。文中不赘述跑分、定价、基础环境安装，也不会将某一类消息报错直接等同于全部 Agent 异常的根因。
一、版本前置确认：GLM-5.3 不能沿用旧版思考开关逻辑
GLM-5.3 作为智谱最新旗舰模型，拥有 1M 上下文窗口、128K 最大输出长度，模型默认持续开启思考能力，reasoning_effort支持 low、high、max 三档，默认档位为 max。
官方迁移提示重点：从老版本迁移代码时，如果继续传入 thinking.type: "disabled"，请求会直接报错，需要切换为启用思考模式，并按需调整推理强度档位。
这里有两个极易混淆的关键点。
第一，推理强度档位，和历史消息保留是两件独立配置。reasoning_effort仅控制本轮请求的推理深度，不会自动帮应用保存工具交互记录。
第二，长上下文容量 ≠ 自动记忆。哪怕模型支持百万 Token 上下文，如果代码组装消息时删掉必要字段，模型没有办法依靠上下文上限恢复丢失的交互信息。
接入校验要分成两层：请求参数是否匹配 GLM-5.3 规范、多轮消息数组是否完整还原每一步交互过程。
二、一次工具调用链路，包含哪些不可丢失的字段？
以订单查询场景举例，标准流程：用户提问 → 模型输出工具调用 → 业务程序执行查询 → 回传工具结果 → 模型总结回复。
模型返回工具调用消息时，需要处理四类核心信息：
表格
| 字段或信息 | 用途说明 |
|---|---|
| content | 助手正文内容，工具调用阶段可为空 |
| reasoning_content | 模型内部推理思考文本 |
| tool_calls | 工具名称、入参、调用唯一标识 |
| tool_call_id | 工具结果和对应工具调用的绑定 ID |
存储时不能只提取对用户可见的回答文本，其余字段直接丢弃。
特别注意：工具调用回合中content为空，不代表响应无效。只要tool_calls存在有效调用指令，就应当进入工具执行分支，不要判定为失败重试。
同时，工具返回结果不能简单包装成一条用户消息，必须携带tool_call_id和上一轮助手发起的调用一一绑定，让模型识别这条结果对应哪一次工具请求。
三、三类思考机制区分，不要混为同一个开关
文档里的交错式思考、保留式思考、思考强度，解决的是完全不同的能力逻辑。
交错式思考：工具步骤之间持续推理
模型不会只在任务开头完成一次思考。它可以先发起查询，拿到工具返回数据之后，继续判断是否需要继续调用工具。
如果应用只回传工具结果，缺失上一轮助手的工具调用消息，整条交互时序就被破坏，交错推理无法正常进行。
保留式思考：原样保留助手回合内的推理内容
保留式思考在 Coding Plan 端点默认开启，标准 API 默认关闭。标准 API 想要启用，需要配置thinking下的clear_thinking: false，并且原样回传未经修改、完整的推理文本。
这并不意味着所有问答应用都强制开启该能力，开发者需要结合接口类型、业务场景、数据留存策略选择是否开启。
思考强度：控制单次请求的推理深度reasoning_effort只作用于当前这一轮请求，它无法替代消息持久化，也修复不了丢失的工具调用上下文。
排查 BUG 的时候，不要同时修改这三项配置，否则就算效果好转，也无法定位到底是哪一项配置生效。
四、高频坑点：前端展示历史 和 送入模型的协议历史共用一套数据
很多早期聊天应用消息结构极简，只保存助手对外展示的回答：
{
"role": "assistant",
"content": "展示给用户的回答"
}接入工具调用之后继续复用这套结构，就会在序列化、转存过程丢失扩展字段。
推荐分开维护两套消息队列：
- 协议历史：用于组装发给模型的请求，保留全部原始字段、严格保持交互顺序；
- 展示历史：用于前端渲染，可做摘要、隐藏推理内容、简化工具信息。
前端不展示推理文本，和请求时删除reasoning_content，是完全不同的两件事。前者属于产品交互选择，后者会直接破坏模型上下文链路。
通过 KoalaAPI 接入 GLM 服务时，同样要校验 SDK、适配层是否透传全部扩展字段。单次普通问答正常，只能证明基础连通性没问题，不代表多轮工具调用链路兼容到位。
五、第二轮请求标准消息结构示例
下方是简化演示结构，仅作为格式参考，里面参数为占位示例，不可直接上线使用：
[
{
"role": "user",
"content": "查询订单ORDER-DEMO的配送状态。"
},
{
"role": "assistant",
"content": null,
"reasoning_content": "此处填入模型返回的完整推理内容",
"tool_calls": [
{
"id": "call_demo",
"type": "function",
"function": {
"name": "lookup_order",
"arguments": "{\"order_id\":\"ORDER-DEMO\"}"
}
}
]
},
{
"role": "tool",
"tool_call_id": "call_demo",
"content": "{\"status\":\"示例状态\"}"
}
]这套消息数组还原了完整交互：用户发起查询、助手请求调用工具、业务侧返回对应工具结果。
开发注意事项：禁止手动改写、润色模型返回的推理内容；tool_call_id必须使用模型原生返回值，不能硬编码；一次返回多个 tool_calls 时，每个调用都要独立记录 ID，分别回传结果，不能只处理其中一部分。
六、封装消息构造函数，规避字段丢失
使用 OpenAI 兼容 Chat 格式开发时，建议把组装助手消息的逻辑收拢到统一函数，不要在业务各处零散拼接消息。
示例处理思路（伪代码，根据所用 SDK 调整）：
def build_assistant_message(message):
result = {
"role": "assistant",
"content": message.content,
}
reasoning = getattr(message, "reasoning_content", None)
if reasoning is not None:
result["reasoning_content"] = reasoning
tool_calls = getattr(message, "tool_calls", None)
if tool_calls:
result["tool_calls"] = [
item.model_dump(exclude_none=True)
for item in tool_calls
]
return result核心原则：
- 不要因为 content 为空，直接删掉整条 assistant 消息；
- 需要回传的推理原文，不能摘要、改写、打乱顺序；
- 完整保存 tool_call_id、函数名称、原始入参；
- 给模型发请求，统一使用协议历史，而不是前端简化版消息。
满足以上，只是保证消息协议合规，不代表工具执行、权限校验、业务逻辑一定正常，业务校验需要单独实现。
七、流式工具调用：禁止收到片段 JSON 就执行工具
开启流式工具返回 tool_stream=true 之后，工具参数会分片下发，单条流块往往只是 JSON 片段，无法独立解析。
流式处理时，需要独立缓存三类增量数据：
- reasoning_content 推理文本增量；
- content 回答正文增量；
- 各个 tool_call 的名称、调用 ID、参数片段。
多个工具并行调用时，要依靠流返回的索引信息，分开合并每个调用的参数，不能混在一起解析。
就算片段拼接后 JSON 合法，也不能立刻执行工具。需要等待当前 tool_call 全部接收完毕，再做参数格式校验、权限校验、业务规则校验。
参数正确 ≠ 用户有权限执行该操作，写入类工具还需要额外做幂等、重复调用防护。
八、分层排查：定位问题在模型、工具还是消息组装层
遇到循环调用、无法接续任务，不要直接判定是推理内容丢失导致。故障来源还可能是工具报错、查询结果异常、提示词模糊、输出截断。
按照这个顺序逐项排查：
表格
| 检查层级 | 核对要点 |
|---|---|
| 模型响应 | 是否正常返回回答、tool_calls，或是提前终止 |
| 工具参数 | 参数是否完整、JSON 可解析、符合 Function Schema |
| 工具执行 | 是否成功执行，有无超时、鉴权、业务报错 |
| 结果关联 | tool_call_id 和上一轮助手调用一一匹配 |
| 助手历史 | 协议消息保存完整，推理、工具调用字段未丢失 |
| 最终请求 | SDK 序列化之后发出去的消息，和内存里的协议历史一致 |
重点对比：内存中准备发送的消息，和经过 SDK、中间层序列化之后实际上行的报文。很多字段会在序列化、适配器转换环节被静默过滤。
排查日志按需留存，敏感业务数据做好权限管控，不要无限制全量保存推理内容。
九、最小用例测试，提前验证整条回传链路
对接真实业务库之前，先用无副作用的桩函数做闭环测试。
比如写一个读取本地固定测试数据的工具，区分测试数据和真实业务数据。
测试目标不是模型回答有多流畅，而是验证下面几个行为：
- 第一轮正常输出 tool_calls；
- 助手消息全部字段被完整持久化；
- 流式分片合并、参数校验逻辑正常；
- 工具不会重复执行；
- 工具结果通过 tool_call_id 正确绑定；
- 模型拿到结果后可以继续推进任务。
测试完成基础正向用例之后，再补充返回空、调用失败、多工具并行、流中断等边界场景。
每次测试只改动单一变量，可以做两组对照：完整协议消息 / 简化消息，同时留存请求响应日志，避免单次偶然结果下结论。
尽量简化复现 Demo，越小的案例，越容易区分是消息清洗、拼接逻辑还是工具执行问题。
十、长上下文也要做预算管理：保留内容不等于无限追加
开启保留式思考，保障上下文连续性的同时，也要控制 Token 开销。
不能把全部日志、冗余文档、无效历史无限制塞进消息数组，会拉高推理成本，同时增加调试难度。
优化思路：
- 工具返回结果按需精简，只返回本轮任务必需字段；
- 读取大文件时返回摘要、定位片段，而非全量原文；
- 区分报错类型，标记可重试 / 不可重试错误；
- 增加工具调用次数上限、任务超时限制。
这里有一条红线：工具返回结果可以按需精简压缩，但官方要求原样回传的reasoning_content推理文本，不能擅自修改、删减。
如果需要上下文压缩，应当设计检查点、重建上下文策略，而不是随机删除消息数组内的 assistant、tool 回合。
同时不能单看单次请求 Token 变少就判定成本下降，需要统计完整任务包含重试、多轮调用后的总消耗。
十一、迁移上线验收，三层闭环校验标准
从旧版 GLM 迁移到 GLM-5.3，不能只替换 model_id 跑一次问答就上线。迁移需要重点关注思考配置、推理强度、流式推理解析、工具参数完整性。
上线验收分三层标准：
- 基础调用通过：请求参数合法，能够正常拿到模型响应；
- 协议闭环通过：助手调用、工具执行、结果回传、后续消息组装链路完整；
- 业务任务通过：最终输出符合需求，权限、调用次数符合规范，异常场景可停止或恢复。
使用 KoalaAPI 统一调度模型时，同样遵循这套验收标准。模型路由切换成功，不代表不同模型的思考机制、扩展字段、工具交互行为完全一致。
GLM-5.3 多轮工具调用上下文保留的核心，不是堆砌超长提示词，而是忠实还原每一轮交互。隔离协议消息和前端展示消息，搭配最小用例验证回传链路，才能让 Agent 工具调用逻辑稳定、可维护。
