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. 添加依赖

<dependency>
    <groupId>com.agentframework</groupId>
    <artifactId>agent-spring-boot-starter</artifactId>
    <version>latest-version</version>
</dependency>

2. 配置环境

spring:
  ai:
    deepseek: 
      api-key: ${DEEPSEEK_API_KEY}

3. MCP配置

spring:
   ai:
    mcp:
      client:
        enabled: false
      stdio:
        servers-configuration: classpath:mcp-servers.json

创建自定义Agent

@Agent(name = "my-agent")
public class MyAgent extends AbstractAgent {
    @Override
    public void react() {
        // 消息处理逻辑
    }
    
    protected int observe() throws InterruptedException {
        // 消息观察
        return 0;    
    }
    
}

创建自定义Action

@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

@Agent(name = "my-agent", actions = { MyAction.class })
public class MyAgent extends AbstractAgent {
    
}

创建自定义环境并绑定Agent

@Environment(name = "myEnvironment", agents = {MyAgent.class, MyAgent2.class})
public class MyEnvironment extends AbstractEnvironment {
    
}

运行环境

public class Test {

   @Resource
   private MyEnvironment myEnvironment;
    
   @Test
   public void test() {
       // 显式调用环境的run方法启动
       myEnvironment.run();
   }
}

🎮 示例应用：金花扑克小游戏

游戏简介

基于框架实现的经典扑克游戏，展示多智能体协作、消息通信、状态管理与数据持久化能力。通过游戏示例可直观了解框架在实际业务场景中的灵活应用。

核心设计逻辑

1. 状态驱动：统一管理游戏生命周期

   • 牌局状态维护（发牌/下注/比牌/结算）
   • 玩家状态快照与历史记录
   • 输赢计算与数据导出

2. 动作处理：实现业务逻辑

   • 玩家动作解析与验证
   • 游戏规则执行
   • 结果消息生成

📋 运行步骤

环境准备

# 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模型上测试通过）

启动游戏

# 运行金花游戏示例
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许可证 - 详见