# agent-framework
**Repository Path**: TobyChow/agent-framework
## Basic Information
- **Project Name**: agent-framework
- **Description**: agent-framework
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 3
- **Created**: 2025-06-19
- **Last Updated**: 2025-06-19
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Agent Framework: 多智能体应用开发框架
  
## 🌟 项目简介
Agent Framework 是一个基于Java SpringBoot生态的多智能体开发框架，融合AI能力、分布式通信与模块化设计，帮助开发者快速构建灵活可扩展的多智能体应用。框架集成Spring AI、MCP协议及事件驱动架构，通过金花游戏示例展示其在复杂业务场景下的适配能力。
## 🚀 核心技术栈
### 🔹 智能能力集成
- **Spring AI无缝对接**：通过模块实现主流LLM模型(OpenAI/Deepseek/dashscope)调用，支持提示词工程与函数调用
- **决策引擎**：内置规则引擎与AI推理协同机制，支持复杂场景下的智能决策
### 🔹 多智能体通信
- **消息队列**：基于内存队列实现代理间松耦合通信，支持消息持久化与重试机制
### 🔹 架构设计
- **模块化分层**：核心层(agent-core)、通用工具层(agent-common)、Spring集成层(agent-spring-boot-*)清晰分离
- **可扩展性**：抽象智能体(Agent)、环境(Environment)、动作(Action)与工具(Tool)体系
## 📚 快速开发指南
### 环境要求
- JDK 17+
- Maven 3.9+
- Spring Boot 3.3+
### 环境配置
1. **添加依赖**
```xml
com.agentframework
agent-spring-boot-starter
latest-version
```
2. **配置环境**
```yaml
spring:
ai:
deepseek:
api-key: ${DEEPSEEK_API_KEY}
```
3. **MCP配置**
```yaml
spring:
ai:
mcp:
client:
enabled: false
stdio:
servers-configuration: classpath:mcp-servers.json
```
### 创建自定义Agent
```java
@Agent(name = "my-agent")
public class MyAgent extends AbstractAgent {
@Override
public void react() {
// 消息处理逻辑
}
protected int observe() throws InterruptedException {
// 消息观察
return 0;
}
}
```
### 创建自定义Action
```java
@Action(name = "my-action")
public class MyAction extends AbstractAction {
@Override
public AssistantMessage execute(AgentContext context) {
AssistantMessage response = super.execute(messages);
handleResponseMessage(response, getResponseType());
return response;
}
}
```
### 绑定Action到Agent
```java
@Agent(name = "my-agent", actions = { MyAction.class })
public class MyAgent extends AbstractAgent {
}
```
### 创建自定义环境并绑定Agent
```java
@Environment(name = "myEnvironment", agents = {MyAgent.class, MyAgent2.class})
public class MyEnvironment extends AbstractEnvironment {
}
```
### 运行环境
```java
public class Test {
@Resource
private MyEnvironment myEnvironment;
@Test
public void test() {
// 显式调用环境的run方法启动
myEnvironment.run();
}
}
```
## 🎮 示例应用：金花扑克小游戏
### 游戏简介
基于框架实现的经典扑克游戏，展示多智能体协作、消息通信、状态管理与数据持久化能力。通过游戏示例可直观了解框架在实际业务场景中的灵活应用。
### 核心设计逻辑
1. **状态驱动**：统一管理游戏生命周期
- 牌局状态维护（发牌/下注/比牌/结算）
- 玩家状态快照与历史记录
- 输赢计算与数据导出
2. **动作处理**：实现业务逻辑
- 玩家动作解析与验证
- 游戏规则执行
- 结果消息生成
### 📋 运行步骤
#### 环境准备
```bash
# 1. 克隆项目
git clone https://github.com/your-org/agent-framework.git
cd agent-framework
# 2. 构建项目
mvn clean package -DskipTests
# 3. 配置大模型
api-key: ${DEEPSEEK_API_KEY}
（本游戏在deepseek模型上测试通过）
```
#### 启动游戏
```bash
# 运行金花游戏示例
class JinhuaGameTest2 {
@Resource
private JinhuaEnvironment jinhuaEnvironment;
@Test
public void testJinhuaGame() {
// 显式调用环境的run方法启动游戏
jinhuaEnvironment.run();
}
}
```
### 📊 示例输出
```
09:04:49.320 [main] DEBUG c.a.examples.jinhua.JinhuaStarted -- JinhuaStarted 玩家： [Agent{agentName='player-1', agentId='c8d1c4fb'}, Agent{agentName='player-2', agentId='7166f581'}, Agent{agentName='player-3', agentId='0e1b9825'}]
09:04:49.321 [main] DEBUG c.a.examples.jinhua.JinhuaStarted -- JinhuaStarted 荷官： Agent{agentName='荷官：JinhuaGameDealer', agentId='1a600f28'}
09:04:49.324 [main] DEBUG c.a.e.jinhua.JinhuaGameEndCondition -- JinhuaGameEndCondition -> shouldEnd -> JinhuaGameState: JinhuaGameState{players=[PlayerInfo{playerId='c8d1c4fb', cards=[], viewed=false, currentBet=0, balance=1000, active=true, totalWinLoss=0}, PlayerInfo{playerId='7166f581', cards=[], viewed=false, currentBet=0, balance=1000, active=true, totalWinLoss=0}, PlayerInfo{playerId='0e1b9825', cards=[], viewed=false, currentBet=0, balance=1000, active=true, totalWinLoss=0}], minBet=5, currentRound=1, totalRounds=1}
09:04:49.334 [main] DEBUG c.a.c.e.AbstractEnvironment -- >>>>>put message to agent 荷官：JinhuaGameDealer - 1a600f28 process message UserMessage{content='游戏开始', properties={send_to=[1a600f28], messageType=USER, action=start_new_round}, messageType=USER}
09:04:49.335 [AgentProcessor-1a600f28] DEBUG c.a.core.agent.AbstractAgent -- agent Agent{agentName='荷官：JinhuaGameDealer', agentId='1a600f28'} deque messages [UserMessage{content='游戏开始', properties={send_to=[1a600f28], messageType=USER, action=start_new_round}, messageType=USER}]
09:04:49.336 [AgentProcessor-1a600f28] DEBUG c.a.core.agent.AbstractAgent -- Agent{agentName='荷官：JinhuaGameDealer', agentId='1a600f28'} news [UserMessage{content='游戏开始', properties={send_to=[1a600f28], messageType=USER, action=start_new_round}, messageType=USER}]
09:04:49.499 [AgentProcessor-1a600f28] DEBUG c.agentframework.core.provider.Llm -- Agent{agentName='荷官：JinhuaGameDealer', agentId='1a600f28'} Starting LLM call
09:04:55.645 [boundedElastic-1] DEBUG c.a.c.tools.AgentToolCallingManager -- Executing tool call: dealCards
09:04:55.665 [boundedElastic-1] DEBUG o.s.a.tool.method.MethodToolCallback -- Starting execution of tool: dealCards
09:04:55.668 [boundedElastic-1] DEBUG o.s.a.tool.method.MethodToolCallback -- Successful execution of tool: dealCards
09:04:55.668 [boundedElastic-1] DEBUG o.s.a.t.e.DefaultToolCallResultConverter -- Converting tool result to JSON.
{
"round": "1",
"message": "第1轮游戏开始，已发牌",
"sendTo": "c8d1c4fb"
}
...
09:06:39.062 [AgentProcessor-1a600f28] DEBUG c.a.core.action.AbstractAction -- 玩家c8d1c4fb与7166f581比牌，c8d1c4fb获胜
09:06:39.062 [AgentProcessor-0e1b9825] DEBUG c.a.core.agent.AbstractAgent -- agent Agent{agentName='player-3', agentId='0e1b9825'} deque messages [UserMessage{content='玩家c8d1c4fb与7166f581比牌，c8d1c4fb获胜', properties={send_to=[0e1b9825, c8d1c4fb, 7166f581], msg_from=1a600f28, messageType=USER, view_to=[0e1b9825, c8d1c4fb, 7166f581]}, messageType=USER}]
09:06:39.062 [AgentProcessor-1a600f28] DEBUG c.a.core.action.AbstractAction -- >>>CompareAction doHandleResponseMessage 只剩下一名玩家存活，本轮结束，开启新的一轮
09:06:39.065 [AgentProcessor-1a600f28] DEBUG c.a.core.action.AbstractAction -- 游戏已经达到最大轮数，游戏结束
09:06:39.068 [INFO] 游戏记录已导出至：..\agent-framework\data\jinhua\game_record_20231001.csv
```
### 🔍 框架灵活性体现
- **业务解耦**：游戏规则与框架核心完全分离，可独立修改游戏逻辑
- **状态扩展**：通过继承`GameState`抽象类快速实现新游戏类型
- **AI集成**：可通过Spring AI模块为游戏添加智能NPC对手
- **数据持久化**：支持自定义导出格式（CSV/JSON）与存储路径
## 📄 文档与资源
- **架构设计**：
- **API文档**：`mvn javadoc:javadoc`生成完整API文档
- **示例代码**：
## 📜 许可证
本项目采用Apache 2.0许可证 - 详见