41 · 故障排查（Troubleshooting）

本节覆盖使用 Embabel 开发时可能遇到的常见问题，并给出可操作的解决办法。

常见问题与解决办法

问题	解决办法	相关文档
编译错误	检查 Maven 或 Gradle 依赖中使用的 Embabel 版本是否正确。你可能用到了更高版本（甚至是 snapshot）的 API。不同 Embabel 模块之间的版本不匹配会导致编译问题。除非你在照抄某个特定示例，否则请确保所有 com.embabel.agent 构件使用同一个版本。	配置（Configuration）
不知道怎么调用自己的 Agent	看文档中处理 UserInput 的示例，研究 AgentInvocation 相关模式，理解如何触发你的 Agent 流程。关键是想清楚如何提供 Agent 期望的初始输入。	调用 Agent（Invoking Agents）
Agent 流程跑不完	这通常意味着数据流出了问题。先理解 Embabel 的类型驱动数据流概念 —— 复习输入/输出类型如何在动作之间建立依赖关系。然后写一个集成测试，端到端验证你的流程。熟悉 Embabel 的 GOAP 规划概念。	数据流概念
LLM 提示词看起来不对，或超参数不对	写单元测试来捕获并校验实际发给 LLM 的提示词。这让你能看到真实的提示词内容，并据此调整 temperature、模型选择等参数。单元测试是调试 LLM 交互的最佳方式。	测试（Testing）
Agent 卡在规划阶段	检查所有动作是否都有清晰的输入/输出类型签名。类型流中缺失或循环的依赖会让规划器找不到通往目标的有效路径。检查你的 @Action 方法签名，查看规划器的日志输出寻找线索，并把 ProcessOptions.verbosity 调高以显示规划过程。	类型驱动流程
Agent 拿不到工具	确认你在 PromptRunner 上通过 withToolGroup() 或 withTools() 指定了工具。工具必须显式加进每一个需要它的 LLM 调用。检查所需工具组在你的环境中是否可用。	工具（Tools）
Agent 能跑但结果很差	复查提示词工程与人设（persona）配置。考虑调整 LLM temperature、模型选择，以及提供给动作的上下文。写测试来捕获"实际输出 vs 期望输出"。	测试、LLM 配置
很难用计划表达你想要的流程	熟悉自定义条件以实现复杂的流程控制。对于常见行为模式，考虑用 Embabel 的类型安全自定义 builder（例如 ScatterGatherBuilder、RepeatUntilBuilder）写成原子动作，而不是硬用一个个动作去表达所有东西。	DSL 与 Builder
自定义条件不按预期工作	记住：对于那些可能设置自定义条件的 @Action 方法，你必须声明后置条件；对于依赖这些条件的动作，必须声明前置条件。否则规划器会认为这些条件永远不会被设置，你的计划就不会按预期执行。	类型驱动流程
Agent 没有目标、无法执行	检查 @AchievesGoal 注解，确保你的终结动作被它标注。每个 Agent 至少需要一个 @AchievesGoal 动作，用来定义什么算"Agent 工作完成"。	注解（Annotations）
Claude Desktop 这类 MCP 客户端看不到你的 Agent	确保 @AchievesGoal 注解里包含 @Export(remote=true)。这会让你的 Agent 可以通过 MCP（Model Context Protocol）客户端远程调用。	注解、集成（Integrations）
Agent 用不了上游 MCP 工具，日志里报疑似配置错误	如果你用的是默认的 Docker MCP Gateway，检查 Docker 配置是否正确、容器是否在运行且可访问。其它 MCP 配置则要确保 Spring AI MCP 客户端配置正确。详细配置见 Spring AI MCP client 文档。	Spring AI MCP Client

调试策略（Debugging Strategies）

打开调试日志

在 application.yml 或 application.properties 中定制 Embabel 日志级别，以查看详细的 Agent 执行过程。例如：

logging:
  level:
    com.embabel.agent: DEBUG

获取帮助（Getting Help）

Embabel 社区活跃且乐于助人。加入 Discord 服务器提问并分享你的经验。