Question 1

如何修复返回的 Tool.Result.Error 被记录并计为成功的 ToolCallResponseEvent 的问题？

Accepted Answer

该失败的发生是因为 `EventPublishingTool` 只把抛出的异常映射为 `Result.failure`；返回的 `Tool.Result.Error` 会走成功分支，并以 `Result.success("<error message>")` 的形式被发布。请修复 `ToolDecorators.kt` 中的 `EventPublishingTool`，使得当委托对象返回 `Tool.Result.Error` 时，发布 `Result.failure(ToolReturnedError(message, cause))`，同时 `call()` 仍返回原始的 `Error`。不要更改返回的中间结果，因为下游恢复逻辑以及 Spring 的 `ToolExecutionException` 转换都依赖它。添加一个测试，让委托对象返回 `Tool.Result.Error`，断言 `responseEvent.result.isFailure` 为 true，并且 `call()` 仍返回原始的 `Error`。这样可以使 `result.isFailure`、工具统计信息以及 `embabel.tool.errors.total` 正确报告该调用。在使用包含此修复的版本之前，自定义工具可以抛出异常而不是返回 `Tool.Result.Error`，但基于注解的 `MethodTool` 和 `ScriptTool` 错误需要该补丁。

Question 2

如何修复在使用 Embabel LM Studio autoconfigure 时缺少较新的 OpenAI 模型（例如 gpt-5.6-luna）的问题？

Accepted Answer

出现这种情况是因为 `embabel-agent-lmstudio-autoconfigure` 中包含一个过时的重复文件 `models/openai-models.yml`。如果该 JAR 先被加载，`OpenAiModelLoader` 就会使用它，而不是 `embabel-agent-openai-autoconfigure` 中的模型目录，因此较新的模型永远不会被注册。

修复方法：
1. 升级到包含 issue #2064 修复的版本，该修复已从 `embabel-agent-lmstudio-autoconfigure` 中移除了重复文件。
2. 作为临时变通方案，可以从 LM Studio JAR 中移除过时的资源文件：
   ```bash
   jar tf embabel-agent-lmstudio-autoconfigure-*.jar | grep 'models/openai-models.yml'
   zip -d embabel-agent-lmstudio-autoconfigure-*.jar 'models/openai-models.yml'
   ```
   之后重新构建并重新打包应用程序。或者，确保 `embabel-agent-openai-autoconfigure` 在 classpath 上位于 LM Studio JAR 之前，不过 JAR/classpath 的排序方式可能并不可靠。
3. 验证启动日志。加载正确的模型目录后，你应该会看到类似如下的日志条目：
   ```text
   Registered OpenAI model bean: gpt56luna -> gpt-5.6-luna
   ```

更长远的防护措施是让 `OpenAiModelLoader` 调用 `getResources("models/openai-models.yml")`，并在发现多个目录副本时发出警告或直接失败。

Question 3

为什么我的 Embabel agent 显示的版本是 0.1.0-SNAPSHOT 而不是应用程序的构建版本？

Accepted Answer

未显式声明 `@Agent(version = "...")` 的 Agent 此前会回退到框架默认值 `0.1.0-SNAPSHOT`，因为注解要求编译时常量，无法读取 Maven/Gradle 项目版本。此问题已在 PR #2113 中修复，通过由 `AgentMetadataReader` 使用的 `AgentVersionResolver` 按以下顺序解析版本：1) 显式设置的 `@Agent(version = "...")`（如有）；2) 生成 build-info 时的 Spring Boot `BuildProperties.version`；3) Agent 类所在包的 JAR 清单中的 `Implementation-Version`；4) 作为最终回退的 `Semver.DEFAULT_VERSION`。要将构建版本写入 Agent 元数据，可以显式设置版本：`@Agent(description = "...", version = "2.0.0")`，或者启用 Spring Boot 的 build-info 生成。对于 Maven：在 `spring-boot-maven-plugin` 中添加一个 `build-info` 目标的 execution。对于 Gradle：添加 `springBoot { buildInfo() }`。这样，部署的 Agent 元数据将反映实际应用构件的版本。

Question 4

如何使用 Spring AI 2.0 将 Embabel MCP 服务器从已弃用的 SSE 迁移到 Streamable HTTP？

Accepted Answer

使用包含 MCP Streamable HTTP 迁移的 Embabel 版本，在该版本中，仅用于 SSE 的 `McpSseShutdownConfiguration` 已被移除，`WebMvcSseServerTransportProvider` 也不再使用。然后通过添加以下配置，让 Spring AI 自动配置来选择传输方式：

```properties
spring.ai.mcp.server.protocol=STREAMABLE
```

或 YAML：

```yaml
spring:
  ai:
    mcp:
      server:
        protocol: STREAMABLE
```

移除所有引用 `WebMvcSseServerTransportProvider`、`McpSseShutdownConfiguration` 或旧版 SSE 端点的自定义 Bean 或配置。使用 `./mvnw clean package` 重新构建。远程 MCP 或 agent-to-agent 客户端必须连接到 Streamable HTTP 端点，而不是旧的 SSE 端点。在包含此更改的版本中，Embabel 将传输处理委托给 Spring AI，不再保留 SSE 特有的关闭代码路径。

Question 5

如何为速度较慢的本地 OpenAI 兼容或 Docker 嵌入模型增加超时时间？

Accepted Answer

升级到包含 issue #2083 修复的版本，然后配置 `connect-timeout` 和 `read-timeout`，而不是依赖硬编码的客户端默认值。

对于 Docker Model Runner，例如设置：

```yaml
embabel:
  agent:
    platform:
      models:
        docker:
          connect-timeout: 5s
          read-timeout: 30m
```

对于通用的 OpenAI 兼容提供商，在该提供商的配置中设置相同的 `connect-timeout` 和 `read-timeout` 属性。修复后的实现会将这些值同时应用于嵌入和补全/聊天客户端，并将它们传递到 Spring AI 的每请求选项；否则这些选项会发送 60 秒超时并覆盖 HTTP 客户端的设置。默认值仍为连接超时 5 秒、读取超时 10 分钟。在旧版本中，唯一的变通方法是减小嵌入批处理大小，例如将一个包含 800 个块的请求拆分为多个较小的请求。

embabel-agent

项目简介

README 预览

常见问题 (5)

同类型项目

tensorflow

superpowers

everything-claude-code

flutter