Spring AI 项目中 JSON Schema 生成机制对 ToolContext 的处理差异分析

背景介绍

在 Spring AI 项目中，工具调用(Tool Calling)是一个重要功能，它允许 AI 模型与外部工具进行交互。在这个过程中，JSON Schema 扮演着关键角色，它定义了工具方法所需的输入参数结构，确保 AI 模型能够正确地生成调用参数。

问题发现

在 Spring AI 的版本迭代过程中，开发团队发现新旧两种 JSON Schema 生成实现对于 ToolContext 参数的处理存在不一致性：

1. 旧实现(MethodInvokingFunctionCallback)：会主动跳过 ToolContext 类型的参数，不将其包含在生成的 JSON Schema 中
2. 新实现(JsonSchemaGenerator)：会将 ToolContext 类型参数包含在生成的 JSON Schema 中

这种差异可能导致以下问题：

• 向后兼容性问题：升级后行为不一致
• 用户困惑：开发者可能误以为需要手动提供 ToolContext 参数
• 与某些 AI 提供商的兼容性问题（如 Gemini 会报参数校验错误）

技术原理分析

ToolContext 是 Spring AI 中一个特殊的上下文对象，主要用于：

• 传递用户提供的上下文信息
• 传递框架管理的上下文信息
• 在工具调用过程中共享状态

按照设计初衷，ToolContext 应当由框架自动处理，而不应作为工具方法的显式输入参数暴露给 AI 模型。因此旧实现的跳过行为更符合设计预期。

解决方案

Spring AI 团队已经修复了这个问题，新版本中：

1. 统一了新旧实现的逻辑
2. 确保 ToolContext 参数不会被包含在生成的 JSON Schema 中
3. 保持了与文档描述的一致性

开发者影响

对于使用 Spring AI 的开发者来说，这一修复意味着：

1. 升级后不会出现意外的行为变化
2. 不需要为 ToolContext 提供额外的输入参数
3. 与 AI 提供商的交互更加稳定可靠

最佳实践

开发者在实现工具方法时，应当：

1. 将 ToolContext 参数视为框架内部机制
2. 专注于定义业务相关的输入参数
3. 通过 ToolContext 获取或共享状态信息，而不是依赖它作为输入

总结

Spring AI 对 JSON Schema 生成机制的改进，体现了框架对一致性和易用性的重视。这一修复确保了工具调用功能的稳定性和预期行为，使开发者能够更专注于业务逻辑的实现，而不必担心底层机制的差异。