结论先行
ChatClient 组织消息、工具、选项与 Advisor 流程,ChatModel 将处理后的 Prompt 转换为具体服务协议。工具由应用执行,模型只提出调用请求。统一业务调用写法成立的前提,是底层适配完整传递这些信息。
本案例有两个独立问题:第一处,默认选项类型使已注册工具在构建 Prompt 时丢失;第二处,旧 Codex 适配只转发文字,没有工具请求与结果回传通道。前者通过返回工具选项类型兼容当前版本,后者通过 app-server 双向协议接回官方工具循环。
最小复现、运行输出及预期行为已提交至 Spring AI issue #7238。明确声明应被保留;不能支持时应明确报错。本文对设计的评价不代表维护者已认可或承诺修复。
问题背景
应用已经注册天气工具,也能通过 ChatClient 得到文字回答,但 Java 工具方法始终没有执行。继续增加提示词或日志之前,应先确认工具是否进入 Prompt,再检查底层协议是否传递了工具定义与调用结果。
本文基于 Spring AI 2.0.1 和自定义 CodexTextChatModel 的接入案例,按“职责分工 → 两处缺口 → 协议修复 → 装配与验证”展开。“自定义模型”指实现 Spring AI 接口的 Java 适配器;“工具循环”指模型请求工具、应用执行、结果回传后继续回答的过程。
详细内容
从一段看起来正确的 tools 调用开始
业务代码只想把用户问题交给模型,并让模型在需要时调用天气工具:
String text = chatClient.prompt()
.user(request.getPayload())
.tools((Object[]) this.llmTools)
.call()
.content();工具对象中已经有 @Tool 方法,数组也成功注入,但 Java 方法始终没有执行。此时最容易做的事是继续补提示词或增加 advisor。更有效的排查方法是沿调用链确认三个事实:工具有没有进入请求、模型有没有提出调用、应用有没有执行并回传结果。
.tools(...) 提供可用工具;模型根据问题决定是否调用。只有工具方法实际运行,并且结果进入下一步回答,才能证明整条链工作。
本案例使用自定义 CodexTextChatModel。如果使用已经支持工具协议的官方 Anthropic 模型适配,转换工作由官方实现承担,不能把两条接入路径的能力混为一谈。
| 检查位置 | 发现的问题 | 处理方式 |
|---|---|---|
| 第一处:Prompt 组装 | 注册的工具与上下文没有进入模型输入 | 核对默认选项 builder 类型,参见 issue #7238 |
| 第二处:协议转换 | 只发文字,缺少工具定义、调用请求和结果回传 | 接入 Codex app-server 双向工具协议 |
ChatClient 与 ChatModel:请求组织和协议适配各负责什么
业务代码可以保持同一种写法,是因为供应商差异由已装配的 ChatModel 适配器处理。业务调用层和适配层承担不同工作:
| 位置 | 负责什么 | 在本案例中的边界 |
|---|---|---|
| ChatClient / Builder | 保存客户端默认配置,组织本次消息、提示词变量、工具、上下文与选项,并构建 Advisor 链。 | 调用方表达本次需求,不直接编写 Codex RPC 或供应商 HTTP 报文。 |
| Advisor 链 | 在模型调用前后处理请求与响应;工具 Advisor 推动工具执行和后续调用。 | 日志、记忆、检索等只在配置了对应实现时生效;不是所有业务流程都由 ChatClient 自动完成。 |
| ChatModel 接口及适配器 | 提供默认选项;接收 Prompt,转换消息、工具定义和参数,访问对端服务,返回 ChatResponse。 | 尊重处理后的请求,不重新选择业务工具,不擅自替换提示词,不用默认模型覆盖本次明确选择。 |
| ToolCallingManager / ToolCallback | 按工具名找到回调、带上本地上下文,执行 Java 方法并整理结果。 | 工具真实执行发生在应用中,不能把 Java 对象或私有上下文直接交给 LLM。 |
| Codex app-server | 运行 Codex 会话,通过协议提出动态工具请求并等待结果。 | 它是带自身运行过程的服务端,不能把一次 ChatModel.call 等同于内部一次 LLM 请求。 |
业务侧:user / system / tools / toolContext / options
→ ChatClient 组织本次 Prompt 与 Advisor 链
→ Advisor 处理请求
→ 模型调用 Advisor
→ ChatModel.call(Prompt)
→ 适配具体协议 → 对端服务
← ChatResponse(文字或工具调用)
→ 工具 Advisor 执行 Java 工具,必要时再次调用模型这里讨论的是本案例的 2.0.1 Client 工具循环。也可以直接调用 ChatModel.call(Prompt),因此 ChatModel 的接口本身不依赖 ChatClient;直接调用者需要自行组织 Prompt 和所需处理流程。
还要分清三类信息:提示词与消息会进入模型请求;toolContext 是传给本地工具的上下文,默认不发给 LLM;Advisor 的 context 用于处理链内部传递参数,也不等于系统提示词。统一管理不表示把这些内容全部拼进提示词。
整体 API 职责见 Chat Client API 与 Chat Model API。
为什么官方示例只写 ChatClient,仍然能切换底层模型
下面这段业务代码没有供应商协议细节,这是统一入口要达到的效果:
ChatClient chatClient = chatClientBuilder
.defaultAdvisors(MyLoggingAdvisor.builder()
.showAvailableTools(true).build())
.build();
var output = chatClient.prompt()
.user("What should I wear today in Amsterdam and in Barcelona?")
.tools(new WeatherTools())
.advisors(ToolCallingAdvisor.builder().build())
.call()
.content();这段调用写法与具体供应商解耦,但注入的 chatClientBuilder 已经在创建时关联一个 ChatModel。默认模型、连接方式、凭据和协议转换已由 Starter、自动配置及模型实现准备好,因此这里不必再写。更换模型适配与装配后,可以复用业务调用写法;仍需确认目标适配支持工具等实际使用的能力。
例如官方 AnthropicChatModel 在同版本中同样实现了:
@Override
public AnthropicChatOptions getOptions() {
return this.options;
}源码见 AnthropicChatModel:官方实现的 getOptions 与请求转换。官方实现已经提供匹配的选项类型,所以业务示例没有暴露上述隐藏条件。自定义适配器仍需提供默认配置和协议转换,但“官方也实现 getOptions”只能解释示例为什么能工作,不能证明静默丢弃工具声明的行为合理。
Spring AI 屏蔽底层通信细节,是让业务代码通过统一接口调用,由具体实现完成差异转换;不会让自定义适配器也无需处理协议。这里“自定义提示词模板”和“自定义 ChatModel 实现”尤其不能混为一谈:只换提示词应留在 Client 或 Advisor;新增一种通信后端才需要实现模型适配。
上例保留了手动工具 Advisor 以对应原始演示。当前案例版本会自动补上工具 Advisor,通常无需再手动添加;显式添加时也要遵守单个工具 Advisor 的限制。另一篇天气源码文章基于 2.1.0-M1,本篇基于 2.0.1,内部细节按各自版本核对。
第一处缺口:默认选项类型导致工具声明丢失
业务侧已经通过 .tools(...) 声明工具,适配器为什么还必须覆写下面的方法?疑问的重点在于:默认选项类型是否应该影响明确声明的工具能否进入本次请求。
@Override
public ToolCallingChatOptions getOptions() {
return ToolCallingChatOptions.builder()
.model(defaultModel)
.build();
}这个方法没有接收本次 Prompt,也没有修改它。它返回当前适配器的默认选项:defaultModel 是未指定模型时的默认名称;ToolCallingChatOptions 是可承载工具参数的选项类型。它没有在这里重复注册天气工具、写业务提示词或执行工具。
源码中的组装顺序
Spring AI 2.0.1 的 DefaultChatClientUtils.toChatClientRequest() 先从模型默认选项创建 builder,再合并 Client 请求设置,最后放入工具回调与上下文。下面摘录参数组装的关键步骤,工具列表收集与写入部分以注释概述:
ChatOptions.Builder<?> builder = inputRequest.getChatModel().getOptions().mutate();
if (inputRequest.getOptionsCustomizer() != null) {
builder = builder.combineWith(inputRequest.getOptionsCustomizer());
}
if (builder instanceof ToolCallingChatOptions.Builder<?> tbuilder) {
// 此处分配并收集 toolCallbacks,包含直接注册的回调和 provider 回调。
// 列表非空时校验,并调用 tbuilder.toolCallbacks(toolCallbacks)。
// toolContext 非空时调用 tbuilder.toolContext(inputRequest.getToolContext())。
}
ChatOptions processedChatOptions = builder.build();源码依据:DefaultChatClientUtils:默认选项、请求设置与工具参数的组装。这里要求的是运行时 builder 类型支持工具选项,不是要求业务调用者重新配置工具,也不是一个独立的能力探测系统。只返回这种类型,仍不能证明底层协议真正支持工具。
ChatModel 接口的默认实现只返回普通 ChatOptions。本适配器若直接继承它,构造出的 builder 不会进入上述工具分支;单纯删除覆写,不能让本案例的 .tools(...) 保持原有功能。源码见 ChatModel:getOptions 默认实现。
源码事实与设计评价要分开
源码事实:在这里核对的路径中,ChatClient 已保存工具回调,但模型默认选项产生普通 builder 时,不会进入工具参数写入分支。问题发生在构建 Prompt 时,早于 ChatModel.call(Prompt),并不是 LLM 不愿调用工具,也不是默认模型名覆盖了请求模型名。Client 层的默认工具和本次 .tools(...) 设置,均不能只因已调用注册 API 就保证最终工具选项已正确生成。
设计评价:统一入口接受了明确的工具声明,却因底层默认选项类型而跳过传递,形成了调用者不易察觉的隐藏条件。默认值应该补充缺省配置,不能让明确声明悄悄失效。更合理的行为是保留工具声明,在不支持或无法转换时给出明确错误;能力检查可以存在,但不应以静默遗漏代替。这是本文依据上述行为给出的设计评价,不是引用官方已承认的问题或修复承诺。
本案例的处理:为兼容现有版本,适配器返回可承载工具参数的选项类型,使 ChatClient 进入工具参数组装分支。此举解决当前接入问题,不代表调用者应该在模型层重复声明业务工具,也不代表任意普通选项实现天然支持工具。当前不能直接删除覆写而不处理这条传递路径。
默认模型能否被请求覆盖
可以。本案例在 call(Prompt) 中实际读取的是下面这段代码,而不是不加判断地取 getOptions():
ChatOptions options = prompt.getOptions();
validateOptions(options);
String model = options != null && options.getModel() != null
? options.getModel()
: defaultModel;例如装配时配置默认模型 A,本次请求明确选择 B,ChatClient 组装后的 Prompt 携带 B,适配器就使用 B。只有没有提供模型时才回到 A。对模型名这样的非空标量字段,Client 请求设置会覆盖模型默认值;集合等字段的合并规则须看对应 builder,不能概括成所有选项都简单覆盖。
对于已经到达模型入口的请求,还有一条实现要求:适配器必须尊重有效请求。如果适配器忽略 prompt.getOptions()、始终发送 defaultModel,或者只取文字而丢掉工具,同样会破坏统一调用的预期。本案例对不支持的参数明确报错,也不能把“统一 API”理解成所有底层服务自动支持全部选项。
配置值由配置文件与启动装配提供,适配器通过 getOptions 暴露它,并不要求适配器硬编码业务默认值。本案例仍由 CodexChatConfiguration 注入默认模型名;这一点与 ChatClient 提供客户端默认配置并不冲突。
这一请求组装问题已报告为 Spring AI issue #7238。复现不依赖 Codex 或真实 LLM:捕获模型收到的 Prompt,即可比较请求级工具、Client 默认工具与 toolContext 是否保留。返回普通选项时工具与上下文均缺失;返回工具选项类型后均正常传递。完整 Java 代码和命令见 issue。
第二处缺口:只转发文字,没有工具协议通道
业务侧的 .tools(...).call().content() 没有错。这里说的“只取文字”,指旧 CodexTextChatModel 内部调用 prompt.getContents(),与业务末尾取得回答的 .content() 不是同一个方法。后者可以在工具循环完成后返回最终文字,不能据此判断没有工具执行。
下面是提交 f23db32 中旧适配器的完整 call() 方法:
@Override
public ChatResponse call(Prompt prompt) {
String input = "你是智能助手。直接回答用户的问题,将回答放在reply字段。以下是用户消息:\n"
+ prompt.getContents();
CodexProcessRunner.Result result = runner.run(
new CodexProcessRunner.Request(input, REPLY_SCHEMA, "gpt-6-astra"),
Instant.now().plus(timeout), () -> !Thread.currentThread().isInterrupted(), () -> { });
JsonNode reply = json.readTree(result.finalJson()).get("reply");
if (reply == null || !reply.isString() || reply.asString().isBlank()) {
throw new IllegalStateException("CLI returned no chat reply");
}
return new ChatResponse(Collections.singletonList(new Generation(new AssistantMessage(reply.asString()))),
ChatResponseMetadata.builder().usage(usage(result.inputTokens(), result.outputTokens())).build());
}旧代码只将消息文字、最终输出 JSON 格式和写死的模型名交给 runner。它没有读取 prompt.getOptions() 中的工具定义,也没有将模型工具请求转换成 ToolCall,返回的 AssistantMessage 只有文字。即使第一处缺口修好、工具已经进入 Prompt,这条路径仍会丢掉工具信息。
| 位置 | 旧实现 | 当前实现 |
|---|---|---|
| 业务调用 | .tools(...).call().content() | 保持相同写法 |
| 读取输入 | getContents() 提取文字 | getInstructions() 保留角色;getOptions() 读取工具和模型 |
| 传输 | exec 等待最终 JSON | app-server 保持双向连接 |
| 工具声明 | 未发送 | toolDefinitions() → dynamicTools |
| 工具请求 | 没有转换为框架 ToolCall | toolCallResponse() 返回 ToolCall,框架执行 Java 方法 |
| 工具结果 | 没有回传入口 | returnToolResult() 响应原 RPC,让 Codex 继续 |
新实现的完整 call 方法变化见下一节代码 diff;后续章节再展开工具定义、ToolCall 与结果回传的实现。
核心实现集中在 model/codex,会话 Advisor 位于其 advisor 子包。新 call 方法上方保留了旧 call 的完整注释;runner 启动位置保留旧 exec 命令摘录。历史代码只用于对照,不执行,也没有增加第二套工具循环。
代码 diff:业务调用不变,底层具体改了哪里
前面解释了两处缺口。这里把关键改动集中对照:业务调用保持原样,变化发生在模型适配、双向通信和连接生命周期。旧代码取自 f23db32,新代码来自本文整理后的工作区。下列 diff 中,- 表示删除,+ 表示新增。
第一段是 call 方法的实际源码 diff;后面三段是标明范围的接口或调用片段摘要,用于定位改动,不是可以直接 git apply 的完整补丁。完整的方法实现分别在后续“工具定义”“工具请求”“工具结果”和“请求作用域”章节展开。
模型入口:从只取文字,到读取完整请求
--- f23db32/CodexTextChatModel.call
+++ current/model/codex/CodexTextChatModel.call
@@ -1,14 +1,24 @@
@Override
public ChatResponse call(Prompt prompt) {
- String input = "你是智能助手。直接回答用户的问题,将回答放在reply字段。以下是用户消息:\n"
- + prompt.getContents();
- CodexProcessRunner.Result result = runner.run(
- new CodexProcessRunner.Request(input, REPLY_SCHEMA, "gpt-6-astra"),
- Instant.now().plus(timeout), () -> !Thread.currentThread().isInterrupted(), () -> { });
- JsonNode reply = json.readTree(result.finalJson()).get("reply");
- if (reply == null || !reply.isString() || reply.asString().isBlank()) {
- throw new IllegalStateException("CLI returned no chat reply");
+ // 不带工具的直接调用,也建立作用域;带工具时必须覆盖整个框架工具循环。
+ if (current.get() == null) {
+ requireSessionForTools(prompt.getOptions());
+ return inSession(() -> call(prompt));
}
- return new ChatResponse(Collections.singletonList(new Generation(new AssistantMessage(reply.asString()))),
- ChatResponseMetadata.builder().usage(usage(result.inputTokens(), result.outputTokens())).build());
+
+ ChatOptions options = prompt.getOptions();
+ validateOptions(options);
+ String model = resolveModel(options);
+ List<Map<String, Object>> tools = toolDefinitions(options);
+ CallState state = current.get();
+
+ if (state.session == null) {
+ // 第一次:发送消息和工具定义,启动 Codex。
+ start(state, prompt, model, tools);
+ } else {
+ // 后续轮次:Spring AI 已执行 Java 工具,把结果交回同一个 Codex。
+ validateContinuation(state, prompt, model, tools);
+ returnToolResult(state, prompt);
+ }
+ return awaitResponse(state);
}看三处新增调用即可理解主线:toolDefinitions(options) 读取 ChatClient 的工具声明;首次 start(...) 发起带工具定义的 Codex 运行;后续 returnToolResult(...) 回传 Java 执行结果。awaitResponse(...) 会返回文字或结构化 ToolCall,工具的实际执行仍由 Spring AI 完成。
传输入口:从单次 run,到双向 Session
以下为旧、新通信接口的签名摘要,省略实现、重载和辅助类型:
- // 旧 CodexProcessRunner:输入文字、输出格式、模型,等待最终结果。
- public Result run(Request request, Instant deadline,
- BooleanSupplier current, Runnable beforeStart)
+
+ // 新 CodexProcessRunner:整次业务请求保持一个连接。
+ public Session open()
+
+ // Session 内的三个入口:
+ public JsonNode request(String method, Object params)
+ public JsonNode nextEvent()
+ public void respond(JsonNode id, Object result)request 发起初始化、创建会话和启动运行;nextEvent 接收模型文字或工具请求;respond 将 Java 工具结果交回原来的 RPC。更换传输方式的原因是需要保留“等待工具结果”的连接,而不是因为业务末尾使用了 .content()。
工具转换:新增三个必需的连接点
以下为新实现的关键语句摘录。旧适配器没有对应实现,所以只显示新增行;三个片段分别位于不同方法中:
+ // start:把工具定义注册给 Codex。
+ params.put("dynamicTools", tools);
+
+ // toolCallResponse:把模型请求转换为框架可以处理的 ToolCall。
+ AssistantMessage.ToolCall toolCall = new AssistantMessage.ToolCall(
+ callId, "function", name, json.writeValueAsString(params.get("arguments")));
+ AssistantMessage message = AssistantMessage.builder()
+ .content(text)
+ .toolCalls(List.of(toolCall))
+ .build();
+
+ // returnToolResult:将匹配到的 Java 工具结果回传给等待中的 Codex。
+ state.session.respond(state.pending, Map.of("success", true, "contentItems",
+ List.of(Map.of("type", "inputText", "text", match.responseData()))));这三步缺一不可:只发送定义,模型提出请求后仍没人执行;只返回 ToolCall,Java 执行后没有回传,Codex 仍在等待。toolContext 留在应用侧,由框架传给 Java 方法,不出现在 dynamicTools 中。
连接收尾:从单次调用结束,到整个工具循环结束
以下为生命周期位置的对照摘要;旧版与新版都需要 finally,新版将连接寿命扩展到整次业务请求:
- // 旧版:runner.run(...) 退出时,其 finally 结束进程。
- // 适合一次性返回文字,没有等待 Java 工具结果的后续轮次。
+
+ // 新版 CodexSessionAdvisor.adviseCall:包住官方工具循环。
+ return model.inSession(() -> chain.nextCall(request));
+
+ // 新版 CodexSessionAdvisor.getOrder:在工具 Advisor 前进入、后退出。
+ return ToolCallingAdvisor.DEFAULT_ORDER - 1;这样第一次模型调用返回工具请求时,连接仍然存活;Spring AI 执行工具后,下一次调用继续使用它。最终完成、异常或 returnDirect 提前结束,都由作用域的 finally 关闭。截止任务仍负责工具阻塞时的进程清理。
另一个独立改动是返回 ToolCallingChatOptions,用于兼容前文“第一处缺口”的请求组装限制,详见 issue #7238。它解决工具进入 Prompt 的问题;本节的协议改动解决工具进入 Codex 并往返执行的问题。
用 Codex 双向协议接起官方工具循环
本次采用 codex app-server --stdio。它通过一行一个 JSON 对象交换请求、响应和通知,适合在模型等待工具结果时保留交互通道。动态工具接口见 Codex 官方说明;其中 dynamicTools 与 item/tool/call 属于实验性能力。
ChatClient
→ CodexSessionAdvisor
→ 官方 ToolCallingAdvisor
→ TokenCounterAdvisor
→ CodexTextChatModel
→ CodexProcessRunner
→ Codex app-server- 初次模型调用在
thread/start注册工具定义,再通过turn/start提交问题。 - Codex 提出
item/tool/call;适配器保存待响应的 RPC,并返回 Spring AI 的工具调用对象。 - 官方
ToolCallingManager执行 Java 工具,生成工具结果消息。 - 官方工具循环再次进入模型适配;适配器把结果响应给等待中的 Codex。
- Codex 继续运行,直至请求其他工具或生成最终回答。
应用没有在 runner 中另造一套 Java 工具执行器。Codex 负责内部模型运行,Spring AI 负责应用工具的执行和循环调度,两侧在工具请求处衔接。一次适配调用也不能直接等同于供应商内部的一次模型请求。
工具定义如何发给模型
toolDefinitions() 从回调中提取工具说明。下面是当前实现的核心转换片段:
ToolDefinition definition = callback.getToolDefinition();
definitions.add(Map.of(
"type", "function",
"name", definition.name(),
"description", definition.description(),
"inputSchema", json.readTree(definition.inputSchema())));inputSchema 必须作为 JSON 对象发送,而不是把整段 Schema 再当成普通字符串。私有 toolContext 留在 Java 进程内,由官方 manager 交给工具方法。
模型工具请求如何变成 ToolCall
收到工具请求后,适配器验证工具名、threadId、turnId、参数对象和重复 callId,再构造标准响应:
AssistantMessage message = AssistantMessage.builder()
.content(text.toString())
.toolCalls(List.of(new AssistantMessage.ToolCall(
callId, "function", name,
json.writeValueAsString(params.get("arguments")))))
.build();| 标识 | 用途 | 为什么不能混用 |
|---|---|---|
| callId | 标识一次模型工具调用,与 ToolResponse.id 匹配。 | 同名工具可能被调用多次。 |
| RPC id | 标识一次 JSON RPC 请求,用于发送协议响应。 | 它不必与 callId 相同。 |
| threadId / turnId | 限定调用所属的会话与执行轮次。 | 避免把其他轮次的事件当成本次工具请求。 |
工具结果怎样回到等待中的 Codex
returnToolResult() 按 callId 和工具名匹配结果,再用原 RPC id 发送 contentItems:
state.session.respond(state.pending, Map.of(
"success", true,
"contentItems", List.of(Map.of(
"type", "inputText",
"text", match.responseData()))));
state.pending = null;这里表示工具协议响应已被处理;业务是否成功仍由结果内容和工具自身规则表达。默认框架处理器可能把工具运行时异常转换成错误文本交回模型,不能假定所有工具异常都会向调用方抛出。
底层 runner:从一次性文字调用改成双向交互
CodexProcessRunner.java 不再只等待一次最终文字输出。它启动 codex app-server --stdio,并提供三个交互入口,供模型适配完成请求、等待和回传:
// CodexProcessRunner.Session 中的三个核心入口
public JsonNode request(String method, Object params)
public JsonNode nextEvent()
public void respond(JsonNode id, Object result)以上为方法签名摘录。request() 发送主动 RPC 并等待匹配响应;nextEvent() 接收 Codex 发来的通知与工具请求;respond() 使用原 RPC id 回传工具结果。它们提供传输能力,不承担 Java 工具的业务执行。
初次调用依次完成 initialize、thread/start 和 turn/start。模型提出工具请求时,进程保持等待;Spring AI 执行 Java 方法之后,下一次模型适配调用再通过 respond 继续原来的 Codex 运行。这里不能重新启动一轮无关的文字聊天,也不能把整个工具结果拼成新问题冒充协议回传。
runner 同时负责临时目录、登录复用、输出大小限制、独立截止任务与幂等清理。原来的单并发限制仍保留,改动没有引入另一套业务调度器。
Advisor 顺序为什么影响清理与 Token 统计
本案例把会话 advisor 放在工具循环外,统计 advisor 放在循环内:
// CodexSessionAdvisor
@Override
public int getOrder() {
return ToolCallingAdvisor.DEFAULT_ORDER - 1;
}
@Override
public ChatClientResponse adviseCall(
ChatClientRequest request, CallAdvisorChain chain) {
return model.inSession(() -> chain.nextCall(request));
}
// TokenCounterAdvisor
@Override
public int getOrder() {
return ToolCallingAdvisor.DEFAULT_ORDER + 1;
}inSession() 使用请求作用域保存进程与待处理工具请求,在 finally 中关闭资源。它需要包住整个循环:工具设置 returnDirect=true 时,Spring AI 会直接把结果返回调用方,不会再进入下一次模型 call。只依赖“下一轮模型调用”收尾,会留下仍在等待结果的 Codex 进程。
统计 advisor 位于循环内,因此能观察每次适配调用。但 Codex 提供的是 turn 累计用量,不能每轮都返回同一份总数再让框架相加。本实现中间步骤返回 EmptyUsage,正常完成时只登记一次总量;提前返回或异常可能无法取得完整用量。
循环和统计的框架依据见 2.0.1 ToolCallingAdvisor。若工具等待期间的 advisor 改变初始消息、模型或工具清单,本适配明确拒绝,避免表面修改成功、底层实际忽略。
请求作用域:finally 为什么必须覆盖整个工具循环
CodexSessionAdvisor.adviseCall() 调用模型的 inSession()。下面摘录当前核心实现:
public <T> T inSession(Supplier<T> work) {
CallState previous = current.get();
CallState state = new CallState();
current.set(state);
try {
return work.get();
} finally {
try {
if (state.session != null) state.session.close();
} finally {
if (previous == null) current.remove();
else current.set(previous);
}
}
}CallState 保存本次请求的进程会话、工具定义、调用标识和待回传结果。多个工具轮次使用同一份状态,避免把工具结果交给错误的进程。结束时移除本次 ThreadLocal,已有外层状态则恢复,防止线程复用时串入下一次请求。
外层 finally 处理正常完成、returnDirect 和异常;独立截止任务则处理 Java 工具阻塞时的进程清理。这两者解决不同问题:关闭 Codex 进程不等于能强制终止任意 Java 工具方法。
启动装配:把会话管理和统计接回 ChatClient
CodexChatConfiguration.java 使用配置中的模型名创建自定义模型,并将请求作用域和统计功能放入同一个 ChatClient:
@Bean
public CodexTextChatModel codexTextChatModel(CodexCliProperties properties) {
CodexProcessRunner runner = new CodexProcessRunner(
properties.getExecutable(), properties.getTimeout());
return new CodexTextChatModel(runner, properties.getChat().getModel());
}
@Bean
public ChatClient codexTextChatClient(CodexTextChatModel model) {
return ChatClient.builder(model)
.defaultAdvisors(
new CodexSessionAdvisor(model),
new TokenCounterAdvisor())
.build();
}这里摘录方法主体,省略了 import 与配置类注解。模型名不再硬编码在调用处;请求中支持的模型选项也会由模型适配读取。
Spring AI 2.0.1 的 ChatClient 会配置官方工具 advisor,当前不再重复添加第二个。会话 advisor 在循环外,统计 advisor 在循环内,实际顺序由各自 getOrder() 决定,不应只根据注册列表的位置推断。
业务侧继续使用原来的 chatClient.prompt().user(...).tools(...).call().content(),无需在订阅器里自行反射执行工具或手写工具循环。
核心改动总表:四个文件完成五个步骤
| 步骤 | 代码位置 | 前后变化 |
|---|---|---|
| 提供工具选项类型 | CodexTextChatModel.java · getOptions() | 普通 ChatOptions → ToolCallingChatOptions,让工具回调进入 Prompt。 |
| 传递工具 | CodexTextChatModel.java · toolDefinitions() / awaitResponse() | 只传文字 → 发送 dynamicTools,并把模型工具请求转成 ToolCall。 |
| 回传结果 | CodexTextChatModel.java · returnToolResult() | 没有结果通道 → 按 callId 匹配结果,用原 RPC id 响应 Codex。 |
| 管理作用域 | CodexSessionAdvisor.java / CodexChatConfiguration.java | 单次调用收尾 → 在官方工具循环外统一清理,统计保留在循环内。 |
| 保持双向连接 | CodexProcessRunner.java · Session | 一次性 exec → app-server 请求、事件接收和结果响应。 |
完整过程是:注册工具 → Codex 请求调用 → 适配成 ToolCall → Spring AI 执行 Java 方法 → 回传结果 → Codex 生成回答。测试代码分别检查受控协议路径与真实模型往返。
本案例核对的组合为 Spring AI 2.0.1、Spring Boot 4.0.8、Codex CLI 0.158.0,构建环境为 Java 25、Maven 3.8.6。已有 Claude 官方接入保持原样,业务侧工具注册代码也无需更换。
- 目前支持同步文本
.call();流式、图片和音频未接入。 - 支持配置与请求级模型选择;temperature、maxTokens、topP 等未支持参数会明确报错。
- 保留单并发,忙时拒绝第二个请求;每次请求有独立进程与临时目录。
- 复用现有 auth.json 文件登录,不导入个人插件或 MCP 配置;未接入系统 keyring 凭据存储。
- 进程最长 60 秒,工具调用上限为 16 次;独立截止任务在 Java 工具阻塞时仍能清理进程与临时目录。任意 Java 方法无法被强制停止,工具自身仍须实现超时与取消。
- 历史注入采用本机生成协议定义的
thread/inject_items;实验接口升级后需要重新核对。
原生协议还会报告用户消息回显、推理和上下文压缩。这些正常事件需要与原生工具执行分开识别,否则合法对话也会被错误中断。
如何验证生效,而不是只看最终回答
排查时按数据流设置断点,比重复增加日志更容易找到问题:
- 模型入口:检查 Prompt.options 是否为 ToolCallingChatOptions,目标 callback 是否存在。
- 发送前:检查 dynamicTools 的名称、描述和参数 Schema。
- 模型返回:检查是否收到 item/tool/call,验证名称与调用 ID。
- Java 方法入口:观察真实参数、副作用和执行次数。
- 回传位置:检查 ToolResponse 与待处理 callId 的匹配。
- Advisor 前后:观察工具循环是否重新进入,并核对用量没有重复累计。
案例原有验证记录显示,全模块 mvn -DskipTests=false clean verify 通过:48 项测试中 45 项执行通过,3 项真实外部调用测试默认跳过。模拟进程覆盖连续工具调用、私有上下文、历史角色、重复请求、错误、returnDirect、线程取消、阻塞工具超时清理,以及忙拒绝后的新请求隔离。
另行启用的真实 Codex 验证使用一个只返回固定测试值的 Java 工具:方法执行 1 次,适配调用 2 次,最终回答包含该测试值。这证明了真实工具往返;它不代表真实天气 HTTP 服务或其他业务流程已经验收。
# 全模块构建与本地模拟测试
mvn -DskipTests=false clean verify
# 本项目的可选真实验证:使用已有 Codex 登录额度
mvn -pl agent-infrastructure -am -DskipTests=false \
-Dsparrow.codex.tools.live=true \
-Dtest=CodexLiveToolCallingTest \
-Dsurefire.failIfNoSpecifiedTests=false test模拟服务证明应用协议和执行行为;真实模型测试证明供应商链路;最终业务验收还需要核对授权、数据和副作用。不要用其中一种结果替代其他结论。
代码整理后重新执行了 Codex 定向测试及全模块 clean verify:16 项 Codex 测试通过;全模块 48 项测试中 45 项执行通过,3 项外部调用测试按原配置跳过,0 失败、0 错误。真实 Codex 工具往返为案例原有验证记录,此次未重新调用;issue #7238 的无外部服务最小复现已单独编译运行。
总结归纳
排查工具不执行时,先看声明是否进入 Prompt,再看协议是否完整传递。两处缺口应分别验证,文字回答正常不能证明工具链路正常。
ChatModel 可以提供默认选项,但不能让明确的工具声明悄悄失效。当前版本的接入处理保留工具选项类型;底层通过双向协议完成调用与回传。相关请求组装问题及复现见 Spring AI issue #7238。
参考资料
- Spring AI · Chat Model API
理解 Prompt、消息角色、模型选项和 ChatResponse 的职责。
- Spring AI · Tool Calling
理解工具定义、ToolCallback、模型提出调用与应用执行工具的区别。
- Spring AI · Recursive Advisors
理解工具循环如何重新进入后续 advisor。
- Spring AI 2.0.1 · DefaultChatClientUtils
本案例工具参数为什么可能在构造 Prompt 时被忽略的源码依据。
- Spring AI 2.0.1 · ToolCallingAdvisor
工具执行、循环、returnDirect 和多轮用量累计的实际实现。
- Spring AI 2.0.1 · AnthropicChatModel
官方适配中消息、工具结果和供应商参数转换的参考。
- OpenAI · Codex App Server
Codex 双向 RPC 和实验性动态工具调用的官方入口。
- Spring AI · Chat Client API
统一的请求构造入口,以及 Builder 与具体 ChatModel 的关系。
- Spring AI 2.0.1 · ChatModel
默认 getOptions 返回普通聊天选项;模型接口可被直接调用。
- Spring AI issue #7238
本文提交的工具声明丢失问题:包含 Spring AI 2.0.1 的独立复现、实际输出、源码分析与预期行为。用于追踪上游讨论,不代表官方结论。
核对日期:2026-10-28。在线参考手册展示的版本可能高于案例版本;具体 API 与装配行为以文中固定的 2.0.1 源码为准。本篇为基于官方资料和项目代码的分析,不是官方发布教程。