Embabel Agent Framework 已经发布 1.0，为 Java 和 Kotlin 开发者提供了一套构建 AI Agent 的框架。它建立在 Spring AI 之上，可以连接多个模型提供商，并把“让模型自主规划”和“按预定义状态机执行”结合起来。
这意味着，Java 团队不必为了引入 Agent 工作流而切换到另一套语言生态。熟悉 Spring、依赖注入和领域对象的开发者，可以继续用类型安全的方式组织 Agent 能力。
Agent 不再只是一个聊天接口
传统的 LLM 集成通常是一次请求、一次响应：应用准备 prompt，调用模型，然后解析文本。Agent 框架关注的是更长的执行过程：模型需要判断下一步动作，调用工具，读取结果，再决定是否继续。
Embabel 的核心思路是把 Agent 表达为类型化的领域对象。一个 Agent 可以拥有明确的输入、输出和动作，而不是把全部逻辑塞进一段超长 prompt 中。
可以把这种设计理解为三层：
- 领域对象：描述任务输入、工具结果和最终输出。
- 规划能力：由模型决定应该调用哪些动作，以及动作的顺序。
- 确定性流程：对关键路径使用预定义状态机，限制可执行的状态和转移。
这种组合适合企业应用。探索性任务可以交给模型规划，支付、审批、数据写入等高风险步骤则可以保留在显式状态机中。
规划与状态机如何配合
纯规划模式灵活，但执行结果可能受模型输出影响；纯状态机模式可控，却需要开发者提前写出所有路径。Embabel 1.0 所强调的组合方式，适合在两者之间做边界划分。
例如，一个客服 Agent 可以这样工作：
- 接收用户问题并分类。
- 规划是否查询知识库、订单系统或人工服务。
- 对查询动作允许模型选择工具。
- 一旦进入退款或账户变更流程，就切换到固定状态机。
- 在完成审计和确认后返回结果。
规划负责处理不确定性，状态机负责守住业务规则。这个边界比“让模型自由调用所有工具”更容易测试、监控和审计。
一个可改造的 Java 示例
下面的示例用普通 Java 类型表达一个订单支持 Agent 的结构。它是一个便于改造的最小示意，具体注解名和配置方式应以项目使用的 Embabel 1.0 API 为准。示例展示了三个重要边界：类型化输入、可调用动作，以及确定性的退款状态。
import java.util.List;
// 领域输入：Agent 不直接接收一段无结构的字符串
record SupportRequest(String customerId, String message) {}
record Order(String orderId, String status, boolean refundable) {}
record SupportReply(String message, List<String> evidence, boolean requiresHuman) {}
interface OrderService {
Order findLatestOrder(String customerId);
}
interface KnowledgeBase {
List<String> search(String query);
}
public final class OrderSupportAgent {
private final OrderService orders;
private final KnowledgeBase knowledgeBase;
public OrderSupportAgent(OrderService orders, KnowledgeBase knowledgeBase) {
this.orders = orders;
this.knowledgeBase = knowledgeBase;
}
// 这类动作可以暴露给 Agent 的规划层
public Order lookupOrder(SupportRequest request) {
return orders.findLatestOrder(request.customerId());
}
public List<String> searchPolicy(SupportRequest request) {
return knowledgeBase.search(request.message());
}
// 退款属于高风险流程，使用显式状态转移更合适
public SupportReply refundFlow(SupportRequest request, Order order) {
if (order == null) {
return new SupportReply("找不到可处理的订单。", List.of(), true);
}
if (!order.refundable()) {
return new SupportReply("该订单不满足退款条件。", List.of(order.status()), false);
}
// 实际项目中，这里应继续拆分为确认、授权、执行和审计状态
return new SupportReply(
"订单已进入退款确认流程。",
List.of(order.orderId(), order.status()),
false
);
}
}
在真实项目中，可以将 lookupOrder 和 searchPolicy 作为 Agent 可规划的动作，把 refundFlow 之后的确认与执行拆成状态机节点。模型可以决定先查订单还是先查政策，但不能跳过授权和审计步骤。
如果使用 Spring AI 统一管理模型提供商，可以把模型配置放在环境变量和 YAML 中，避免把密钥写入代码：
spring:
ai:
openai:
api-key: ${OPENAI_API_KEY}
chat:
options:
model: ${OPENAI_MODEL:gpt-4o-mini}
切换其他模型提供商时，应优先检查 Embabel 和 Spring AI 对应的 provider 集成，而不是在业务 Agent 中直接绑定某个厂商 SDK。这样可以减少模型切换对领域代码的影响。
Java 团队需要关注的工程问题
类型安全不等于流程安全
record、接口和明确的返回类型可以减少参数解析错误，但它们不会自动阻止危险操作。涉及资金、权限、个人数据和外部写入时，仍然需要显式授权、幂等设计、超时、重试上限和审计日志。
规划结果必须可观测
Agent 执行失败时，开发者需要知道：模型选择了什么动作、使用了哪些输入、工具返回了什么、在哪个状态停止。生产环境至少应记录请求标识、Agent 状态、工具名称、耗时和失败原因，同时避免记录不必要的敏感内容。
模型提供商的可替换性有边界
基于 Spring AI 和多模型提供商的抽象，可以降低接入成本，但不同模型在工具调用、结构化输出、上下文长度和推理风格上仍然存在差异。上线前应使用真实任务集测试，不要只验证“能否成功返回文本”。
状态机应当小而明确
状态机不是把所有业务代码搬进框架。它更适合约束少量关键步骤，例如支付确认、人工升级、退款执行和权限变更。低风险的检索、摘要和分类任务，可以交给规划层处理。
采用建议
如果团队已经使用 Spring Boot、Java 或 Kotlin，Embabel 1.0 值得从一个边界清晰的流程开始试用：知识库问答、订单查询或工单分类都比直接改造核心交易流程更合适。
落地时可以按以下顺序推进：
- 先定义输入、工具结果和最终输出的数据类型。
- 为每个工具设置明确的参数、权限和超时限制。
- 把高风险操作放入显式状态机。
- 为规划决策和工具调用增加可观测性。
- 用固定测试集比较不同模型提供商的结果。
- 保留人工接管路径，并为失败和超时设计可恢复状态。
Embabel 的价值不只是“在 Java 中调用大模型”，而是让 Agent 进入熟悉的类型系统和应用工程边界。真正适合生产环境的方案，通常不是让模型拥有最大自由度，而是让模型在清晰定义的领域对象、工具和状态之间工作。