麻雀窝 Sparrow Zoo

Spring AI 自定义模型接入:让 Codex 的 tools 与 Advisors 真正生效

结合 Spring AI 2.0.1 与 Codex 适配案例,分清 ChatClient 与 ChatModel 的职责,定位工具声明丢失、底层协议缺失两个问题,并说明修复、验证与上游 issue #7238。

面向接入自定义 ChatModel 的 Java 开发者;案例基于 Spring AI 2.0.1 与 Codex CLI 0.158.0。发布于 更新于
SPRING AI · CODEX工具如何真正生效保留声明 · 转换协议 · 执行回传ChatClient + Advisors工具注册与官方循环自定义 ChatModelPrompt ↔ Codex 双向协议Codex请求工具Java 工具执行并回传注册成功 ≠ 已经执行
阅读目录

结论先行

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 调用开始

业务代码只想把用户问题交给模型,并让模型在需要时调用天气工具:

code
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 请求。
code
业务侧: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,仍然能切换底层模型

下面这段业务代码没有供应商协议细节,这是统一入口要达到的效果:

code
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(...) 声明工具,适配器为什么还必须覆写下面的方法?疑问的重点在于:默认选项类型是否应该影响明确声明的工具能否进入本次请求。

code
@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() 方法:

code
@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 等待最终 JSONapp-server 保持双向连接
工具声明未发送toolDefinitions() → dynamicTools
工具请求没有转换为框架 ToolCalltoolCallResponse() 返回 ToolCall,框架执行 Java 方法
工具结果没有回传入口returnToolResult() 响应原 RPC,让 Codex 继续

新实现的完整 call 方法变化见下一节代码 diff;后续章节再展开工具定义、ToolCall 与结果回传的实现。

源码中的旧代码对照

核心实现集中在 model/codex,会话 Advisor 位于其 advisor 子包。新 call 方法上方保留了旧 call 的完整注释;runner 启动位置保留旧 exec 命令摘录。历史代码只用于对照,不执行,也没有增加第二套工具循环。

代码 diff:业务调用不变,底层具体改了哪里

前面解释了两处缺口。这里把关键改动集中对照:业务调用保持原样,变化发生在模型适配、双向通信和连接生命周期。旧代码取自 f23db32,新代码来自本文整理后的工作区。下列 diff 中,- 表示删除,+ 表示新增。

阅读范围

第一段是 call 方法的实际源码 diff;后面三段是标明范围的接口或调用片段摘要,用于定位改动,不是可以直接 git apply 的完整补丁。完整的方法实现分别在后续“工具定义”“工具请求”“工具结果”和“请求作用域”章节展开。

模型入口:从只取文字,到读取完整请求

code
--- 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 属于实验性能力。

code
ChatClient
  → CodexSessionAdvisor
  → 官方 ToolCallingAdvisor
  → TokenCounterAdvisor
  → CodexTextChatModel
  → CodexProcessRunner
  → Codex app-server
  1. 初次模型调用在 thread/start 注册工具定义,再通过 turn/start 提交问题。
  2. Codex 提出 item/tool/call;适配器保存待响应的 RPC,并返回 Spring AI 的工具调用对象。
  3. 官方 ToolCallingManager 执行 Java 工具,生成工具结果消息。
  4. 官方工具循环再次进入模型适配;适配器把结果响应给等待中的 Codex。
  5. Codex 继续运行,直至请求其他工具或生成最终回答。

应用没有在 runner 中另造一套 Java 工具执行器。Codex 负责内部模型运行,Spring AI 负责应用工具的执行和循环调度,两侧在工具请求处衔接。一次适配调用也不能直接等同于供应商内部的一次模型请求。

工具定义如何发给模型

toolDefinitions() 从回调中提取工具说明。下面是当前实现的核心转换片段:

code
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,再构造标准响应:

code
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:

code
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,并提供三个交互入口,供模型适配完成请求、等待和回传:

code
// 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 放在循环内:

code
// 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()。下面摘录当前核心实现:

code
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:

code
@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;实验接口升级后需要重新核对。

原生协议还会报告用户消息回显、推理和上下文压缩。这些正常事件需要与原生工具执行分开识别,否则合法对话也会被错误中断。

如何验证生效,而不是只看最终回答

排查时按数据流设置断点,比重复增加日志更容易找到问题:

  1. 模型入口:检查 Prompt.options 是否为 ToolCallingChatOptions,目标 callback 是否存在。
  2. 发送前:检查 dynamicTools 的名称、描述和参数 Schema。
  3. 模型返回:检查是否收到 item/tool/call,验证名称与调用 ID。
  4. Java 方法入口:观察真实参数、副作用和执行次数。
  5. 回传位置:检查 ToolResponse 与待处理 callId 的匹配。
  6. Advisor 前后:观察工具循环是否重新进入,并核对用量没有重复累计。

案例原有验证记录显示,全模块 mvn -DskipTests=false clean verify 通过:48 项测试中 45 项执行通过,3 项真实外部调用测试默认跳过。模拟进程覆盖连续工具调用、私有上下文、历史角色、重复请求、错误、returnDirect、线程取消、阻塞工具超时清理,以及忙拒绝后的新请求隔离。

另行启用的真实 Codex 验证使用一个只返回固定测试值的 Java 工具:方法执行 1 次,适配调用 2 次,最终回答包含该测试值。这证明了真实工具往返;它不代表真实天气 HTTP 服务或其他业务流程已经验收。

code
# 全模块构建与本地模拟测试
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。

参考资料

  1. Spring AI · Chat Model API

    理解 Prompt、消息角色、模型选项和 ChatResponse 的职责。

  2. Spring AI · Tool Calling

    理解工具定义、ToolCallback、模型提出调用与应用执行工具的区别。

  3. Spring AI · Recursive Advisors

    理解工具循环如何重新进入后续 advisor。

  4. Spring AI 2.0.1 · DefaultChatClientUtils

    本案例工具参数为什么可能在构造 Prompt 时被忽略的源码依据。

  5. Spring AI 2.0.1 · ToolCallingAdvisor

    工具执行、循环、returnDirect 和多轮用量累计的实际实现。

  6. Spring AI 2.0.1 · AnthropicChatModel

    官方适配中消息、工具结果和供应商参数转换的参考。

  7. OpenAI · Codex App Server

    Codex 双向 RPC 和实验性动态工具调用的官方入口。

  8. Spring AI · Chat Client API

    统一的请求构造入口,以及 Builder 与具体 ChatModel 的关系。

  9. Spring AI 2.0.1 · ChatModel

    默认 getOptions 返回普通聊天选项;模型接口可被直接调用。

  10. Spring AI issue #7238

    本文提交的工具声明丢失问题:包含 Spring AI 2.0.1 的独立复现、实际输出、源码分析与预期行为。用于追踪上游讨论,不代表官方结论。

核对日期:2026-10-28。在线参考手册展示的版本可能高于案例版本;具体 API 与装配行为以文中固定的 2.0.1 源码为准。本篇为基于官方资料和项目代码的分析,不是官方发布教程。