ZpAgent

ZpAgent - ReAct 智能体项目

基于 LangChain 1.2 + LangGraph + FastAPI + Vue 3 构建的 ReAct 范式智能体，支持 SSE 流式输出、动态工具多选、多轮会话记忆和 Human-in-the-Loop 工具审批。

功能特性

• ReAct 推理循环：思考 → 行动 → 观察 → 再思考，完整展示 Agent 决策过程
• SSE 流式输出：逐 token 实时推送，打字机效果呈现回答
• 动态工具选择：前端可按需勾选启用/禁用的工具，支持内置工具 + MCP 外部工具
• Human-in-the-Loop：敏感工具需用户审批后执行，支持批准/编辑/拒绝/自行回复
• 多轮会话记忆：双层存储架构（元数据 + 对话状态），支持 InMemory / MySQL 后端切换
• MCP 工具扩展：通过 mcp_servers.json 配置加载外部 MCP 工具服务
• 页面配置大模型：前端设置面板直接修改 API 地址、密钥和模型名称，保存后热重载立即生效，无需重启服务

界面预览

• 对话界面

• 支持内置工具与MCP

• 工具详情展示

• 支持Human-in-the-Loop人工介入

页面支持模型配置

项目架构

ZpAgent-Python/
├── zpagent.sh                       # 一键启动/停止/重启脚本
├── back/                            # 后端（Python + FastAPI + LangChain + LangGraph）
│   ├── main.py                      # FastAPI 应用入口
│   ├── config.py                    # 配置管理（pydantic-settings）
│   ├── .env                         # 环境变量（API Key 等，不提交 Git）
│   ├── mcp_servers.json             # MCP 外部工具服务配置
│   ├── agent/
│   │   ├── __init__.py              # ReAct Agent 编排层（流式事件 + HITL + 会话管理）
│   │   └── graph.py                 # LangGraph Agent 图工厂（create_agent）
│   ├── llm/
│   │   └── __init__.py              # LLM 客户端（ChatOpenAI）
│   ├── tools/
│   │   ├── __init__.py              # 工具导出
│   │   ├── builtin_tools.py         # 内置工具（位置/时间/天气）
│   │   ├── mcp_loader.py            # MCP 工具加载器
│   │   └── registry.py             # 工具注册表（HITL 策略管理）
│   ├── conversation/                # 会话元数据存储（策略模式）
│   │   ├── __init__.py              # 工厂函数 + 导出
│   │   ├── base.py                  # 抽象基类
│   │   ├── memory_store.py          # InMemory 实现
│   │   └── mysql_store.py           # MySQL 实现
│   ├── checkpoint/                  # 对话状态存储（策略模式）
│   │   ├── __init__.py              # 工厂函数 + 导出
│   │   ├── base.py                  # 抽象基类
│   │   ├── memory_store.py          # InMemory 实现
│   │   └── mysql_store.py           # MySQL 实现
│   ├── entity/
│   │   ├── __init__.py              # Pydantic 数据模型（统一导出）
│   │   ├── chat/                    # 聊天相关（Message、ChatRequest、Decision、DecideRequest）
│   │   ├── conversation/            # 会话管理（ConversationInfo、ConversationDetail、RenameRequest）
│   │   ├── tool/                    # 工具相关（ToolInfo）
│   │   └── common/                  # 公共模型（ApiResponse、LlmConfigRequest、LlmConfigResponse）
│   ├── services/
│   │   ├── __init__.py              # 服务层导出
│   │   └── config_service.py        # 配置服务（.env 读写 + 热重载）
│   ├── routers/
│   │   └── api.py                   # 统一 API 路由（聊天 + HITL + 会话 + 工具 + 配置管理）
│   └── requirements.txt             # Python 依赖
│
└── front/                           # 前端（Vue 3 + Vite）
    ├── package.json
    ├── vite.config.js               # Vite 配置（含 SSE 代理）
    ├── index.html
    └── src/
        ├── main.js
        ├── App.vue                  # 根组件（全局状态管理）
        ├── style.css                # 全局样式
        ├── api/
        │   └── index.js             # API 封装（REST + SSE 流式）
        ├── views/
        │   └── ChatView.vue         # 聊天主视图
        ├── utils/
        │   └── index.js             # 工具函数 + 工具中文名映射
        └── components/
            ├── ChatMessage.vue      # 消息组件（含 ReAct 思考过程）
            ├── ConversationList.vue # 侧边栏会话列表（含设置入口）
            ├── ToolSelector.vue     # 工具多选栏
            ├── ApprovalPanel.vue    # HITL 工具审批面板
            ├── SettingsDialog.vue   # 系统设置弹窗（大模型配置）
            └── ConfirmDialog.vue    # 通用确认弹窗

技术栈

| 层面 | 技术 | 版本 | 说明 | |------|------|------|------| | 后端框架 | FastAPI | 0.115+ | 高性能异步 Web 框架 | | AI 框架 | LangChain | 1.2+ | LLM 调用 + 工具绑定 + astream_events 流式 | | Agent 引擎 | LangGraph | 1.2+ | ReAct 状态图 + checkpointer + HITL | | LLM API | OpenAI 兼容 | — | DeepSeek / 智谱 / Moonshot / OpenAI 等 | | 流式传输 | SSE | — | Server-Sent Events 逐 token 实时输出 | | 前端框架 | Vue 3 + Vite | 3.5+ / 5.4+ | Composition API + 快速热更新 | | 会话记忆 | 双层存储 | — | 元数据（conversation）+ 对话状态（checkpoint），支持 InMemory / MySQL |

快速启动（推荐）

项目提供 zpagent.sh 一键管理脚本，自动处理虚拟环境检测、依赖安装和服务管理。

前置条件

1. 编辑 back/.env，配置你的 LLM API 密钥：

``bash cd back cp .env.example .env # 如果没有 .env，从模板复制 # 编辑 .env，将 API_KEY=your-api-key-here 改为你的实际 Key ``

1. 首次使用前需手动创建 Python 虚拟环境（仅一次）：

``bash cd back python3 -m venv venv source venv/bin/activate pip install -r requirements.txt ``

一键启动

# 赋予脚本执行权限（首次）
chmod +x zpagent.sh

# 启动所有服务（后端 + 前端）
./zpagent.sh start

启动成功后输出：

==============================
  ZpAgent 启动
==============================
[INFO] 启动后端服务...
[OK] 后端服务已启动 (PID: 12345)
[INFO] API 文档: http://localhost:8000/docs
[INFO] 启动前端服务...
[OK] 前端服务已启动 (PID: 12346)
[INFO] 前端地址: http://localhost:5173

==============================
  ZpAgent 服务已全部启动
  后端:  http://localhost:8000
  前端:  http://localhost:5173
  API:   http://localhost:8000/docs
==============================

脚本命令一览

./zpagent.sh {start|stop|restart|status} [backend|frontend|all]

| 命令 | 说明 | 示例 | |------|------|------| | start | 启动服务 | ./zpagent.sh start — 启动前后端 | | stop | 停止服务 | ./zpagent.sh stop — 停止所有服务 | | restart | 重启服务 | ./zpagent.sh restart — 重启所有服务 | | status | 查看状态 | ./zpagent.sh status — 查看运行状态和健康检查 |

第二个参数可选，默认 all：

./zpagent.sh start backend     # 仅启动后端
./zpagent.sh start frontend    # 仅启动前端
./zpagent.sh stop frontend     # 仅停止前端
./zpagent.sh restart backend   # 仅重启后端
./zpagent.sh status            # 查看所有服务状态 + API 健康检查

服务地址

| 服务 | 地址 | 说明 | |------|------|------| | 前端 | http://localhost:5173 | 用户界面 | | 后端 | http://localhost:8000 | API 服务 | | API 文档 | http://localhost:8000/docs | Swagger UI | | 健康检查 | http://localhost:8000/api/health | 后端健康状态 |

日志文件

| 服务 | 日志路径 | |------|----------| | 后端 | log/backend.log | | 前端 | log/frontend.log |

手动启动

如果不想使用脚本，也可以手动启动：

第一步：启动后端

cd back

# 1. 创建 Python 虚拟环境（仅首次）
python3 -m venv venv

# 2. 激活虚拟环境
source venv/bin/activate        # macOS / Linux
# venv\Scripts\activate         # Windows

# 3. 安装 Python 依赖（仅首次）
pip install -r requirements.txt

# 4. 配置环境变量（仅首次）
#    编辑 back/.env，将 API_KEY=your-api-key-here 改为你的实际 Key

# 5. 启动后端服务
python main.py

> 后端运行在 http://localhost:8000 > API 文档（Swagger UI）：http://localhost:8000/docs

第二步：启动前端

cd front

# 1. 安装前端依赖（仅首次）
npm install

# 2. 启动开发服务器
npm run dev

> 前端运行在 http://localhost:5173 > Vite 已配置 /api 代理到后端 8000 端口，无需额外配置

使用说明

1. 浏览器打开 http://localhost:5173
2. 点击左下角齿轮图标打开设置面板，配置 API 地址、密钥和模型名称（也可通过 .env 文件配置）
3. 在底部输入框输入消息，按 Enter 发送
4. 通过工具栏选择需要启用的工具
5. 观察 Agent 的 ReAct 推理过程（工具调用 → 观察结果 → 最终回答）
6. 当 Agent 调用需要审批的工具时，审批面板会弹出，你可以选择批准/编辑/拒绝/自行回复

环境变量说明

在 back/.env 中配置：

> 提示：API_KEY、BASE_URL、MODEL_NAME 三项也可通过前端左下角设置面板修改，保存后热重载立即生效，无需重启服务。

| 变量 | 说明 | 默认值 | |------|------|--------| | API_KEY | LLM API 密钥（必填） | — | | BASE_URL | API 基础地址 | https://api.deepseek.com | | MODEL_NAME | 模型名称 | deepseek-v4-flash | | TEMPERATURE | 生成温度（0~2） | 0.7 | | MAX_COMPLETION_TOKENS | 最大生成 token 数 | 2048 | | REQUEST_TIMEOUT | LLM 请求超时（秒） | 60 | | MAX_RETRIES | LLM 请求重试次数 | 2 | | MAX_ITERATIONS | ReAct 最大迭代次数 | 10 | | HOST | 服务监听地址 | 0.0.0.0 | | PORT | 服务端口 | 8000 | | CONVERSATION_BACKEND | 会话元数据存储后端 | memory | | CHECKPOINT_BACKEND | 对话状态存储后端 | memory | | MYSQL_HOST | MySQL 主机地址 | localhost | | MYSQL_PORT | MySQL 端口 | 3306 | | MYSQL_USER | MySQL 用户名 | root | | MYSQL_PASSWORD | MySQL 密码 | — | | MYSQL_DATABASE | MySQL 数据库名 | zpagent |

会话记忆机制

项目采用 双层存储架构（策略模式），每层独立可切换：

┌──────────────────────────────────────────────────────────────┐
│                     会话记忆 = 两层协作                       │
├─────────────────────────┬────────────────────────────────────┤
│  conversation/          │  checkpoint/                        │
│  ─────────────────────  │  ────────────────────────           │
│  应用层：会话元数据      │  框架层：对话状态管理               │
│  - 会话列表/创建/删除   │  - 通过 thread_id 关联对话          │
│  - 标题管理             │  - 自动拼接历史上下文给 LLM         │
│  - 支持 Memory / MySQL  │  - 支持 Memory / MySQL              │
│                         │  - 支持 human-in-the-loop           │
└─────────────────────────┴────────────────────────────────────┘

通过 .env 中的 CONVERSATION_BACKEND 和 CHECKPOINT_BACKEND 切换存储后端，无需改代码。

ReAct 循环原理

用户输入
  │
  ▼
┌──────────────────────────────────────────────────────┐
│  LangGraph Agent（create_agent + checkpointer）       │
│  checkpointer 自动通过 thread_id 加载对话历史          │
│  LLM 推理（astream_events v2 流式）                    │
│  逐 token 输出 + 检测 tool_calls                      │
└──────────────┬───────────────────────────────────────┘
               │
     ┌─────────┴──────────────────────┐
     │                                │
  有 tool_calls                   无 tool_calls
     │                                │
     ▼                                ▼
 需要审批？── 是 ──→ interrupt()     输出最终答案
     │               暂停等待          │
     │ 否             │                ▼
     ▼                ▼             checkpointer 保存状态
 ToolNode 执行   用户审批决策
     │           (批准/拒绝/编辑)
     ▼                │
 观察结果 ────────────┘
     │
     ▼
 回到 LLM 继续推理

内置工具

| 工具标识 | 功能说明 | 是否需要审批 | |----------|----------|--------------| | get_datetime | 查询当前日期、时间、星期 | 是（演示用） | | base64_tool | Base64 编码/解码，支持 encode 和 decode 两种操作 | 否 |

可通过 back/mcp_servers.json 配置加载额外的 MCP 外部工具，MCP 工具默认需要人工审批。

扩展指南

添加新工具

在 back/tools/builtin_tools.py 中用 @tool 装饰器定义：

from langchain.tools import tool

@tool
def my_new_tool(param: str) -> str:
    """工具描述（LangChain 自动提取为 description）。

    Args:
        param: 参数描述（自动生成为 JSON Schema）
    """
    return "执行结果"

然后将 my_new_tool 加入文件底部的 BUILTIN_TOOLS 列表，前端会自动识别。

如需在 front/src/utils/index.js 的 TOOL_NAME_MAP 中添加中文显示名。

添加新的存储后端

1. 在 conversation/ 或 checkpoint/ 下新建文件，继承抽象基类
2. 实现所有抽象方法
3. 在对应 __init__.py 的工厂函数中添加分支
4. 在 config.py 中添加相关配置项

API 接口一览

所有路由仅使用 GET 和 POST 请求方法。JSON 接口（SSE 流式除外）统一使用 ApiResponse 格式返回：

{"code": 0, "msg": "ok", "data": {...}, "extra": null}

| 方法 | 路径 | 说明 | |------|------|------| | POST | /api/chat | 聊天（SSE 流式输出） | | POST | /api/chat/decide | HITL 审批决策（批准/拒绝/编辑/自行回复） | | GET | /api/messages/{id} | 获取会话消息历史 | | GET | /api/conversations | 获取所有会话列表 | | GET | /api/conversations/{id} | 获取会话详情 | | POST | /api/conversations/{id}/rename | 重命名会话 | | POST | /api/conversations/{id}/delete | 删除会话 | | POST | /api/conversations/{id}/messages/clear | 清空会话消息 | | GET | /api/tools | 获取可用工具列表（含 tooltype、servername） | | POST | /api/tools/reload | 热重载 MCP 工具 | | GET | /api/config/llm | 获取当前 LLM 配置（密钥脱敏） | | POST | /api/config/llm | 保存 LLM 配置到 .env（热重载立即生效） |

协议

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wangzpap
• Source: wangzpap/ZpAgent
• License: MIT

Install and usage instructions live in the source repository linked above.