Spring AI 2.0 Java 工具搜索如何绑定会话键：ToolSearchToolCallingAdvisor 的发现边界

一个 Java AI 服务接入几十个工具后，最先暴露出来的通常不是模型能力，而是边界问题：同一个 ChatClient 如果把整套工具都预先交给模型，单租户、单会话和权限范围就很难核对。Spring AI 2.0 的 ToolSearchToolCallingAdvisor 把工具先放入索引，只在当前会话需要时发现相关工具，关键在于每次请求都带上稳定的会话标识。

会话隔离的核心不是给工具改名，而是让 ToolSearchToolCallingAdvisor 用 session ID 选择当前会话可见的工具索引；没有稳定 session ID，就没有可靠的会话边界。

工具数量上来后，问题先出在“谁能看见什么”

小型示例里把几个 POJO 通过 defaultTools 注册到 ChatClient 很直观；当工具扩展到搜索、订单、报表和内部知识库时，工具定义本身也会变成请求负担。更麻烦的是，模型获得了不必要的工具描述，调用方却很难从日志里说明某个会话为什么看到了它。

这次排查先把问题缩小为三个对象：ToolIndex 保存完整工具集合，ToolSearchToolCallingAdvisor 负责按需发现，ChatClient 为请求提供会话上下文。它们之间是静态职责关系，不等于业务授权链路。

先确认 Spring AI 2.0 的按需发现边界

官方 Tool Search 文档把工具发现拆成两层：完整工具集进入工具索引，模型真正需要能力时调用 toolSearchTool 查询；Advisor 再把匹配到的工具放入当前会话可用范围。这个设计减少的是“每次请求都暴露全部定义”，不是把工具方法变成无需鉴权的公共接口。

因此排查时要分开两个问题：

• 可见性：这个会话是否能发现某一类工具。
• 授权性：Java 工具方法收到请求后，是否仍检查租户、用户和资源权限。

前者由会话索引范围影响，后者仍属于业务服务的责任。不要因为工具没有出现在首轮提示里，就把它当成已经完成了安全隔离。

最小 Java 配置：把会话键放进 Advisor 上下文

Spring AI 文档给出的默认路径是使用 ChatMemory.CONVERSATION_ID。如果现有系统已经在 Advisor 上下文中传递会话 ID，工具搜索可以直接复用；如果系统以租户键作为隔离单位，则通过 sessionIdKeyName 指定读取位置。

var toolSearchAdvisor = ToolSearchToolCallingAdvisor.builder()
    .toolIndex(toolIndex)
    .maxResults(5)
    .build();

String answer = chatClient.prompt("查询本会话可用的库存工具")
    .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, "session-42"))
    .call()
    .content();

如果业务上下文使用 tenantId，配置可以改成：

var tenantAdvisor = ToolSearchToolCallingAdvisor.builder()
    .toolIndex(toolIndex)
    .sessionIdKeyName("tenantId")
    .maxResults(5)
    .build();

这里的 maxResults(5) 是发现结果数量边界，不是权限数量边界。它控制返回多少个候选工具，不能替代工具内部的资源校验。

从排查现场定位三个容易误判的地方

把 defaultTools 当成按会话工具

defaultTools 适合每次请求都应该存在的稳定能力，但它表达的是 ChatClient 级默认工具，不表达“当前会话才可见”。需要按请求收窄范围时，应把会话上下文和工具发现 Advisor 放到同一条可追踪链路中。

会话键每次请求都变

如果请求入口随机生成会话键，Advisor 会把同一个人的连续请求视为不同会话；如果所有租户都使用同一个固定键，隔离效果又会退化。日志中至少应记录脱敏后的会话键、租户边界和发现结果数量。

只检查工具搜索，不检查工具本身

按需发现降低了首轮暴露范围，但工具被发现后仍会进入调用链。工具方法要继续检查当前用户能否访问订单、库存或报表，不能把“没有被搜索到”当成唯一安全控制。

上线前用一张清单复查边界

如果使用自定义会话键，先在单元测试或集成测试里覆盖两个租户、两个会话和一个无权资源。测试重点不是模型返回哪句话，而是会话上下文是否稳定、发现范围是否正确、工具内部是否拒绝越权资源。

相关问题

ToolSearchToolCallingAdvisor 会自动执行所有工具吗？

不会。它负责工具发现和工具调用链的组合；真正的工具方法仍由应用侧的工具管理组件处理，并应保留业务校验。

sessionIdKeyName 可以直接填用户姓名吗？

不建议。应使用稳定、最小化且可脱敏的会话或租户标识，避免把个人信息直接写入调用上下文和日志。

maxResults 调小就等于更安全了吗？

不是。它限制发现结果数量，安全边界仍要由租户、用户和资源授权逻辑完成。

把“少暴露”落实成可审计的会话边界

Spring AI 2.0 的工具搜索适合解决工具集合变大后的可见性问题：工具先进入索引，当前会话再按需发现。Java 服务落地时，优先固定会话键、记录发现边界、区分工具可见性与业务授权，再决定是否调整结果数量。这样排查结果才不会停在“模型没有调用某个工具”这一层，而能回答“这个会话为什么能看到它、调用时又如何被校验”。