# 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: Multi-Agent Application Development Framework

![Java](https://img.shields.io/badge/Java-17+-blue.svg) ![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.0+-green.svg) ![Apache License](https://img.shields.io/badge/License-Apache%202.0-yellow.svg)

## 🌟 Project Introduction
Agent Framework is a Java-based multi-agent development framework that integrates AI capabilities, distributed communication, and modular design to help developers quickly build flexible and scalable multi-agent applications. The framework integrates Spring AI, MCP protocol, and event-driven architecture, demonstrating its adaptability in complex business scenarios through the Jinhua Poker game example.

## 🚀 Core Technology Stack

### 🔹 Intelligent Capability Integration
- **Seamless Spring AI Integration**: The <mcmodule name="spring-ai"></mcmodule> module enables calls to mainstream LLM models (OpenAI/Deepseek/dashscope), supporting prompt engineering and function calls
- **Decision Engine**: Built-in rule engine and AI reasoning coordination mechanism to support intelligent decision-making in complex scenarios

### 🔹 Multi-Agent Communication
- **Message Queue**: Implements loosely coupled communication between agents based on in-memory queues, supporting message persistence and retry mechanisms

### 🔹 Architecture Design
- **Modular Layering**: Clear separation of core layer (agent-core), common tools layer (agent-common), and Spring integration layer (agent-spring-boot-*)
- **Extensibility**: Action and Tool system architecture

## 📚 Quick Start Guide

### Environment Requirements
- JDK 17+ 
- Maven 3.9+
- Spring Boot 3.3+

### Environment Configuration
1. **Add Dependency**
```xml
<dependency>
    <groupId>com.agentframework</groupId>
    <artifactId>agent-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>
```

2. **Configure Environment**
```yaml
spring:
  ai:
    deepseek: 
      api-key: ${DEEPSEEK_API_KEY}
```

3. **MCP Configuration**
```yaml
spring:
  ai:
    mcp:
      client:
        enabled: false
      stdio:
        servers-configuration: classpath:mcp-servers.json
```

### Create Custom Agent
```java
@Agent(name = "my-agent")
public class MyAgent extends AbstractAgent {
    @Override
    public void react() {
        // Message processing logic
    }
    
    protected int observe() throws InterruptedException {
        // Message observation
        return 0;    
    }
    
}
```

### Create Custom 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;
    }
}
```

### Bind Action to Agent
```java
@Agent(name = "my-agent", actions = { MyAction.class })
public class MyAgent extends AbstractAgent {
    
}
```

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

### Run Environment
```java
public class Test {

   @Resource
   private MyEnvironment myEnvironment;
    
   @Test
   public void test() {
       // Explicitly call the environment's run method to start
       myEnvironment.run();
   }
}

```

## 🎮 Example Application: Jinhua Poker Game

### Game Introduction
A classic poker game implemented based on the framework, demonstrating multi-agent collaboration, message communication, state management, and data persistence capabilities. The game example provides an intuitive understanding of how the framework can be applied in real business scenarios.

### Core Design Logic
1. **State-Driven**: <mcsymbol name="JinhuaGameState" filename="JinhuaGameState.java" path="agent-examples/src/main/java/com/agentframework/examples/jinhua/JinhuaGameState.java" startline="25" type="class"></mcsymbol> unified management of game lifecycle
   - Game round state maintenance (dealing/betting/comparing/settling)
   - Player state snapshots and history records
   - Win/loss calculation and data export

2. **Action Processing**: <mcsymbol name="CompareAction" filename="CompareAction.java" path="agent-examples/src/main/java/com/agentframework/examples/jinhua/CompareAction.java" startline="30" type="class"></mcsymbol> implements business logic
   - Player action parsing and validation
   - Game rule execution
   - Result message generation

### 📋 Running Steps

#### Environment Preparation
```bash
# 1. Clone the project
git clone https://github.com/your-org/agent-framework.git
cd agent-framework

# 2. Build the project
mvn clean package -DskipTests

# 3. Configure LLM
api-key: ${DEEPSEEK_API_KEY}
  (This game has been tested on the DeepSeek model)
```

#### Start the Game
```bash
# Run Jinhua game example
class JinhuaGameTest2 {

    @Resource
    private JinhuaEnvironment jinhuaEnvironment;

    @Test
    public void testJinhuaGame() {
        // Explicitly call the environment's run method to start the game
        jinhuaEnvironment.run();
    }
}
```

### 📊 Example Output
```
09:04:49.320 [main] DEBUG c.a.examples.jinhua.JinhuaStarted -- JinhuaStarted Players: [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 Dealer: Agent{agentName='Dealer: 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 Dealer: JinhuaGameDealer - 1a600f28 process message UserMessage{content='Game started', 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='Dealer: JinhuaGameDealer', agentId='1a600f28'} deque messages [UserMessage{content='Game started', 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='Dealer: JinhuaGameDealer', agentId='1a600f28'} news [UserMessage{content='Game started', 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='Dealer: 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": "Round 1 started, cards dealt",
 "sendTo": "c8d1c4fb"
}
...
09:06:39.062 [AgentProcessor-1a600f28] DEBUG c.a.core.action.AbstractAction -- Player c8d1c4fb vs 7166f581, c8d1c4fb wins
09:06:39.062 [AgentProcessor-0e1b9825] DEBUG c.a.core.agent.AbstractAgent -- agent Agent{agentName='player-3', agentId='0e1b9825'} deque messages [UserMessage{content='Player c8d1c4fb vs 7166f581, c8d1c4fb wins', 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 Only one player remaining, round ended, starting new round
09:06:39.065 [AgentProcessor-1a600f28] DEBUG c.a.core.action.AbstractAction -- Maximum rounds reached, game ended
2023-10-01 15:30:10 [INFO] Game record exported to: ..\agent-framework\data\jinhua\game_record_20231001.csv
```

### 🔍 Framework Flexibility
- **Business Decoupling**: Game rules are completely separated from the framework core, allowing independent modification of game logic
- **State Extension**: Quickly implement new game types by inheriting the `GameState` abstract class
- **AI Integration**: Add intelligent NPC opponents to the game through the Spring AI module
- **Data Persistence**: Support custom export formats (CSV/JSON) and storage paths

## 📄 Documentation and Resources
- **Architecture Design**: <mcfile name="jinhua-message-architecture.md" path="doc/jinhua-message-architecture.md"></mcfile>
- **API Documentation**: Generate complete API documentation with `mvn javadoc:javadoc`
- **Example Code**: <mcfolder name="agent-examples" path="agent-examples"></mcfolder>

## 📜 License
This project is licensed under the Apache 2.0 License - see the <mcfile name="LICENSE" path="LICENSE"></mcfile> file for details.