Skip to content

A simple yet powerful agent framework for personal assistants, designed to enable intelligent interaction, multi-agent collaboration, and seamless tool integration.

License

Notifications You must be signed in to change notification settings

Xxiii8322766509/NagaAgent

Repository files navigation

NagaAgent

简体中文|繁體中文|English

NagaAgent Logo Platform License Python Status

Star HistoryForksIssuesPull Requests UI 预览

介绍

NagaAgent 是一个功能丰富的智能对话助手系统,具有以下特色功能:

🎯 核心功能

  • 智能对话系统:支持流式对话和工具调用循环
  • 多Agent协作:基于博弈论的智能任务调度
  • 知识图谱记忆:GRAG系统支持长期记忆和智能检索
  • 完整语音交互:实时语音输入输出处理
  • 现代化界面:PyQt5 GUI + Live2D虚拟形象
  • 系统托盘集成:后台运行和快捷操作

🛠️ 技术架构

系统整体架构

graph TB
    %% 用户界面层
    subgraph "用户界面层 (UI Layer)"
        UI[PyQt5 GUI界面]
        Live2D[Live2D虚拟形象]
        Tray[系统托盘]
        Chat[聊天界面]
    end

    %% 核心服务层
    subgraph "核心服务层 (Core Services)"
        API[API服务器<br/>:8000]
        Agent[Agent服务器<br/>:8001]
        MCP[MCP服务器<br/>:8003]
        TTS[TTS服务器<br/>:5048]
    end

    %% 业务逻辑层
    subgraph "业务逻辑层 (Business Logic)"
        Game[博弈论系统<br/>多Agent协作]
        Memory[GRAG记忆系统<br/>知识图谱]
        Voice[语音处理系统<br/>实时语音交互]
        Tools[工具调用系统<br/>MCP协议]
    end

    %% 数据存储层
    subgraph "数据存储层 (Data Storage)"
        Neo4j[(Neo4j图数据库<br/>知识图谱存储)]
        Files[文件系统<br/>配置/日志/缓存]
        MemoryCache[内存缓存<br/>会话状态]
    end

    %% 外部服务层
    subgraph "外部服务层 (External Services)"
        LLM[LLM服务商<br/>OpenAI/通义千问等]
        Portal[NagaPortal<br/>门户服务]
        MQTT[物联网设备<br/>MQTT通讯]
        Web[网络爬虫<br/>在线搜索]
    end

    %% 连接关系
    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
    
    %% 样式
    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

Loading

核心特性

  • 多服务并行:API服务器(8000)、Agent服务器(8001)、MCP服务器(8003)、TTS服务器(5048)
  • 模块化设计:各服务独立运行,支持热插拔
  • 配置驱动:实时配置热更新,无需重启
  • 跨平台支持:Windows、macOS、Linux

🔧 技术栈

技术栈架构

graph TB
    %% 前端技术栈
    subgraph "前端技术栈 (Frontend Stack)"
        PyQt5[PyQt5<br/>GUI框架]
        Live2D[Live2D<br/>虚拟形象]
        QSS[QSS<br/>样式表]
    end
    
    %% 后端技术栈
    subgraph "后端技术栈 (Backend Stack)"
        FastAPI[FastAPI<br/>Web框架]
        Uvicorn[Uvicorn<br/>ASGI服务器]
        AsyncIO[AsyncIO<br/>异步编程]
    end
    
    %% 数据库技术栈
    subgraph "数据库技术栈 (Database Stack)"
        Neo4j[Neo4j<br/>图数据库]
        GRAG[GRAG<br/>知识图谱]
        Memory[内存缓存<br/>会话管理]
    end
    
    %% AI技术栈
    subgraph "AI技术栈 (AI Stack)"
        OpenAI[OpenAI API<br/>GPT模型]
        Qwen[通义千问<br/>多模态模型]
        MCP[MCP协议<br/>工具调用]
    end
    
    %% 语音技术栈
    subgraph "语音技术栈 (Voice Stack)"
        ASR[语音识别<br/>ASR]
        TTS[语音合成<br/>TTS]
        Realtime[实时语音<br/>WebRTC]
    end
    
    %% 网络技术栈
    subgraph "网络技术栈 (Network Stack)"
        HTTP[HTTP/HTTPS<br/>RESTful API]
        WebSocket[WebSocket<br/>实时通信]
        MQTT[MQTT<br/>物联网协议]
    end
    
    %% 样式
    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
Loading

核心技术

  • Python 3.11 + PyQt5 + FastAPI
  • Neo4j图数据库 + GRAG知识图谱
  • MCP (Model Context Protocol) 工具调用
  • OpenAI兼容API + 多种LLM服务商支持

部署运行教程

环境要求

  • Python 3.11
  • 可选:uv工具(加速依赖安装,且无需特定python版本)

快速开始

如果您的部署有困难,可以参考视频教程或下载一键运行整合包。

1. 安装依赖

使用setup脚本
# 可选:先安装uv
pip install uv

# 使用 setup.py 自动初始化
python setup.py

# 或使用 setup.sh (Linux/macOS)
./setup.sh

# 或使用 setup.bat (Windows)
setup.bat

初始化脚本会自动:

  • 检测Python版本
  • 创建虚拟环境
  • 安装依赖包
  • 复制配置文件模板
  • 打开配置文件供编辑
手动部署
# 无uv
python -m venv .venv

# linux/Mac OS
source .venv/bin/activate
# Windows
.\.venv\Scripts\activate

pip install -r requirements.txt

# 使用uv
uv sync

2. 配置LLM API

编辑 config.json 文件,配置您的LLM API信息:

{
  "api": {
    "api_key": "你的api_key",
    "base_url": "模型服务商OPENAI API端点",
    "model": "模型名称"
  }
}
可选配置

启用知识图谱记忆

使用 docker 安装 neo4j 或安装 neo4j desktop 并在 config.json 中配置 Neo4j 连接参数:

{
  "grag": {
    "enabled": true,
    "neo4j_uri": "neo4j://127.0.0.1:7687",
    "neo4j_user": "neo4j",
    "neo4j_password": "你安装neo4j时设置的密码"
  }
}

启用语音输出功能

{
  "system": {
    "voice_enabled": true
  },
  "tts": {
    "port": 5048
  }
}

Live2D 相关配置

  "live2d": {
    "enabled": false, # 是否启用Live2D
    "model_path": "ui/live2d_local/live2d_models/重音テト/重音テト.model3.json", # Live2D模型路径
    "fallback_image": "ui/img/standby.png", # 备用图片
    "auto_switch": true, # 是否自动切换
    "animation_enabled": true, # 是否启用动画
    "touch_interaction": true # 是否启用触摸交互
  },

其他配置项可参考注释

3. 启动应用

# 使用启动脚本
./start.sh          # Linux/macOS
start.bat           # Windows


# 或直接运行py文件
# linux/Mac OS
source .venv/bin/activate
# Windows
.\.venv\Scripts\activate
python main.py

# uv
uv run main.py
故障排除
  1. Python 版本不兼容:确保使用Python 3.11
  2. 端口被占用:检查8000、8001、8003、5048端口是否可用
  3. Neo4j 连接失败:确保Neo4j服务正在运行
  4. 检测 Neo4j 连接时出现 json 解析错误:退出并重新启动程序
  5. 未知错误:请创建issue以反馈
环境检测
# 运行系统环境检测
python main.py --check-env --force-check

# 快速检测
python main.py --quick-check

许可证

NagaAgent License

贡献

欢迎创建Issue和Pull Request!

构建一键运行整合包
python build.py

构建完成的文件位于dist/目录下

Star History

Star History Chart

感谢所有开发者对本项目做出的贡献

⭐ 如果这个项目对您有帮助,请考虑给我们一个 Star

About

A simple yet powerful agent framework for personal assistants, designed to enable intelligent interaction, multi-agent collaboration, and seamless tool integration.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages