Fine grained tool calling

学习笔记：工具使用与流式传输 (Tool Use & Streaming)

💡 核心概念

• 流式传输 (Streaming): API 在初始响应后，持续向用户发送一系列事件，实现内容实时展示。
• 工具使用 (Tool Use): 当开启流式传输并调用工具时，需要处理特定的事件类型。

🛠️ input JSON event 详解

• 用途: 用于传输 Claude 计划发送给工具的参数。
• 关键属性:
• partial JSON: 工具参数中的一个片段（部分）。
• snapshot: 迄今为止所有 partial JSON 的累积总和。

🚧 默认机制与延迟问题

• API 内部流程: 默认情况下，API 会缓存 JSON 片段，直到生成一个完整的键值对（如 abstract 或 meta）。
• 验证步骤: API 会将完整的键值对与提供的 JSON Schema 进行验证。
• 问题所在: 只有通过验证的完整键值对才会被发送。这导致工具参数的输出存在明显的延迟和突发性大块文本。

🚀 解决方案：细粒度工具调用 (Fine Grained Tool Calling)

• 核心功能: 禁用 API 的 JSON 验证步骤。
• 工作原理: API 不再等待完整键值对，而是将生成的 JSON 片段以传统流式方式（Chunk by Chunk）发送给服务器。
• 优势: 允许开发者更快地处理工具调用参数（例如，在等待完整文本前获取 word count）。
• 注意事项 (Trade-off): 由于跳过了验证，开发者必须实现错误处理机制，以应对接收到的可能包含无效数据（例如 undefined）的 JSON。
• JSON 模式变更: meta 字段的类型已从包含数字和字符串的对象，变更为简单的字符串。
• 总结: 若追求更经典的流式体验，应开启“细粒度工具流”，但代价是放弃 API 的自动验证功能。

Takeaways

• 流式传输（Streaming）指API在初始响应后持续发送事件，实现内容实时展示。
• 默认机制中，API会缓存JSON片段直到生成完整键值对并验证通过，这会导致工具参数输出存在延迟。
• 细粒度工具调用（Fine Grained Tool Calling）通过禁用API的JSON验证步骤，将JSON片段以块（Chunk by Chunk）方式发送，实现更快的工具参数处理。
• 开启细粒度工具流的代价是放弃API的自动验证功能，开发者必须自行实现错误处理机制以应对无效数据。