Embabel Agent Framework：把类型安全的 Agent 编排写进 Java/Kotlin 生产栈

为什么 JVM 团队要单独看 Agent 框架

多数 Agent 教程和 PoC 仍落在 Python 侧：迭代快、模型与数据科学生态密，做实验很顺手。真正要把 Agent 嵌进已有订单、风控、客服、审批链路时，问题往往不再是「怎么调一次 LLM」，而是类型约束、事务与权限边界、可观测与回归测试，以及和现有 Spring 服务怎么共生。

Embabel Agent Framework（发音 Em-BAY-bel，/ɛmˈbeɪbəl/）把叙事放在这条线上：在 JVM 上用强类型领域模型编排 Agent 流，混合 LLM 调用与普通业务代码，并尽量复用企业栈已经具备的注入、持久化与运维能力。官网 hub.embabel.com 的定位是「Agentic AI for the JVM」；仓库 README 写明它「seamlessly mix LLM-prompted interactions with code and domain models」，并支持面向目标的路径规划。

本文聚焦「JVM 原生 Agent 框架选型与上手」，不展开持续学习或运行时沙箱权限等相邻话题。

项目名片

稳定二进制自 0.2.0 起发布在 Maven Central。当前 Central 上 embabel-agent-starter / embabel-agent-api / 各 provider starter 的 release 最新为 1.5.2（maven-metadata.xml 的 lastUpdated 为 2026-09-16）。主分支 POM 已是 1.5.3-SNAPSHOT，与文档站点上偶见的 SNAPSHOT 版本号不要和 Central 稳定版混用。

推荐起步坐标（稳定版）：

<dependency>
  <groupId>com.embabel.agent</groupId>
  <artifactId>embabel-agent-starter</artifactId>
  <version>1.5.2</version>
</dependency>

接 OpenAI 时再加 com.embabel.agent:embabel-agent-starter-openai:1.5.2；本地交互调试常用 embabel-agent-starter-shell。需要链路追踪时可用官方文档中的 embabel-agent-starter-observability:1.5.2（同样已在 Central）。

相对 Python 实验栈的定位差异

Hub 自己说得很直白：Python 适合机器学习实验，但从实验走向生产规模的 AI 时，更吃紧的是上下文、可靠性、类型安全、性能、可观测，以及与既有企业系统的集成；Java/Kotlin 在这些点上更对口。

Embabel 并不替代「直接调模型」或 Spring AI 的底层能力。README 用了一个类比：Spring AI 更接近 Servlet 层，Embabel 更接近 Spring MVC——多数业务应用应工作在更高层 API。规划步骤默认采用 Goal-Oriented Action Planning（GOAP），每步 Action 结束后按黑板（blackboard）上的类型化状态重规划，形成类似 OODA 的闭环。开发者通常不必手写完整状态机；方法签名上的输入输出类型会推断前置与后置条件。

这与「在 notebook 里串几段 prompt」不是同一类问题。若团队的主资产是 JVM 服务、领域对象和 Spring 组件，把 Agent 写进同一语言与同一容器，比另起一套 Python 编排再跨进程对接，更符合生产约束。

官方材料里的核心卖点

下列要点均可在 README 或 User Guide 中找到对应表述，本文不外推未写明的能力。

强类型与领域对象。 Action、Goal、Condition 由领域模型驱动；createObject(...) 把 LLM 输出绑到具体类型，而不是散落的 magic map。领域对象还可带 @Tool 方法，按需暴露给模型，未标注方法不会自动开放。

目标导向编排与可扩展复用。 默认 GOAP（也支持 Utility AI 等可插拔规划器）。动态规划意味着增加领域对象、Action、Goal、Condition 可以扩展能力，而不必改写既有 FSM 定义。执行模式包括 Focused（代码指定跑某个 Agent）、Closed（在已知 Agent 集合中选一个）与 Open（跨 Goal 组装路径；官方明确 Open 模式最强也最不确定）。

Spring 与 JVM 集成。 Agent 可被 Spring 注入与管理，可继续使用事务、持久化等企业能力。编程模型有两套：类似 Spring MVC 的注解模型（@Agent、@Action、@AchievesGoal、@Condition），以及 Kotlin DSL（agent { / action {）。框架本体用 Kotlin 编写，但对 Java 提供自然用法。

MCP。 文档称 Embabel 可消费外部 MCP Server 作为工具源，也可把自身 Agent 发布为 MCP Server（含 embabel-agent-starter-mcpserver）。@Export(remote = true) 等机制可把 Goal 暴露给 Claude Desktop 等 MCP 客户端。

可观测。 embabel-agent-starter-observability 在零业务改动前提下自动追踪 Agent 生命周期、Action、LLM 调用与工具调用，对接 OpenTelemetry 兼容后端（文档举例 Zipkin、Langfuse、LangSmith、Jaeger、Prometheus 等）。另有成本事件订阅与 Budget Guardrail 等与生产相关的配套能力。

可测试。 官方将单元测试与端到端 Agent 测试列为设计目标之一，并提供 embabel-agent-test 等模块（文档标注部分为 Incubating，选用时注意模块状态表）。

最小上手：依赖 + 一小段 Agent

前提：Java 21+、Maven Central、以及至少一个模型密钥（例如 OPENAI_API_KEY）。更快的路径是使用官方模板仓库 java-agent-template 或 kotlin-agent-template；注意模板 POM 里的版本号可能滞后于 Central，建议显式对齐到已核实的 1.5.2。

依赖示例（平台 + OpenAI + Shell）：

<properties>
  <embabel-agent.version>1.5.2</embabel-agent.version>
</properties>

<dependencies>
  <dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-starter</artifactId>
    <version>${embabel-agent.version}</version>
  </dependency>
  <dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-starter-openai</artifactId>
    <version>${embabel-agent.version}</version>
  </dependency>
  <dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-starter-shell</artifactId>
    <version>${embabel-agent.version}</version>
  </dependency>
</dependencies>

应用仍是普通 @SpringBootApplication。下面是官方文档「Writing Your First Agent」中的思路缩写（Java）：用 @Action 产出中间领域对象，用 @AchievesGoal 标记达成目标的终态 Action。

@Agent(description = 'Agent that writes and reviews stories')
public class WriteAndReviewAgent {

    @Action
    public Story writeStory(UserInput userInput, OperationContext context) {
        return context.ai()
            .withAutoLlm()
            .createObject('''
                You are a creative writer who aims to delight and surprise.
                Write a story about %s
                '''.formatted(userInput.getContent()),
                Story.class);
    }

    @AchievesGoal(description = 'Review a story')
    @Action
    public ReviewedStory reviewStory(Story story, OperationContext context) {
        return context.ai()
            .withLlmByRole('reviewer')
            .createObject('''
                You are a meticulous editor.
                Carefully review this story:
                %s
                '''.formatted(story.text()),
                ReviewedStory.class);
    }
}

配置好密钥后启动 Shell，可用 execute / x 喂自然语言，例如文档示例：x "Tell me a story about a robot learning to paint"。框架会把输入包成 UserInput 放进黑板，再按类型依赖推断执行顺序。若只想在现有 Bean 里「掺一点 AI」，也可注入 Ai，调用 generateText / createObject，不必一开始就上完整 Agent。

更完整的多步示例见官方 Examples 仓库中的 StarNewsFinder：抽取结构化人物、调用普通 Spring 服务取运势、带 Web 工具找新闻，最后生成 Markdown 文稿——同一 Agent 内混合 LLM 与非 LLM Action。

Java、Kotlin 与 Spring Boot 怎么接

• Java： 注解模型为主；模板与文档示例齐全。构造器注入业务服务即可，Agent 与普通 @Component / @Service 共存。
• Kotlin： 同样支持注解；另有 idiomatic DSL。Hub 首页示例即是 Kotlin @Action + createObjectIfPossible。
• Spring Boot： 加 starter 后由扫描注册 @Agent（默认 embabel.agent.platform.scanning.annotation=true）。运行形态由你决定：Web、Shell、微服务，或 MCP Server starter。模型密钥可用环境变量或 application.yml 下的 embabel.agent.platform.models.*。

一句话：把它当成「会规划的业务组件层」，而不是旁路脚本。

适用与不适用

更适用：

• 已有 Java/Kotlin/Spring 资产，希望 Agent 与领域服务同进程、同类型系统落地。
• 需要多步编排、中间结果结构化、可对 Action 做单测与回归。
• 要在流程中混用大小模型、本地模型与云模型，并控制成本与隐私边界。
• 需要把能力以 MCP 形式对外暴露，或消费 Docker MCP 等外部工具目录。
• 生产侧关心 OpenTelemetry 链路、成本事件与 guardrail，而不是只看一次 demo 成功率。

不太适用或需谨慎：

• 以数据科学实验、训练与 notebook 探索为主，且没有 JVM 集成诉求时，Python 生态通常更直接（这也是 Hub 对两侧分工的表述）。
• 期望「完全开放、任意组合」且结果高度确定：Open 模式官方写明最强但最不确定；生产上更常见 Focused / Closed。
• 只想薄封装一次 Chat Completions：直接用 Spring AI 可能更轻；Embabel 的价值在编排与类型化流程。
• 依赖文档中标为 Experimental / Incubating 的模块（如部分 A2A、Discord、Eval、Remote 等）做硬承诺前，应对照模块状态表并接受可能的破坏性变更。
• 默认 Context 仓储为内存实现，进程重启不保留；跨重启状态需自行对接持久化 SPI。

小结

Embabel 把 Agent 从「脚本里的 prompt 链」拉回 JVM 工程习惯：领域类型、Spring 注入、可测试的 Action，以及可插拔的目标导向规划。许可证为 Apache-2.0，稳定版 com.embabel.agent:embabel-agent-starter:1.5.2 已在 Maven Central。若你的团队正在评估「Agent 如何进生产而不另起一座语言栈」，从官方 Java/Kotlin 模板跑通 Shell，再对照 User Guide 里的 StarNewsFinder 与 MCP / Observability 章节，是一条可复核的路径。

延伸阅读：仓库 README、docs.embabel.com、embabel-agent-examples、示例应用 Tripper，以及 Hub 上的文档问答 Agent。