Embabel Agent 智能体框架

项目概述

Embabel 是一个面向 JVM 的智能体（Agent）框架，用于编写能够将 LLM 提示交互与业务代码及领域模型无缝融合的智能体流程。该框架使用 Kotlin 编写，但对 Java 同样友好，由 Spring 的创始人主导开发。其核心设计目标是让开发者能够以强类型、面向对象的方式构建可动态规划、可扩展、可测试的 Agent 系统。

核心概念

框架以以下几类要素建模智能体流程：

• Action（动作）：Agent 执行的具体步骤
• Goal（目标）：Agent 试图达成的目标
• Condition（条件）：执行动作或判定目标是否完成时评估的条件，每个动作执行后会重新评估
• Domain Model（领域模型）：支撑流程的对象模型，可包含行为，为 Action、Goal、Condition 提供信息
• Plan（计划）：达成目标的动态动作序列，由系统而非程序员自动编排；每个动作完成后都会重新规划，从而形成 OODA 循环式的自适应执行

应用开发者通常无需直接处理这些概念，因为大多数条件可以由代码定义的数据流推导得出，框架会自动推断前置与后置条件。

关键差异化能力

相比其他方案，Embabel 提供：

• 复杂规划能力：超越有限状态机和顺序嵌套，引入真正的规划步骤，使用非 LLM 的 AI 算法，使系统能够以新颖组合完成未被预先编程的任务，并能决策并行化等运行时行为
• 良好的扩展性与复用：得益于动态规划，新增领域对象、动作、目标、条件即可扩展系统能力，无需修改有限状态机定义或既有代码
• 强类型与面向对象优势：动作、目标、条件均由领域模型驱动，模型可包含行为，提示词与手写代码自然集成，避免魔法 Map，完整支持重构

平台架构与执行模式

框架通过 AgentPlatform 实现执行，支持以下模式：

• Focused（聚焦）：用户代码直接调用某个具体 Agent 的方法，适合事件驱动的代码流
• Closed（封闭）：对用户意图进行分类，在已知 Agent 中选择最匹配者，仅运行该 Agent 内定义的动作
• Open（开放）：评估用户意图后，平台整合所有资源尝试达成目标，从所有已知目标中动态构建自定义 Agent；若对适用性存疑则拒绝执行，可通过 GoalChoiceApprover 接口进一步约束

默认规划算法为 GOAP（Goal Oriented Action Planning），也可使用 Utility AI，后者基于效用分数而非严格前置/后置条件来选择动作，适合探索性和开放性任务。

使用方式

框架提供两种编写风格：

• 注解式：类型标注 @Agent，方法标注 @Goal、@Condition、@Action，与 Spring MVC 风格类似
• Kotlin DSL：通过 agent { action { } } 代码块构建

环境要求

• 必需：OPENAI_API_KEY
• 可选：ANTHROPIC_API_KEY、MINIMAX_API_KEY、ZAI_API_KEY 等
• Docker Desktop 版本需大于 4.43.2，并启用 Brave Search、Fetch、Puppeteer、Wikipedia 等 MCP 工具
• 本地使用 Ollama 时，引入以下依赖即可自动连接：

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

Shell 交互

开发期间可通过 Spring Shell 与框架交互：

execute "Lynda is a Scorpio, find news for her" -p -r

-p 输出提示词日志，-r 输出 LLM 响应日志；chat 命令可进入交互式对话。

代码示例（Java）

以下示例展示一个根据星座查找新闻的 Agent，核心代码片段如下：

@Agent(description = "Find news based on a person's star sign")
public class StarNewsFinder {

    @Action
    public StarPerson extractStarPerson(UserInput userInput, Ai ai) {
        // 从用户输入中抽取姓名与星座
        return ai.withLlm(OpenAiModels.GPT_41)
                 .createObjectIfPossible(prompt, StarPerson.class);
    }

    @Action(toolGroups = {CoreToolGroups.WEB})
    public RelevantNewsStories findNewsStories(StarPerson person, Horoscope horoscope, Ai ai) {
        // 使用 Web 工具搜索相关新闻
        return ai.withDefaultLlm().createObject(prompt, RelevantNewsStories.class);
    }

    @AchievesGoal(description = "Write an amusing writeup for the target person ...")
    @Action
    public Writeup writeup(StarPerson person, RelevantNewsStories news, Horoscope horoscope, Ai ai) {
        // 调用 LLM 生成创意稿件
        var llm = LlmOptions.withModel(OpenAiModels.GPT_41_MINI).withTemperature(0.9);
        return ai.withLlm(llm).createObject(prompt, Writeup.class);
    }
}

配套领域模型以 Java record 形式定义，例如 StarPerson、Horoscope、Writeup 等，配合 Jackson 注解保证反序列化与 LLM 解析的类型安全。

可测试性

框架从设计层面支持测试。可通过 FakeOperationContext 等工具断言提示词内容、工具组配置等，例如：

context.expectResponse(new Writeup("Gonna be a good day"));
starNewsFinder.writeup(starPerson, relevantNewsStories, horoscope, context);
var prompt = context.getLlmInvocations().getFirst().getPrompt();
assertTrue(prompt.contains(starPerson.getName()));

从而确保 Agent 按预期传递提示与超参数。