# agent-framework **Repository Path**: xjd2020/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**: 14 - **Forks**: 3 - **Created**: 2025-05-21 - **Last Updated**: 2025-07-24 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Agent Framework: 多智能体应用开发框架 ## 🌟 项目简介 本项目是一个基于Java SpringBoot生态的多智能体应用开发框架，旨在简化智能体开发流程，支持以下核心功能： - 智能体自主规划工作流 - 自定义工作流 - 多智能体通信 - 灵活的架构设计 框架支持创建多个智能体实例，并通过环境类统一管理消息交互与状态流转。示例中实现了金花扑克游戏，展示了框架的实际应用。 ## 🚀 核心技术栈 - **智能能力集成**：通过 Llm 类封装了大模型调用逻辑，支持多种模型提供方（如 Dashscope、DeepSeek、Ollama等） - **多智能体通信**：通过 Environment 和 AgentContext 实现智能体间的消息发布与消费 - **工具调用**：支持通过 ToolCallingManager 实现工具调用与执行 - **Spring Boot 自动配置**：提供 AgentAutoConfiguration，实现自动扫描 Agent、Action 和 Environment 的注册 ## 📚 快速开发指南 ### 环境要求 - Java 17 或更高版本 - Maven 3.6+ - Dashscope 或其他 LLM 服务的 API Key（可选） - Spring Boot 3.0+ ### 环境配置 1. 安装 JDK 17 或更高版本 2. 配置 Maven 并确保依赖管理正常工作 3. 在 `application.properties` 或 `application.yml` 中配置 LLM 提供商信息，例如： ```properties llm.timeout.seconds=30 llm.retry.max=3 llm.retry.initialDelaySeconds=1 llm.stream.bufferSize=100 llm.circuitBreaker.enabled=true llm.circuitBreaker.failureRate=0.5 llm.circuitBreaker.waitDurationSeconds=10 # Dashscope 配置示例 spring.ai.dashscope.apiKey=your_api_key spring.ai.deepseek.apiKey=your_deepseek_key ``` ### 创建自定义 Agent 创建一个继承 `AbstractAgent` 的类，例如： ```java @Agent(name = "myCustomAgent") public class MyCustomAgent extends AbstractAgent { public MyCustomAgent(String name) { super(name); // 默认使用 LlmType.AUTO } @Override public String getAgentProfile() { return "这是一个自定义智能体"; } } ``` ### 创建自定义 Action 创建一个继承 `AbstractAction` 的类并实现 `doExecute` 方法： ```java @Action(name = "my_custom_action", order = 1) public class MyCustomAction extends AbstractAction { public MyCustomAction(String name) { super(name); } @Override protected Prompt doExecute(List messages) { // 实现具体动作逻辑 return new Prompt("执行自定义动作"); } } ``` ### 绑定 Action 到 Agent 使用@Agent注解的actions属性为智能体绑定动作： ```java @Agent(name = "myCustomAgent", actions= {MyCustomAction.class}) public class MyCustomAgent extends AbstractAgent { } ``` ### 创建自定义 Environment 创建一个继承 `AbstractEnvironment` 的类，并管理智能体的生命周期和消息流转： ```java @Environment(name = "myEnvironment", agents = {MyAgent.class, MyAgent2.class}) public class MyCustomEnvironment extends AbstractEnvironment { public MyCustomEnvironment() { super(); } @Override protected void init() { // 初始化逻辑 } @Override public void run() { // 启动环境并运行智能体 } } ``` ### 启动 Environment 在 Spring Boot 应用中注入并启动环境： ```java public class JinhuaGameApplication { @Resource private MyCustomEnvironment myEnvironment; public static void main(String[] args) { JinhuaGameApplication.run(JinhuaGameApplication.class, args); myEnvironment.run(); } } ``` ## 🎭 单智能体示例：Playwright网页自动化 ### 功能简介 PlaywrightAgent展示了框架在单智能体模式下的网页自动化能力，支持浏览器控制、页面交互和截图功能。 ### 实现类结构 ```text com.agentframework.examples.playwright/ ├── PlaywrightAgent.java // 核心智能体实现 └── ScreenshotAction.java // 网页截图动作实现 ``` ### 核心代码实现 #### 1. PlaywrightAgent智能体 ```java package com.agentframework.examples.playwright; public class PlaywrightAgent extends PlanAgent { final String prompt = """ 你能够通过Playwright启动浏览器，你有网页导航、网页截图、能够通过工具`getPageContent`提取网页源码、自动根据html定位页面元素等能力。 注意：定位元素前一定要先调用`getPageContent`工具获取到网页html代码 """; @Override protected String profile() { return prompt; } } ``` #### 2. PlaywrightTool网页操作工具类 ```java package com.agentframework.examples.playwright; public class PlaywrightTool implements AgentTool { } ``` #### 3. PlanAgent自动编排智能体 ```java package com.agentframework.examples.playwright; public abstract class PlanAgent extends AbstractAgent { @Override protected AssistantMessage react() { if (!StringUtils.hasText(planner.getPlan().getGoal())) { planner.createPlan(this, getLatestMessage().getText()); } while (planner.getPlan().getCurrentTask() != null) { Task task = planner.getPlan().getCurrentTask(); logger.debug("ready to take Task {}", task.getTaskId()); TaskResult result = actOnTask(task); planner.processTaskResult(this, result); } return null; } } ``` ### 测试用例 测试类位于`com.agentframework.examples.AgentTest`，具体测试方法： ```java public class Test { @Test public void testPlaywrightAgent() throws IOException { String web_url = "https://mail.163.com/"; String prompt = """ 这是网页的URL：“%s”。 首先，给你账号xxx@163.com，密码：xxxpassword。(请设置自己的邮箱账号，密码) 其次，打开这个网页地址，自动分析网页dom结构，找到登录界面的账号密码输入框，然后输入提供的账号密码，帮我登录进去。 """; playwrightAgent.run(String.format(prompt, web_url)); } } ``` ## 🎮 多智能体应用：金花扑克小游戏 ### 游戏简介 金花扑克是一款流行的中国纸牌游戏，支持多人比牌、下注、弃牌等逻辑。本框架通过 `JinhuaEnvironment` 和 `JinhuaDealerAgent` 模拟了游戏的流程。 ### 核心设计逻辑 - **环境层**：`JinhuaEnvironment` 管理游戏状态与智能体交互 - **荷官（Dealer）**：`JinhuaDealerAgent` 负责控制游戏流程，包括发牌、下注、比牌等 - **玩家（Player）**：`JinhuaPlayerAgent` 代表游戏参与者，可执行 `PlayerAction` - **游戏状态（GameState）**：`JinhuaGameState` 维护游戏的核心状态，包括玩家、牌、下注、比牌等 - **工具（Tool）**：`JinhuaTool` 提供游戏操作接口，如发牌、看牌、下注等 ### 📋 运行步骤 1. **环境准备** - 克隆项目： ```bash git clone https://gitee.com/xjd2020/agent-framework.git ``` - 构建项目： ```bash mvn clean package ``` - 配置 LLM： - 在 `application.yaml` 中配置 LLM 提供商，如 Dashscope、DeepSeek等 2. **启动游戏** - 使用 `JinhuaEnvironment` 启动游戏： ```java @SpringBootApplication public class JinhuaGameApplication { public static void main(String[] args) { SpringApplication.run(JinhuaGameApplication.class, args); } } ``` - 在 Spring 配置中注入环境并运行： ```java @Service public class JinhuaService { @Autowired private JinhuaEnvironment jinhuaEnvironment; public void runGame() { jinhuaEnvironment.run(); } } ``` 3. **运行金花游戏示例** - 示例测试类 `JinhuaGameTest` 展示了如何运行游戏： ```java @SpringBootTest(classes = { JinhuaEnvironment.class, JinhuaDealerAgent.class, JinhuaPlayerAgent.class }) public class JinhuaGameTest { @Autowired private JinhuaEnvironment environment; @Test public void testJinhuaGame() { environment.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 ``` ## 🔍 框架灵活性体现 - 可扩展的 Agent 和 Action：支持多种智能体和动作的自定义开发 - 支持多 LLM 提供商：通过 `Llm` 和 `Provider` 接口支持多个 LLM 服务 - 工具系统：通过 `ToolManager` 和 `AgentToolCallingManager` 实现工具管理与调用 - 消息路由与监听：通过 `AgentContext` 和 `EnvironmentListeners` 实现消息队列和环境事件监听 ## 📄 文档与资源 - **框架文档**：请查阅 `doc/` 目录下的相关说明 - **Spring Boot 集成**：`agent-spring-boot-autoconfigure` 模块提供 Spring Boot 自动配置 - **LLM 支持**：支持 Dashscope、DeepSeek、Ollama等 ## 📜 许可证 本项目采用 Apache 2.0 协议，详细内容请参阅 `LICENSE` 文件。