Content
# NagaAgent
[简体中文](README.md)|[繁體中文](README_tw.md)|[English](README_en.md)
---
## [Get tutorial videos and one-click run package here](https://www.pylindex.top/naga)
## Introduction
NagaAgent is a feature-rich intelligent dialogue assistant system with the following key features:
### 🎯 Core Features
- **Intelligent Dialogue System**: Supports streaming dialogue and tool invocation loops
- **Multi-Agent Collaboration**: Intelligent task scheduling based on game theory
- **Knowledge Graph Memory**: GRAG system supports long-term memory and intelligent retrieval
- **Complete Voice Interaction**: Real-time voice input and output processing
- **Modern Interface**: PyQt5 GUI + Live2D virtual avatar
- **System Tray Integration**: Background operation and quick actions
### 🛠️ Technical Architecture
#### Overall System Architecture
```mermaid
graph TB
%% User Interface Layer
subgraph "User Interface Layer (UI Layer)"
UI[PyQt5 GUI]
Live2D[Live2D Virtual Avatar]
Tray[System Tray]
Chat[Chat Interface]
end
%% Core Services Layer
subgraph "Core Services Layer (Core Services)"
API[API Server<br/>:8000]
Agent[Agent Server<br/>:8001]
MCP[MCP Server<br/>:8003]
TTS[TTS Server<br/>:5048]
end
%% Business Logic Layer
subgraph "Business Logic Layer (Business Logic)"
Game[Game Theory System<br/>Multi-Agent Collaboration]
Memory[GRAG Memory System<br/>Knowledge Graph]
Voice[Voice Processing System<br/>Real-time Voice Interaction]
Tools[Tool Invocation System<br/>MCP Protocol]
end
%% Data Storage Layer
subgraph "Data Storage Layer (Data Storage)"
Neo4j[(Neo4j Graph Database<br/>Knowledge Graph Storage)]
Files[File System<br/>Configuration/Logs/Cache]
MemoryCache[Memory Cache<br/>Session State]
end
%% External Services Layer
subgraph "External Services Layer (External Services)"
LLM[LLM Service Providers<br/>OpenAI/Tongyi Qianwen, etc.]
Portal[NagaPortal<br/>Portal Service]
MQTT[IoT Devices<br/>MQTT Communication]
Web[Web Crawler<br/>Online Search]
end
%% Connection Relationships
UI --> API
UI --> Agent
UI --> MCP
UI --> TTS
API --> Game
API --> Memory
API --> Voice
API --> Tools
Agent --> Game
Agent --> Tools
MCP --> Tools
MCP --> Portal
MCP --> MQTT
MCP --> Web
TTS --> Voice
Game --> Memory
Memory --> Neo4j
Voice --> LLM
Tools --> LLM
API --> MemoryCache
Agent --> MemoryCache
MCP --> MemoryCache
%% Styles
classDef uiLayer fill:#e1f5fe
classDef coreLayer fill:#f3e5f5
classDef businessLayer fill:#e8f5e8
classDef dataLayer fill:#fff3e0
classDef externalLayer fill:#fce4ec
class UI,Live2D,Tray,Chat uiLayer
class API,Agent,MCP,TTS coreLayer
class Game,Memory,Voice,Tools businessLayer
class Neo4j,Files,MemoryCache dataLayer
class LLM,Portal,MQTT,Web externalLayer
```
#### Core Characteristics
- **Multi-Service Parallelism**: API Server (8000), Agent Server (8001), MCP Server (8003), TTS Server (5048)
- **Modular Design**: Each service runs independently, supporting hot-swapping
- **Configuration Driven**: Real-time configuration hot updates without restarting
- **Cross-Platform Support**: Windows, macOS, Linux
### 🔧 Tech Stack
#### Tech Stack Architecture
```mermaid
graph TB
%% Frontend Tech Stack
subgraph "Frontend Tech Stack (Frontend Stack)"
PyQt5[PyQt5<br/>GUI Framework]
Live2D[Live2D<br/>Virtual Avatar]
QSS[QSS<br/>Stylesheet]
end
%% Backend Tech Stack
subgraph "Backend Tech Stack (Backend Stack)"
FastAPI[FastAPI<br/>Web Framework]
Uvicorn[Uvicorn<br/>ASGI Server]
AsyncIO[AsyncIO<br/>Asynchronous Programming]
end
%% Database Tech Stack
subgraph "Database Tech Stack (Database Stack)"
Neo4j[Neo4j<br/>Graph Database]
GRAG[GRAG<br/>Knowledge Graph]
Memory[Memory Cache<br/>Session Management]
end
%% AI Tech Stack
subgraph "AI Tech Stack (AI Stack)"
OpenAI[OpenAI API<br/>GPT Model]
Qwen[Tongyi Qianwen<br/>Multimodal Model]
MCP[MCP Protocol<br/>Tool Invocation]
end
%% Voice Tech Stack
subgraph "Voice Tech Stack (Voice Stack)"
ASR[Speech Recognition<br/>ASR]
TTS[Text-to-Speech<br/>TTS]
Realtime[Real-time Voice<br/>WebRTC]
end
%% Network Tech Stack
subgraph "Network Tech Stack (Network Stack)"
HTTP[HTTP/HTTPS<br/>RESTful API]
WebSocket[WebSocket<br/>Real-time Communication]
MQTT[MQTT<br/>IoT Protocol]
end
%% Styles
classDef frontend fill:#e3f2fd
classDef backend fill:#f1f8e9
classDef database fill:#fff3e0
classDef ai fill:#fce4ec
classDef voice fill:#e8f5e8
classDef network fill:#f3e5f5
class PyQt5,Live2D,QSS frontend
class FastAPI,Uvicorn,AsyncIO backend
class Neo4j,GRAG,Memory database
class OpenAI,Qwen,MCP ai
class ASR,TTS,Realtime voice
class HTTP,WebSocket,MQTT network
```
#### Core Technologies
- **Python 3.11** + PyQt5 + FastAPI
- **Neo4j Graph Database** + GRAG Knowledge Graph
- **MCP (Model Context Protocol)** Tool Invocation
- **OpenAI Compatible API** + Support for Various LLM Service Providers
---
## Deployment and Running Guide
### Environment Requirements
- Python 3.11
- Optional: uv tool (to speed up dependency installation without requiring a specific Python version)
### Quick Start
> If you encounter difficulties during deployment, you can refer to the video tutorial or download the one-click run package.
#### 1. Install Dependencies
##### Using setup script
```bash
# Optional: Install uv first
pip install uv
# Automatically initialize using setup.py
python setup.py
# Or use setup.sh (Linux/macOS)
./setup.sh
# Or use setup.bat (Windows)
setup.bat
```
The initialization script will automatically:
- Check Python version
- Create a virtual environment
- Install dependencies
- Copy configuration file templates
- Open the configuration file for editing
</details>
<details><summary>Manual Deployment</summary>
```bash
# Without uv
python -m venv .venv
# Linux/Mac OS
source .venv/bin/activate
# Windows
.\.venv\Scripts\activate
pip install -r requirements.txt
# Using uv
uv sync
```
</details>
#### 2. Configure LLM API
Edit the `config.json` file to configure your LLM API information:
```json
{
"api": {
"api_key": "your_api_key",
"base_url": "Model Service Provider OPENAI API Endpoint",
"model": "Model Name"
}
}
```
<details><summary>Optional Configuration</summary>
#### Enable Knowledge Graph Memory
Install `neo4j` using `docker` or install `neo4j desktop` and configure the Neo4j connection parameters in `config.json`:
```json
{
"grag": {
"enabled": true,
"neo4j_uri": "neo4j://127.0.0.1:7687",
"neo4j_user": "neo4j",
"neo4j_password": "the password you set when installing neo4j"
}
}
```
#### Enable Voice Output Functionality
```json
{
"system": {
"voice_enabled": true
},
"tts": {
"port": 5048
}
}
```
#### Live2D Related Configuration
```json5
"live2d": {
"enabled": false, # Enable Live2D
"model_path": "ui/live2d/live2d_models/characters/llny/mianfeimox/llny.model3.json", # Live2D model path
"fallback_image": "ui/img/standby.png", # Fallback image
"auto_switch": true, # Enable auto switch
"animation_enabled": true, # Enable animation
"touch_interaction": true # Enable touch interaction
},
```
> Other configuration items can refer to the comments
</details>
#### 3. Start the Application
```bash
# Using start script
./start.sh # Linux/macOS
start.bat # Windows
# Or run the py file directly
# Linux/Mac OS
source .venv/bin/activate
# Windows
.\.venv\Scripts\activate
python main.py
# Using uv
uv run main.py
```
<details><summary>Troubleshooting</summary>
1. **Incompatible Python Version**: Ensure you are using Python 3.11
2. **Port Occupied**: Check if ports 8000, 8001, 8003, and 5048 are available
3. **Neo4j Connection Failed**: Ensure the Neo4j service is running
4. **JSON Parsing Error When Checking Neo4j Connection**: Exit and restart the program
5. **Unknown Error**: Please create an issue to provide feedback
</details>
<details><summary>Environment Check</summary>
```bash
# Run system environment check
python main.py --check-env --force-check
# Quick check
python main.py --quick-check
```
</details>
## License
[NagaAgent License](LICENSE)
## Contribution
Feel free to create Issues and Pull Requests!
<details><summary>Build One-Click Run Package</summary>
```bash
python build.py
```
The built files will be located in the `dist/` directory
</details>
<div align="center">
**Thanks to all developers for their contributions to this project**
**⭐ If this project has been helpful to you, please consider giving us a Star**
</div>
