🧾 ProcurePilot · 采购智能体

面向企业采购的多智能体助手:Python 业务层做权威、MCP 暴露受控工具、DeepAgents 编排比价分析与下单流程,订单写操作必须人工审批。

PythonDeepAgentsLangGraphMCPFastAPISSEMySQLOpenSandboxVue 3

项目简介

ProcurePilot 是一个面向企业采购场景的智能助手,用来完成采购查询、供应商比价、分析报告和采购订单操作。

它的核心设计是:不让大模型直接碰数据库。

  • Python 业务层负责确定性的规则和数据,是唯一权威来源
  • MCP 把业务能力包装成受控工具,每次调用都绑定调用者身份和权限
  • Agent 只负责理解需求、规划步骤和编排工具
  • 订单写操作必须经过人工审批(HITL),审批授权一次性、限时,并且绑定具体参数

项目仍在开发中:M0–M10 的源码和非 live 自动化测试已完成,OpenSandbox 真实容器验收和生产认证还没有做。

核心特性

  • 🧭 主 / 子 Agent 分工:主 Agent 只做路由、委派和汇总;分析类请求交给 procurement-analyst,下单、改单、撤单交给 procurement-order
  • 🔍 证据优先的比价分析:每个推荐候选都必须能追溯到真实的 supplier_id 和 quotation_id,并与报价查询结果逐字段核对,查不到证据就返回明确的失败,而不是编造结论
  • ✋ 人在回路的下单流程:缺字段时中断,请用户补充;关键写操作中断,等人审批;审批通过后才真正执行
  • 🔐 最小权限工具:分析 Agent 只拿到 6 个只读查询工具,订单 Agent 拿到 8 个订单工具;身份、角色、trace_id 从可信上下文注入,不由模型传参
  • 📦 沙箱隔离执行:每个请求都有独立的 OpenSandbox,Agent 的文件、命令和 Skill 脚本都在沙箱里跑,不回退到宿主机
  • 💾 状态分库持久化:业务库和 Agent 状态库分开;Checkpoint、Store、恢复元数据和脱敏展示历史各用各的表
  • 🌊 流式交互:FastAPI + SSE 只输出 7 类事件(token、tool_start、tool_args、tool_result、tool_end、interrupt、done),中断后可以通过 HTTP 恢复
  • 🛑 运行护栏:单次运行默认最多 50 次模型调用、200 次工具调用,超限就停止

请求处理流程

graph TD
    U([用户 / Vue 工作台]) -->|POST /api/chat/stream| API[FastAPI<br/>可信身份 + SSE]
    API --> CTX[ProcurementContext<br/>用户 / 租户 / 角色]
    CTX --> MAIN[主 Agent<br/>路由 · 委派 · 汇总]

    MAIN -->|分析 / 比价 / 报告| ANA[procurement-analyst<br/>6 个只读工具]
    MAIN -->|下单 / 改单 / 撤单| ORD[procurement-order<br/>8 个订单工具]

    ANA --> MCP[MCP Server<br/>受控业务工具]
    ORD --> MCP
    MCP --> BIZ[Python 业务层<br/>规则 + Repository]
    BIZ --> DB[(MySQL 业务库)]

    ANA --> SB[OpenSandbox<br/>图表 · 报告 · Skill]

    ORD -->|缺字段| INT1{{interrupt:补充信息}}
    ORD -->|写操作| INT2{{interrupt:人工审批}}
    INT1 -->|POST /resume| ORD
    INT2 -->|批准后执行| ORD

    MAIN -.-> CK[(Agent 状态库<br/>Checkpoint / Store / 历史)]

    style MAIN fill:#f0e1ff
    style ANA fill:#fff4e1
    style ORD fill:#e1f5ff
    style INT1 fill:#ffe8e8
    style INT2 fill:#ffe8e8

系统架构

从上到下分为五层:

  1. Vue 3 工作台:会话回放、流式聊天、工具调用过程展示,以及补充信息卡片和审批卡片
  2. FastAPI / SSE 接口:流式聊天、中断恢复、会话历史查询和删除
  3. Agent 编排:DeepAgents 主 Agent + 两个子 Agent,挂载上下文注入、调用次数限制等中间件
  4. MCP 工具层:供应商、物料、库存、订单四组工具,统一做身份绑定和错误映射
  5. 业务与基础设施:纯 Python 领域模型和服务、SQLAlchemy + MySQL 持久化、OpenSandbox 执行环境

技术栈

类别技术
Agent 编排DeepAgents 0.4.12、LangGraph(主 / 子 Agent、中间件、interrupt)
工具协议MCP(Streamable HTTP)
业务层Python 3.11、Pydantic、领域模型 + Repository / UnitOfWork
持久化MySQL、SQLAlchemy(async)、Alembic、langgraph-checkpoint-mysql
执行隔离OpenSandbox(镜像锁定 sha256 摘要,非 root)
后端 APIFastAPI + SSE
前端Vue 3 + TypeScript + Pinia + Vite
质量pytest(200+ 用例)、ruff、mypy、Vitest

运行方式

项目需要 Python 3.11、MySQL(业务库和 Agent 状态库分开),真实沙箱还需要 Docker 和 OpenSandbox Server。完整的安装和启动步骤见 GitHub 仓库的 README。