ProcureFlow Agent

DeepAgents / LangGraph 기반의 멀티 에이전트 지능형 조달 시스템으로, 조달 분석, 주문 실행, ERP 데이터 서비스, MCP 도구, 장기 메모리와 샌드박스 실행을 하나의 감사 가능한 비즈니스 체인으로 통합합니다.

프로젝트 주요 특징

• 멀티 에이전트 협업: 메인 에이전트는 의도 인식과 작업 라우팅을 담당하고, procurement-analyst는 조달 분석을, procurement-order는 주문 조회와 쓰기 작업을 담당합니다. Prompt, 도구, Skills 및 미들웨어는 모두 YAML/모듈식 구성으로 분리됩니다.

• 표준화된 비즈니스 도구: MCP를 통해 공급업체, 부품, 재고 및 구매 주문 기능을 캡슐화하여 총 8개의 도구를 제공하며, 가격 비교, 재고 경고, 주문 상세 조회, 구매 제안 및 시각화 보고서 생성을 지원합니다.

• Human-in-the-Loop: 주문을 생성하거나 수정하기 전에 에이전트가 자동으로 자재, 공급업체 및 시스템 단가를 파싱하고, 누락된 필드를 구조적으로 보완하며, 최종 쓰기 전에 인적 승인을 요구합니다.

• 긴 체인 컨텍스트 관리: MongoDB Checkpoint가 세션 상태를 저장하고, 장기 메모리는 사용자별로 격리됩니다. 컨텍스트 요약, 도구 결과 Offloading 및 Skills 점진적 로딩을 통해 컨텍스트 오버헤드를 제어합니다.

• 격리 실행 및 복구: OpenSandbox가 파일 및 코드 실행을 담당하며, 상태 확인, 수명 주기 갱신, 장애 시 재구축 및 Skills 복구를 지원합니다.

• ERP Python화 마이그레이션: FastAPI + SQLAlchemy를 사용하여 기존 Spring Boot ERP 계층을 재구축했으며, 54개 REST 인터페이스 경로, 8개 MCP 도구 및 기존 응답 프로토콜 호환성을 유지합니다.

Related MCP server: ECOUNT MCP Server

시스템 아키텍처

flowchart LR
    UI[Vue 3 对话前端] --> CHAT[FastAPI Chat API]
    CHAT --> MAIN[主 Agent\n意图识别 / 路由]
    MAIN --> ANALYST[采购分析 Agent]
    MAIN --> ORDER[采购订单 Agent]
    ANALYST --> MCP[MCP 工具层\n8 tools]
    ORDER --> HITL[字段补充 / 人工审批]
    HITL --> MCP
    MCP --> ERP[FastAPI ERP\n54 REST APIs]
    ERP --> MYSQL[(MySQL)]
    MAIN --> MONGO[(MongoDB\nCheckpoint / Store)]
    ANALYST --> SANDBOX[OpenSandbox\nSkills / 文件 / 代码]
    ORDER --> SANDBOX

인터페이스 소개

멀티 에이전트 지능형 조달 워크벤치

세션 기록, 스트리밍 응답, 도구 호출 및 에이전트 비즈니스 기능을 통합 표시합니다.

재고 분석 및 시각화 보고서

조달 분석 에이전트가 재고 MCP 도구를 호출하여 재고 경고 테이블, 막대 차트 및 구매 제안을 출력합니다.

주문 검증 및 인적 승인

주문 에이전트가 자재, 수량, 시스템 단가 및 납기 검증을 완료한 후 인적 승인 경계에서 정지합니다. 승인되지 않으면 쓰기를 실행하지 않습니다.

핵심 프로세스

조달 분석

用户需求 → 主 Agent 路由 → 采购分析 Agent
        → MCP 查询 ERP 数据 → 按需加载分析 Skill
        → 沙箱生成报告/图表 → 主 Agent 汇总结论与建议

조달 주문

用户下单/改单 → 主 Agent 路由 → 采购订单 Agent
        → 查询物料、供应商和系统单价
        → 校验 Schema → 结构化补充缺失字段
        → Human-in-the-Loop 最终审批 → MCP 写入 ERP

프로젝트 구조

procureflow-agent/
├─ src/
│  ├─ agent/          # 主 Agent、子 Agent、中间件、记忆、HITL 与沙箱后端
│  ├─ skills/         # 主 Agent、采购分析与订单扩展 Skills
│  ├─ mcp_server/     # 8 个 ERP MCP 工具
│  ├─ erp_api/        # FastAPI + SQLAlchemy ERP 服务
│  └─ api_view/       # 对话、历史记录与流式事件 API
├─ frontend/          # Vue 3 对话前端
├─ tests/             # ERP 流程、54 接口与 8 MCP 工具契约测试
├─ migrations/        # Alembic 基线迁移
├─ database/          # 已匿名化的本地演示数据
├─ demo_data/         # 采购网页抓取的最小可复现报价页面
├─ docs/              # 架构迁移与等价性说明
└─ start_web.py       # ERP、MCP、Agent API、前端统一启动器

빠른 시작

1. 환경 생성

Conda를 사용하여 Python 3.11과 Node.js 22를 관리하는 것이 좋습니다.

2. 데이터베이스 초기화

빈 테이블 생성:

git clone https://github.com/Running-hue/procureflow-agent.git
cd procureflow-agent
conda env create -f environment.yml
conda activate procureflow-agent
Copy-Item .env.example .env

3. 선택 사항 데모 페이지 시작

alembic upgrade head

4. 전체 서비스 시작

python scripts\import_original_sql.py --yes-recreate

샘플 데이터를 가져오면 관련 테이블이 재구축되므로 프로덕션 데이터베이스에 실행하지 마십시오.

5. 선택 사항 데모 페이지 시작

python -m http.server 5173 --directory demo_data\quote_pages

6. 전체 서비스 시작

python start_web.py

검증

python -m pytest -q
ruff check src\erp_api src\mcp_server tests start_web.py scripts
cd frontend
npm ci
npm run build

현재 자동화 검증 범위:

• 54개 ERP REST 인터페이스 경로 계약;

• 8개 MCP 도구 등록 계약;

• 공급업체, 부품, 재고, 주문 트랜잭션 및 상세 프로세스;

• OpenSandbox 장애 복구 로직;

• Vue 3 프로덕션 빌드.

모델, MongoDB, MySQL 및 OpenSandbox의 실제 엔드투엔드 대화는 로컬 서비스와 개인 키가 필요하며, 이 저장소는 외부 통합 결과를 위조하지 않습니다.

보안 설계

• .env, 로컬 키 디렉터리, 로그, 캐시, 생성 파일 및 프론트엔드 빌드 산출물은 모두 Git에서 무시됩니다.

• 구매 주문 쓰기 작업은 주문 하위 에이전트만 실행하며, 실제 MCP 쓰기 도구를 호출하기 전에 인적 승인을 요구합니다.

• 검증되지 않은 Skills는 OpenSandbox에서 실행됩니다. 사용자 메모리는 user_id별로 격리되어 영구 저장됩니다.

• 도구의 대용량 결과는 자동으로 Offloading되고, 컨텍스트가 임계값에 가까워지면 자동으로 요약되어 긴 체인 실패 위험을 낮춥니다.

마이그레이션 범위와 인터페이스 동등성은 마이그레이션 보고서를, 보안 경계는 SECURITY.md를 참조하십시오.