内容
# Embabel 框架演示 - 电子商务客户支持代理
使用 [Rod Johnson 的 Embabel 框架](https://github.com/embabel/embabel-agent) 将 AI 驱动的客户支持代理添加到现有 Java Spring Boot 应用程序中的实用示例。
## 什么是 Embabel？
Embabel 是一个创新框架，允许您使用 Java 注解创建代理式 AI 系统。您可以使用诸如 `@Agent`、`@Action` 和 `@Condition` 之类的注解以声明方式定义代理行为，而不是编写复杂的编排代码。
本仓库展示了如何将 Embabel 集成到传统的 Spring Boot 电子商务应用程序中，以自动处理客户退款和更换。
## 先决条件
- **Java 21** 或更高版本
- **LLM API 密钥** - OpenAI 或 Anthropic API 密钥，用于 LLM 操作
## 快速开始
### 1. 设置您的 LLM API 密钥
Embabel 框架需要 OpenAI 或 Anthropic API 密钥才能正常运行。请选择其中之一：
**对于 OpenAI：**
```bash
export OPENAI_API_KEY=您的-openai-api-key-此处
```
**对于 Anthropic：**
```bash
export ANTHROPIC_API_KEY=您的-anthropic-api-key-此处
```
或者在 Windows 上：
```cmd
set OPENAI_API_KEY=您的-openai-api-key-此处
# 或
set ANTHROPIC_API_KEY=您的-anthropic-api-key-此处
```
### 2. 运行应用程序
```bash
git clone <此仓库>
cd ecommerce-demo
./mvnw spring-boot:run
```
应用程序将在端口 8080 上启动。
### 3. 测试客户支持代理
您可以通过两种方式与代理交互：
**选项 A：使用交互式 Shell**
要使用 Shell 版本，您需要修改 Application.java 文件：
1. 在第 10 行注释掉 `@EnableAgentMcpServer`
2. 在第 11 行取消注释 `@EnableAgentShell`
然后运行：
```bash
./scripts/shell.sh
```
这将启动一个交互式 Shell，您可以直接与客户支持代理聊天。打开 Shell 后，请在消息前加上 `x`：
```
x "您好！我想退回订单 ORD-123。"
```
**选项 B：MCP 服务器（用于 Claude Desktop 集成）**
代理也可在 `http://localhost:8080/sse` 使用，并可以处理以下客户请求：
- "我需要退回订单 ORD-123 的退款"
- "我可以更换订单 ORD-456 吗？"
- "我对订单 ORD-789 很愤怒，我想要退钱！"
## 展示的 Embabel 关键概念
### 代理声明
```java
@Agent(
name = "客户支持代理",
description = "协助客户退款和更换"
)
public class CustomerSupportAgent {
// 代理实现
}
```
### 操作和流程控制
```java
@Action
ParsedRequest parseRequest(UserInput userInput, OperationContext context) {
// 使用 LLM 提取订单 ID、操作类型和情感
}
@Action(pre = "shouldReplace")
OrderAdjustmentResponse processReplacement(OrderSearchResult searchResult) {
// 仅在 shouldReplace 条件为真时执行
}
```
### 条件逻辑
```java
@Condition(name = "shouldReplace")
public boolean shouldReplace(ParsedRequest request, OrderSearchResult result) {
boolean wantsReplacement = OperationType.REPLACE.equals(request.operationType());
boolean hasInventory = inventoryService.getQuantity(result.order().sku()) > 0;
return hasInventory && wantsReplacement;
}
```
### MCP 服务器集成
```java
@AchievesGoal(
export = @Export(
name = "refundOrReplaceOrder",
remote = true,
startingInputTypes = {UserInput.class}
)
)
```
## 使用 Claude Desktop 测试
要通过 Claude Desktop 与代理交互，请将以下内容添加到您的 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"customer-support": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:8080/sse"]
}
}
}
```
然后重启 Claude Desktop，您可以直接与客户支持代理聊天。
## 项目结构
```
src/main/java/com/kylehoehns/ecommerce/
├── agent/
│ ├── CustomerSupportAgent.java # 主要的 Embabel 代理
│ ├── OperationType.java # REFUND/REPLACE 枚举
│ └── Sentiment.java # POSITIVE/NEUTRAL/NEGATIVE 枚举
├── order/ # 订单管理服务
├── inventory/ # 库存管理
└── Application.java # Spring Boot 应用程序，启用 @EnableAgentMcpServer
```
## 代理工作原理
1. **输入处理**：客户请求使用 LLM 解析以提取：
- 订单 ID
- 期望操作（退款/更换）
- 客户情感
2. **业务逻辑**：代理检查：
- 订单是否存在
- 当前库存水平
- 客户偏好
3. **决策**：根据条件：
- 如果有库存，则提供更换
- 如果没有库存或客户更喜欢退款，则处理退款
4. **响应生成**：LLM 生成考虑客户情感的个性化响应
## 了解更多关于 Embabel 的信息
- **GitHub 仓库**：[embabel-agent](https://github.com/embabel/embabel-agent)
- **Rod Johnson 的博客**：[Medium @springrod](https://medium.com/@springrod) - 包含深入的示例和教程
- **框架文档**：可在 embabel-agent 仓库中找到
## API 示例
虽然代理处理大多数操作，但您也可以与底层服务交互：
```bash
# 检查库存
curl http://localhost:8080/api/inventory
# 创建订单
curl -X POST http://localhost:8080/api/orders \
-H "Content-Type: application/json" \
-d '{"sku": "shirt-m"}'
# 列出订单
curl http://localhost:8080/api/orders
```
## 依赖项
主要的 Embabel 依赖项已添加到 `pom.xml`：
```xml
<dependency>
<groupId>com.embabel.agent</groupId>
<artifactId>embabel-agent-starter</artifactId>
<version>0.1.1-SNAPSHOT</version>
</dependency>
```
## 下一步
1. 探索 `CustomerSupportAgent.java` 以了解 Embabel 模式
2. 尝试修改条件以更改代理行为
3. 为其他客户支持场景添加新操作
4. 阅读 Rod Johnson 的博客文章以获取高级 Embabel 技术
5. 查看 embabel-agent 仓库以获取更多示例
