08 · 领域（Domain）

领域对象（Domain Objects）

Embabel 中的领域对象不只是强类型的数据结构 —— 它们是真正的对象、带有行为，这些行为可以被选择性地暴露给 LLM，并被智能体动作使用。

带行为的对象（Objects with Behavior）

与简单的 struct 或 DTO 不同，Embabel 的领域对象可以封装业务逻辑，并通过 @Tool 注解把它暴露给 LLM。例如：

java

@Entity
public class Customer {
    private String name;
    private LoyaltyLevel loyaltyLevel;
    private List<Order> orders;

    @Tool(description = "Calculate the customer's loyalty discount percentage") // ①
    public BigDecimal getLoyaltyDiscount() {
        return loyaltyLevel.calculateDiscount(orders.size());
    }

    @Tool(description = "Check if customer is eligible for premium service")
    public boolean isPremiumEligible() {
        return orders.stream()
                .mapToDouble(Order::getTotal)
                .sum() > 1000.0;
    }

    public void updateLoyaltyLevel() { // ②
        // 内部业务逻辑
    }
}

注记：

① @Tool 注解会在对象通过 PromptRunner.withToolObject() 加入时，把该方法暴露给 LLM。
② 像 updateLoyaltyLevel 这类没有加注解的方法，无论可见性如何，永远不会暴露给 LLM。这保证了工具暴露是安全、显式且可控的。

选择性地暴露工具（Selective Tool Exposure）

@Tool 注解让你可以有选择地把领域对象的方法暴露给 LLM。例如：

业务逻辑：暴露那些能安全调用、能带来业务价值的方法；
计算属性：计算派生值的方法 —— 这能帮 LLM 避免算错；
业务规则：实现领域专有规则的方法。

始终把内部实现细节隐藏起来；在暴露会修改状态或产生副作用的方法之前，务必慎重思考。

在动作中使用领域对象（Use of Domain Objects in Actions）

领域对象可以在动作方法中自然使用，把 LLM 交互与传统的面向对象编程结合起来。 领域对象实例是否可用，还直接驱动着 Embabel 的规划。

java

@Action
public Recommendation generateRecommendation(Customer customer, OperationContext context) {
    var prompt = String.format(
            "Generate a personalized recommendation for %s based on their profile",
            customer.getName()
    );

    return context.ai()
            .withToolObject(customer) // ①
            .withDefaultLlm()
            .createObject(prompt, Recommendation.class);
}

注记：

① Customer 领域对象作为 tool object 被提供，允许 LLM 调用它的 @Tool 方法。此时 LLM 可以访问 customer.getLoyaltyDiscount() 与 customer.isPremiumEligible()。

领域对象的方法即使加了注解，也不会暴露给 LLM，除非通过 withToolObject() 显式加入。

领域理解至关重要（Domain Understanding is Critical）

正如 Rod Johnson 介绍 DICE（Domain-Integrated Context Engineering，领域集成上下文工程）的博客《Context Engineering Needs Domain Understanding》所述，领域理解是有效上下文工程的根基。领域对象是以下三者之间的桥梁：

业务领域（Business Domain）：现实世界中的实体及其关系；
智能体行为（Agent Behavior）：LLM 如何理解并与该领域交互；
代码动作（Code Actions）：作用于领域对象的传统编程逻辑。

收益（Benefits）

丰富的上下文：LLM 同时获得数据结构与行为层面的上下文；
封装：业务逻辑留在它本该待的地方 —— 领域对象内部；
可复用：领域对象可以在多个智能体之间复用；
可测试：领域逻辑可以独立做单元测试；
可演进：给领域对象添加新的工具，就扩展了智能体的能力。

这种做法确保智能体面对的是有意义的业务实体，而不是泛化的数据结构，从而带来更自然、更有效的 AI 交互。