# web-agent

**Repository Path**: ksfksf/web-agent

## Basic Information

- **Project Name**: web-agent
- **Description**: Web版本Agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-22
- **Last Updated**: 2026-05-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Web Agent

基于 OpenAgent 架构的 Web 智能体系统，支持 MCP 协议通信、可插拔 Skill 技能系统、Web 前端对话界面等核心功能。

## 功能特性

- ✅ **Web 前端对话界面** - Vue3 + Element Plus 打造的现代化聊天界面
- ✅ **MCP 协议支持** - 完整的 Model Context Protocol 实现
- ✅ **可插拔 Skill 技能系统** - 动态加载 Python 技能插件，支持单个文件和子目录两种组织方式
- ✅ **Agent 调度核心** - 基于 LangGraph 思想的任务编排
- ✅ **上下文记忆** - 基于 Redis + SQLite 的混合存储方案
- ✅ **模型底座** - 兼容 OpenAI 协议的 LLM 接入
- ✅ **流式输出** - WebSocket 实时通信，支持思考过程显示
- ✅ **智能搜索技能** - 内置知识库搜索，支持 Python、人工智能、编程等常见领域

## 技术架构

```
┌─────────────────────────────────────────────────────────┐
│                      前端层 (Vue3)                       │
│            聊天界面 / 会话列表 / 技能管理                 │
└────────────────────────────┬────────────────────────────┘
                             │ WebSocket / HTTP
┌────────────────────────────▼────────────────────────────┐
│                    接入层 (FastAPI)                      │
│               API 路由 / WebSocket / CORS                │
└────────────────────────────┬────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────┐
│                  Agent 核心层                            │
│         会话管理 / 任务编排 / 工具调用                   │
└────────────────────────────┬────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────┐
│                  协议层 (MCP)                           │
│         JSON-RPC 编解码 / 工具发现 / 资源管理            │
└────────────────────────────┬────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────┐
│                Skill 技能层                              │
│         技能注册 / 动态加载 / 执行调度                   │
└────────────────────────────┬────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────┐
│                 存储层 (Redis + SQLite)                  │
│         会话缓存 / 消息持久化 / 向量存储                 │
└─────────────────────────────────────────────────────────┘
```

## 快速开始

### 前置要求

- Python 3.9+
- Node.js 18+
- Redis 6+ (可选，用于会话缓存)

### 后端部署

1. 进入后端目录：
```bash
cd backend
```

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

3. 安装依赖：
```bash
pip install -r requirements.txt
```

4. 配置环境变量：
```bash
cp .env.example .env
# 编辑 .env 文件，配置 LLM API Key 等参数
```

5. 启动 Redis（可选，如果使用默认内存存储可跳过）：
```bash
# 使用 Docker
docker run -d -p 6379:6379 redis
```

6. 启动后端服务：
```bash
python main.py
```

后端服务将在 http://localhost:8000 启动。

### 前端部署

1. 进入前端目录：
```bash
cd frontend
```

2. 安装依赖：
```bash
npm install
```

3. 启动开发服务器：
```bash
npm run dev
```

前端服务将在 http://localhost:3000 启动。

## 配置说明

### 后端配置 (.env)

| 参数 | 说明 | 默认值 |
|------|------|--------|
| LLM_API_KEY | LLM API Key | 必填 |
| LLM_BASE_URL | LLM API 地址 | https://api.openai.com/v1 |
| LLM_MODEL | 模型名称 | gpt-4 |
| REDIS_URL | Redis 连接地址 | redis://localhost:6379/0 |
| DATABASE_URL | 数据库连接 | sqlite+aiosqlite:///./webagent.db |
| SKILLS_DIR | 技能目录 | ./skills |

### 使用国内模型

修改 `.env` 文件中的 `LLM_BASE_URL` 和 `LLM_MODEL`：

```bash
# 通义千问
LLM_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
LLM_MODEL="qwen-plus"

# 或者 DeepSeek
LLM_BASE_URL="https://api.deepseek.com/v1"
LLM_MODEL="deepseek-chat"
```

## 技能开发

### 快速开始

开发新技能只需 3 个步骤：

1. **复制模板** - 复制 `backend/skills/plugins/skill_template.py` 为新文件
2. **修改代码** - 编辑技能名称、描述和执行逻辑
3. **自动加载** - 重启后端服务，新技能会自动被发现和加载

### 技能目录结构

```
backend/skills/
├── __init__.py
├── base.py              # 技能基类
├── manager.py           # 技能管理器
├── examples.py          # 内置示例技能
├── SKILLS_GUIDE.md      # 详细开发指南
└── plugins/             # 插件技能目录（推荐用于自定义技能）
    ├── __init__.py
    ├── skill_template.py  # 开发模板
    └── my_skill.py       # 你的自定义技能（单个文件）
    └── my_package/      # 或者使用子目录组织
        ├── __init__.py
        └── skill.py
```

### 创建新技能（单个文件）

1. 在 `backend/skills/plugins/` 目录下创建新的 Python 文件：
```python
# my_skill.py
from typing import Dict, Any
from skills.base import BaseSkill

class MySkill(BaseSkill):
    name = "my_skill"
    description = "我的技能描述"
    version = "1.0.0"
    
    def get_input_schema(self) -> Dict[str, Any]:
        return {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "参数1描述"
                }
            },
            "required": ["param1"]
        }
    
    async def execute(self, **kwargs) -> Dict[str, Any]:
        param1 = kwargs.get("param1")
        # 实现技能逻辑
        return {
            "result": f"执行结果: {param1}"
        }
```

2. 重启后端服务，技能自动加载！

### 内置示例技能

- **calculator** - 计算器，执行基本数学运算（加、减、乘、除）
- **weather** - 天气查询，获取指定城市的天气信息
- **search** - 智能搜索，支持 Python、人工智能、编程等常见领域的搜索

### 技能 API

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/skills` | GET | 列出所有可用技能 |
| `/api/v1/skills/{skill_name}` | GET | 获取技能详情和输入参数 |
| `/api/v1/skills/{skill_name}/execute` | POST | 执行指定技能 |

### 技能开发最佳实践

更多详细内容请参考 [SKILLS_GUIDE.md](./backend/skills/SKILLS_GUIDE.md)。

## MCP 协议

### 服务端

内置 MCP 服务器，支持：
- tools/list - 列出可用工具
- tools/call - 调用工具
- resources/list - 列出资源
- resources/read - 读取资源
- prompts/list - 列出提示模板

### 客户端

MCP 客户端可连接远程 MCP 服务器，扩展 Agent 能力。

## API 文档

启动后端后访问 http://localhost:8000/docs 查看完整的 API 文档。

## 项目结构

```
web-agent/
├── backend/              # 后端服务
│   ├── api/             # API 路由
│   │   ├── conversations.py  # 会话管理
│   │   ├── skills.py        # 技能管理 API
│   │   └── websocket.py     # WebSocket 通信
│   ├── core/            # 核心逻辑
│   │   ├── agent/       # Agent 引擎
│   │   └── memory/      # 记忆管理
│   ├── mcp/             # MCP 协议实现
│   ├── skills/          # 技能管理
│   │   ├── base.py      # 技能基类
│   │   ├── manager.py   # 技能管理器
│   │   ├── examples.py  # 内置示例技能
│   │   ├── SKILLS_GUIDE.md  # 开发指南
│   │   └── plugins/     # 插件技能目录
│   │       ├── __init__.py
│   │       └── skill_template.py
│   ├── models/          # 模型集成
│   ├── storage/         # 存储层
│   ├── config.py        # 配置文件
│   ├── main.py          # 入口文件
│   ├── test_api.py      # API 测试
│   ├── test_search_skill.py  # 搜索技能测试
│   └── requirements.txt
├── frontend/            # 前端应用
│   ├── src/
│   │   ├── views/       # 页面
│   │   ├── store/       # 状态管理
│   │   ├── router/      # 路由
│   │   └── main.js
│   ├── index.html
│   ├── package.json
│   └── vite.config.js
└── README.md
```

## 开发计划

- [x] 可插拔技能系统 - 支持单个文件和子目录两种组织方式
- [x] 智能搜索技能 - 内置知识库搜索
- [x] 技能开发模板 - 提供完整的技能开发文档
- [x] LLM Loop 循环调用 - 支持多轮对话和工具调用
- [x] 工具结果整理 - 让 LLM 先整理结果再返回给用户
- [ ] 支持更多 LLM 模型（Claude, Gemini 等）
- [ ] 真实搜索引擎 API 集成（必应、必应等）
- [ ] 技能市场和分享功能
- [ ] 工作流可视化编排
- [ ] 向量数据库集成
- [ ] RAG 检索增强生成
- [ ] 多智能体协作
- [ ] 权限管理和用户系统
- [ ] Docker 一键部署

## 更新日志

### v1.2.0 (2026-05-22)
- ✨ 新增 LLM Loop 循环调用机制，支持多轮对话和工具调用
- 🧠 实现工具调用失败重试功能，错误时让 LLM 重新梳理参数
- 🔄 工具结果先存入上下文，由 LLM 整理后再返回给用户
- 📝 完善 AgentEngine 实现，支持流式和非流式两种模式
- 🔧 优化 MemoryManager，支持存储 tool_calls 和 tool_call_id
- ✅ 添加完整的测试脚本和模拟测试

### v1.1.0 (2026-05-22)
- ✨ 新增可插拔技能系统
- ✨ 新增智能搜索技能（支持 Python、人工智能、编程等领域）
- 📝 完善技能开发文档和模板
- 🔧 优化技能管理器，支持自动加载插件技能
- ✅ 添加完整的测试套件

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！