Claude工具参数流式输出怎么接?碎片JSON、结束事件与安全执行
按工具启用eager_input_streaming,累积input_json_delta而不是…
文章目录

工具参数很长时,等完整JSON生成后才显示进度会显得卡住。Claude细粒度工具流可更早把参数碎片发给客户端,但服务端不会先缓冲并验证完整JSON。因此接入重点是累积、校验与执行时机,不是把每个片段立刻交给工具。
第一步:只为需要的工具启用
请求启用stream,并在相应用户自定义工具设置eager_input_streaming=true。不需要更早碎片的工具保留默认缓冲行为,避免给所有工具同时增加处理复杂度。
当前每工具字段替代旧fine-grained-tool-streaming-2025-05-14标头。若同时使用computer use或browser use工具集,官方说明旧标头会产生兼容问题;迁移时检查请求级标头,不能只新增字段而保留冲突设置。
{"name":"preview_note","description":"Receive a draft note for review","eager_input_streaming":true,"input_schema":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]}}
第二步:按内容块累积参数碎片
用内容块索引或工具调用ID维护独立缓冲,收到input_json_delta便追加partial_json。一个片段可能只包含半个引号、转义序列或字段名,不能逐块json.loads,也不能因为暂时解析失败就马上重试整轮请求。
多个工具块或文本块需要分别处理,不能把所有事件拼到一个字符串里。展示预览时标为尚未完成的草稿,尤其路径、金额或收件人参数在最后一段之前可能还会变化。
事件处理逻辑:content_block_start→新建对应缓冲;input_json_delta→追加该块partial_json;content_block_stop→尝试完整解析并标记候选完成;消息终态→确认未截断,再进入校验和执行流程。
第三步:完整解析后再做业务校验
拿到完整内容后先验证JSON语法,再按input_schema检查类型与必填字段,最后检查路径范围、外部动作授权等业务条件。语法合法不等于参数合理,例如空路径或越界目录仍可能不适合执行。
练习工具只返回预览,不实际写文件。确认流水线不会被首个碎片触发,才接入真实业务执行器。不要以模型已经发起tool_use为由跳过应用校验,工具仍由你的程序负责执行。
第四步:处理max_tokens与非法JSON
官方明确max_tokens停止可能在参数中途截断,终止事件不能单独证明输入完整。检查消息stop_reason和实际解析结果;不完整时保留错误状态,不补上一个括号就当成模型原本参数。
按官方无效输入处理方式把问题回报模型,需要工具结果错误时使用相应is_error结构,保持tool_use_id对应。不要伪造成功tool_result,也不要无上限重试同一个截断输出。调大输出范围前先检查任务是否可以缩小。
失败样例:引号未闭合;只收到半个Unicode转义;数组缺尾部;两个工具交错到达;连接中断;max_tokens;JSON合法但字段类型错误。预期均不得触发真实外部动作。
第五步:用正常和失败事件共同验收
保存脱敏事件序列,在本地回放确认每块独立、顺序正确、不会重复执行。普通文本流已经正常不代表工具参数流也正常,尤其需要覆盖重连与重复事件的业务去重。
验收时分别记录首次片段时间、完整参数时间和真正执行时间,未运行的测试留空。本教程不声称更快多少;目标是在可见进度更早的同时,只有完整且符合规则的参数才进入执行环节。
官方资料
资料核对日期:2026年11月22日。
本文地址:https://www.163264.com/22484


