# NexusAI

**Repository Path**: zzugis_2/nexus-ai

## Basic Information

- **Project Name**: NexusAI
- **Description**: “Nexus”意为“联结”，体现平台作为AI助手与用户之间的核心纽带。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-06
- **Last Updated**: 2026-03-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智慧农业AI助手 - 小禾 🌾

基于 **AgentScope Runtime** 的多智能体农业AI助手系统

## 🎯 项目特性

- ✅ **多轮对话支持** - 基于 AgentScope Runtime 的会话管理
- ✅ **多Agent协作** - Router、QA、RAG、Graph 四个Agent协同工作
- ✅ **MCP工具集成** - 支持农业设备、天气、土壤等MCP服务调用
- ✅ **RAG知识检索** - Qdrant向量数据库检索
- ✅ **知识图谱查询** - Neo4j图数据库查询
- ✅ **统一消息格式** - 标准化的 `{type, data, metadata}` 响应格式
- ✅ **流式响应** - SSE流式输出，实时反馈

## 📁 项目结构

```
agricultural-ai-runtime/
├── main.py                         # AgentScope Runtime 主入口
├── .env                            # 环境配置
├── requirements.txt                # Python 依赖
├── README.md                       # 项目文档
│
├── agents/                         # Agent 层
│   ├── qa_agent.py                # QA Agent（MCP工具调用）
│   ├── rag_agent.py               # RAG Agent（向量检索）
│   ├── graph_agent.py             # Graph Agent（图谱查询）
│   ├── router_agent.py            # Router Agent（路由分发）
│   └── prompts/                   # Agent 提示词（YAML）
│       ├── qa_agent.yaml
│       ├── rag_agent.yaml
│       ├── graph_agent.yaml
│       └── router_agent.yaml
│
├── services/                       # 服务层
│   ├── rag_service.py             # RAG 服务
│   └── graph_service.py           # 图谱服务
│
├── mcp/                           # MCP 配置
│   └── config.yaml                # MCP 客户端配置
│
├── utils/                         # 工具模块
│   ├── logger.py                  # 日志工具
│   ├── prompt_loader.py           # 提示词加载器
│   └── message_formatter.py       # 消息格式化
│
├── api/                           # API 层（可选）
├── middleware/                    # 中间件（可选）
└── skills/                        # 技能系统（可选）
```

## 🚀 快速开始

### 1. 安装依赖

```bash
# 创建虚拟环境
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/Mac

# 安装依赖
pip install -r requirements.txt
```

### 2. 配置环境变量

复制 `.env` 文件并修改配置：

```bash
# AI 模型配置
DASHSCOPE_API_KEY=your_api_key_here
LLM_MODEL=qwen-plus
ROUTER_LLM_MODEL=qwen-max

# 向量数据库
QDRANT_URL=http://localhost:6333
QDRANT_COLLECTION=qa_collection

# 图数据库
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password

# 服务器配置
SERVER_PORT=8090
```

### 3. 启动服务

```bash
python main.py
```

服务将在 `http://localhost:8090` 启动

## 📡 使用示例

### 多轮对话示例

```python
import requests

session_id = "session_001"
user_id = "user_001"

def query(message):
    response = requests.post(
        "http://localhost:8090/query",
        json={
            "msgs": message,
            "session_id": session_id,
            "user_id": user_id
        },
        stream=True
    )
    
    for line in response.iter_lines():
        if line.startswith(b'data: '):
            data = json.loads(line[6:])
            print(data['data'])

# 第一轮
query("你好，介绍一下自己")

# 第二轮（AI会记住之前的对话）
query("你能做什么？")

# 第三轮（上下文理解）
query("帮我查一下设备数据")
```

### 响应格式

所有响应统一为以下格式：

```json
{
  "type": "text|rag|graph|map|weather|device_data|error",
  "data": "消息内容",
  "metadata": {
    "source": "来源",
    "agent": "小禾",
    ...
  }
}
```

## 🔧 核心功能

### 1. Router Agent  - 路由分发

根据用户请求智能路由到合适的Agent：
- `qa_agent` - 普通问答和MCP工具调用
- `rag_agent` - 文档知识检索
- `graph_agent` - 知识图谱查询

### 2. QA Agent - 对话和工具

- 处理普通问答
- 调用MCP工具（设备查询、天气、地图等）
- 支持多轮对话上下文

### 3. RAG Agent - 知识检索

- Qdrant向量数据库检索
- 操作手册、FAQ查询
- 返回最相关的文档内容

### 4. Graph Agent - 图谱查询

- Neo4j知识图谱查询
- 产品信息、病虫害、政策法规等
- 结构化知识查询

## 🎨 MCP 集成

在 `mcp/config.yaml` 中配置MCP服务：

```yaml
mcp_clients:
  - name: 'agriculture_mcp'
    transport: 'streamable_http'
    url: 'http://your-mcp-server/mcp-servers/device'
    passthrough_token: true
    headers:
      Content-Type: 'application/json'
```

## 📚 开发指南

### 添加新的Agent

1. 在 `agents/` 目录创建新的Agent文件
2. 实现 `create_xxx_agent(memory)` 工厂函数
3. 在 `router_agent.py` 中注册新的Agent

### 添加新的技能

1. 在 `skills/` 目录创建技能模块
2. 编写 `SKILL.md` 说明文档
3. 实现技能逻辑
4. 在对应的Agent中集成技能

### 自定义提示词

修改 `agents/prompts/*.yaml` 文件自定义Agent行为

## 🧪 测试

```bash
# 运行测试
pytest tests/

# 测试多轮对话
python tests/test_multi_turn.py
```

## 📊 架构优势

| 特性 | 传统架构 | AgentScope Runtime |
|------|---------|-------------------|
| 多轮对话 | ❌ 需要手动管理 | ✅ 自动支持 |
| 状态持久化 | ❌ 无 | ✅ 内置支持 |
| 消息格式 | 自定义 | ✅ 标准化 |
| 扩展性 | 修改代码 | ✅ 添加Agent/技能 |
| 生产部署 | 单机 | ✅ 可扩展到分布式 |

## 📝 更新日志

### v1.0.0 (2026-02-02)

- ✅ 基于 AgentScope Runtime 重构
- ✅ 实现多轮对话支持
- ✅ 统一消息格式
- ✅ 集成 MCP、RAG、Graph
- ✅ 完善日志和错误处理

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

---

**项目状态**: ✅ 开发中  
**最后更新**: 2026-02-02  
**团队**: 智慧农业AI团队