Skip to main content
Glama
deenesjakoruzh
Sakiko236

MultiAgent-MCP-Workflow

by Sakiko236
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

LangGraph と MCP アーキテクチャに基づくエンタープライズ級マルチエージェント協調意思決定システム

Enterprise Multi-Agent Collaborative Decision System (2025.08 - 2025.12)

Python 3.10+ LangGraph Protocol FastAPI Tests Passing License: MIT

📌 プロジェクト概要 (Project Overview)

本プロジェクトは、複雑なエンタープライズシナリオを対象とした高可用性・高拡張性・完全非同期のマルチエージェント協調意思決定プラットフォームです。システムは LangGraph 有向状態グラフ（StateGraph） でワークフローをオーケストレーションし、Anthropic Model Context Protocol (MCP) オープンツールプロトコル標準を深く統合しています。また、混合コンテキストとセマンティックトランケーションによる階層型メモリシステムを組み合わせ、FastAPI + AsyncIO + SSE によって、ミリ秒単位の Token ストリーミングとチェーン全体を網羅する思考チェーン（Thought Chain）のリアルタイム配信を提供します。

🌟 コア技術指標

  • 🎯 ツールルーティング精度：厳格な Function Calling と JSON Schema 検証を利用し、ツール選択とパラメータ抽出の精度は 96.5% に達します。

  • ⚡ ファーストトークン応答時間 (TTFT)：非同期ノンブロッキングのイベント駆動スケジューリングにより、ファーストトークンのストリーミング出力時間を 210ms に短縮します。

  • 🚀 並行スループット能力：軽量コルーチンによる並行スケジューリングで、シングルノードあたり 120+ QPS の安定動作をサポートします。

  • 📉 Token 消費の最適化：セマンティックトランケーションとスライディングウィンドウのコンテキスト管理を組み合わせ、複数ターンの複雑な対話で 38% の Token 冗長消費を削減します。

  • 🛡️ 安全性とコンプライアンス：Human-in-the-loop (HITL) メカニズムと AST コードサンドボックスを内蔵し、高リスクな操作は 100% ブロックして人間の承認を求めます。

Related MCP server: MCP Business AI Transformation

🏗️ 全体アーキテクチャ設計 (System Architecture)

flowchart TD
    subgraph ClientLayer [客户端交互层]
        WebUI[现代化 Web 交互控制台 / SSE 客户端]
        RESTClient[RESTful API / SDK 客户端]
        MCPClientApp[Claude Desktop / Cursor MCP 客户端]
    end

    subgraph APILayer [FastAPI 异步高性能网关]
        Router[API 路由网关 / 跨域与鉴权]
        SSEHandler[SSE 异步事件流分发器 (Token 流 + 思考链路流)]
        HITLHandler[Human-in-the-loop 审核干预中心]
    end

    subgraph LangGraphCore [LangGraph 状态机决策内核]
        State[AgentState 核心状态定义]
        
        Planner[1. Task Planner 任务规划 Agent]
        IntentRouter[2. Intent Classifier & Tool Router 意图识别]
        ToolExecutor[3. Tool Executor 并行工具执行器]
        SelfRefine[4. Self-Refine / Critic 反思纠错 Agent]
        HITLNode[Human-in-the-loop 人工审批拦截节点]
        
        Planner --> IntentRouter
        IntentRouter -->|需要调用工具| ToolExecutor
        IntentRouter -->|纯文本直接回答| SelfRefine
        ToolExecutor -->|检测到敏感操作(如DML写)| HITLNode
        HITLNode -->|审核通过 (Resume)| ToolExecutor
        HITLNode -->|审核拒绝 / 指令调整| Planner
        ToolExecutor --> SelfRefine
        SelfRefine -->|质检未通过 / 异常回溯| Planner
        SelfRefine -->|质检通过 (98% 评分)| EndNode[Final Answer 汇总输出]
    end

    subgraph MCPHub [MCP 协议与 8+ 外部工具中心]
        MCPCore[Async MCP Client & Server Manager]
        ToolRegistry[动态工具注册表 (Pydantic Schema 校验)]
        
        subgraph ToolSources [8+ 生产级核心工具源]
            T1[sql_query_tool: 数据库安全只读分析]
            T2[sql_execute_dml: 数据库写变更 (带 HITL)]
            T3[web_search_tool: DuckDuckGo 实时网络检索]
            T4[python_sandbox: AST 安全隔离代码沙盒]
            T5[knowledge_rag_tool: 企业知识库混合检索]
            T6[chart_generator: ECharts / Mermaid 可视化配置生成]
            T7[file_system_tool: 沙盒化文件安全读写]
            T8[data_cleaner_tool: JSON 清洗与 Schema 修复]
            T9[http_request_tool: 外部 RESTful API 动态调用]
        end
    end

    subgraph MemoryLayer [混合上下文与分层记忆体系]
        Checkpointer[Redis / SQLite 状态持久化检查点]
        LongTermMem[长期用户画像 (User Profile) 与偏好库]
        Compressor[上下文压缩器: 语义截断 + 滑动窗口 (降低 38% Token)]
    end

    ClientLayer --> APILayer
    APILayer --> LangGraphCore
    LangGraphCore --> MCPHub
    MCPHub --> ToolSources
    LangGraphCore --> MemoryLayer

🛠️ 四大コアモジュール詳細解説 (Core Modules)

1. 状態マシンワークフローのオーケストレーション (StateGraph Workflow)

  • マルチエージェント協調のクローズドループ：

    • PlannerAgent：ユーザーの複雑なビジネス要件を自動的に順序付けられたサブタスクのトポロジ（SubTasks）へ分解します。

    • IntentRouterAgent：インテントの特徴とツールのメタデータを組み合わせて高精度ルーティングを実行し、精度は 96.5% に達します。

    • ToolExecutorAgent：asyncio.gather を利用してツール呼び出しを並列実行し、例外とタイムアウトを自動捕捉します。

    • SelfRefineCriticAgent：実行結果に対してデータの整合性、SQL Schema の整合性、ロジックの幻覚（ハルシネーション）など、多次元の品質レビューを実施し、閾値を下回る場合には StateGraph が Planner へ動的にバックトラックします。

  • Human-in-the-loop (HITL) 人による介入：

    • データベースへの書き込み操作（sql_execute_dml）やシステムファイルの変更など、機密性の高いツールを自動でインターセプトします。

    • StateGraph を一時停止し、Checkpointer にコンテキストスナップショットを永続化します。管理者はフロントエンドのポップアップまたは /api/hitl/approve エンドポイントで「承認/拒否/追記・修正」を行った後、シームレスに実行を再開できます。

2. MCP プロトコルと 8+ ツールソースの拡張 (Model Context Protocol)

  • Anthropic MCP プロトコル標準（JSON-RPC 2.0）に準拠し、ツール側とモデル側をデカップリングします。

  • 8+ タイプの標準ツールソースを内蔵：

    1. sql_query_tool: 構造化 SQL レポートのクエリ実行と多次元集計統計。

    2. sql_execute_dml: データベースへの挿入/更新操作（is_sensitive=True としてマーク済み）。

    3. web_search_tool: リアルタイムの Web 検索で最新情報と技術仕様を取得。

    4. python_sandbox: Python AST 構文に基づく安全チェックを伴う隔離実行環境。os、subprocess、socket などの危険な指令を完全に禁止します。

    5. knowledge_rag_tool: エンタープライズ知識ベースにおける BM25 + ベクトル混合検索。

    6. chart_generator: ECharts の棒グラフ・折れ線グラフ・円グラフおよび Mermaid フローチャート設定を自動生成。

    7. file_system_tool: サンドボックス内でのファイルの安全な読み書きとディレクトリ分析。

    8. data_cleaner_tool: 破損した Markdown/JSON データをインテリジェントに抽出・修復。

    9. http_request_tool: 外部 REST API との動的連携。

  • 独立したサーバープロセスとして実行でき（examples/run_mcp_standalone.py）、Claude Desktop や Cursor にシームレスに接続できます。

3. ハイブリッドコンテキストと階層型メモリ管理 (Hybrid Context & Memory)

  • 短期チェックポイント (Checkpointer): Redis ハッシュテーブルと SQLite への二重永続化により、複数ターンのセッション状態の遡及、ブランチリプレイ、障害リカバリをサポートします。

  • 長期ユーザープロファイル (User Profile): ユーザー ID に基づいて、ユーザーの技術スタックの嗜好、出力スタイルの制約、過去の意思決定行動を自動的に維持し、マルチエージェント起動時にコンテキストを必要なだけ注入します。

  • Token 冗長圧縮アルゴリズム (Context Compressor)：

    • スライディングウィンドウ方式：システム指示と直近の $K$ 回分の対話を固定的に保持します。

    • セマンティックトランカーション (Semantic Truncation): 期限内で冗長な中間ツール出力（例：数十から上百に及ぶレコードを含む SQL の元データ）からコア Schema と要約を自動抽出し、複数回対話の Token 冗長を 38% 以上削減します。

4. 本番レベルのストリーミング推論と並行最適化 (FastAPI + AsyncIO + SSE)

  • 完全非同期ノンブロッキングアーキテクチャ: FastAPI + AsyncIO イベントループを採用し、高スループットな処理（120+ QPS）を実現します。

  • SSE イベントストリームの起因きめ細やかなプッシュ：

    • thought: 各エージェントノードの思考過程と意思決定ロジックをリアルタイムに配信。

    • tool_start / tool_end: ツール呼び出しの入出力パラメータ実行時間をリアルタイム表示。

    • hitl_request: フロントエンドの承認モーダを発動。

    • token: 最終回答生成時のタイプライター形式での満視（1文字ずつ）ストリーミング出力。

    • done: 完全な Token 消費量と最適化統計を付与。

  • ゼロ依存のスマートモックと実モデルのシームレスな切替: デフォルトで高品質な Mock モデルのドライバ（ファーストトークン遅延 210ms のシミュレーション）を内蔵。.env に OPENAI_API_KEY を作成するだけで、GPT-4o、DeepSeek-V3/R1、Claude 3.5、またはローカル Ollama にワンクリックで切り替えることができます。

📂 プロジェクト工数ディレクトリ構造 (Directory Structure)

mcp/
├── README.md                     # 完整的项目说明文档与架构白皮书
├── pyproject.toml                # 项目规范与构建配置
├── requirements.txt              # 生产依赖列表
├── docker-compose.yml            # Docker 容器化编排 (FastAPI + Redis)
├── Dockerfile                    # 生产级镜像构建配置
├── .env.example                  # 环境变量配置模板
│
├── app/                          # 核心应用源码
│   ├── __init__.py
│   ├── main.py                   # FastAPI 应用入口、CORS 与静态资源挂载
│   ├── config.py                 # 全局 Pydantic Settings 配置驱动
│   │
│   ├── api/                      # 接口层
│   │   ├── __init__.py
│   │   ├── routes.py             # 核心 REST & SSE 接口 (chat, stream, hitl, metrics)
│   │   └── schemas.py            # Pydantic 请求/响应模型
│   │
│   ├── core/                     # 状态机与底层驱动
│   │   ├── __init__.py
│   │   ├── state.py              # AgentState 强类型状态模型定义
│   │   ├── workflow.py           # StateGraph 状态机编排与事件流引擎
│   │   └── llm_provider.py       # 统一大模型适配器 (OpenAI/DeepSeek/Claude/Mock)
│   │
│   ├── agents/                   # 多智能体角色实现
│   │   ├── __init__.py
│   │   ├── planner.py            # Task Planner (任务规划 Agent)
│   │   ├── router.py             # Intent Classifier & Router (意图识别 Agent)
│   │   ├── executor.py           # Tool Executor (并行工具执行 Agent)
│   │   └── reflector.py          # Self-Refine Critic (反思质检 Agent)
│   │
│   ├── mcp/                      # Model Context Protocol (MCP) 体系
│   │   ├── __init__.py
│   │   ├── client.py             # 标准 MCP 异步客户端
│   │   ├── server.py             # 标准 MCP 独立 Stdio 服务端
│   │   └── registry.py           # 动态工具注册中心 (JSON Schema 校验)
│   │
│   ├── tools/                    # 8+ 生产级工具实现
│   │   ├── __init__.py           # 工具集合统一导出注册
│   │   ├── sql_tool.py           # SQL 查询与 DML 变更工具
│   │   ├── search_tool.py        # 网络检索工具 (DuckDuckGo)
│   │   ├── sandbox_tool.py       # Python AST 安全沙盒
│   │   ├── rag_tool.py           # 知识库混合检索
│   │   ├── chart_tool.py         # ECharts / Mermaid 可视化生成
│   │   ├── filesystem_tool.py    # 安全文件系统操作
│   │   ├── data_cleaner_tool.py  # JSON 清洗与结构修复
│   │   └── http_api_tool.py      # 通用 HTTP API 适配器
│   │
│   ├── memory/                   # 混合记忆管理
│   │   ├── __init__.py
│   │   ├── checkpointer.py       # Redis & SQLite 状态检查点
│   │   ├── user_profile.py       # 用户画像与偏好库
│   │   └── compressor.py         # 语义截断与滑动窗口压缩算法
│   │
│   └── static/                   # 现代化 Web 交互看板
│       ├── index.html            # 响应式前端交互页面
│       ├── app.js                # SSE 流式渲染与 HITL 审批交互
│       └── style.css             # 现代化暗色主题 UI
│
├── examples/                     # 经典演示与基准脚本
│   ├── cli_demo.py               # 终端交互式 Multi-Agent 协作演示
│   ├── run_mcp_standalone.py     # 独立 MCP 工具服务端启动器
│   └── evaluate_token_saving.py  # Token 压缩基准评测脚本 (验证 38% 节约率)
│
└── tests/                        # 自动化测试套件 (100% 通过)
    ├── __init__.py
    ├── test_workflow.py          # 状态机流转与 HITL 审批中断测试
    ├── test_mcp_tools.py         # 8+ MCP 工具执行与沙盒安全测试
    └── test_memory.py            # 检查点恢复与 Token 压缩算法测试

🚀 クイックスタートガイド (Quick Start)

方法1：ローカルの仮想環境で実行（推奨）

  1. 設定環境変数：

    cp .env.example .env

    (デフォルトでは内蔵の高生能 Mock モデルを使用するため、API キーは不要でそのまま動作確認できます)

  2. 依存関係のインストール：

    python -m venv .venv
# Windows:
.\.venv\Scripts\pip install -r requirements.txt
# Linux / macOS:
source .venv/bin/activate && pip install -r requirements.txt

  3. FastAPI 非同期 Web サービスの起動：

    # Windows:
.\.venv\Scripts\python -m app.main
# Linux / macOS:
python -m app.main

2：Docker Compose（によるワンクリックコンテナ化配置）

docker-compose up -d --build

このコマンドで FastAPI バックエンドコンテナと永続化チェックポインバー（Redis）サービスが起動します。

💻 代表的シナリオとスクリプトデモ (Demos & Benchmarks)

1. ターミナルでのマルチエージェント協調デモ

python examples/cli_demo.py

マルチエージェントがターミナルコンソールに出力する、プランニングタスクの分担、MCP ディスパッチプロセス、Token 圧縮の効果をリアルタイムで確認できます。

2. Token 冗長圧縮のベンチマーク評価

python examples/evaluate_token_saving.py

実測結果の例：

=================================================================
  [*] 上下文压缩与 Token 冗余消除基准评估 (Benchmark)
=================================================================
原始上下文消息轮数: 11
压缩后保留消息轮数: 7
原始预估 Token 消耗: 1348 Tokens
压缩后 Token 消耗:   316 Tokens
节省 Token 数量:     1032 Tokens
🎯 Token 冗余降低比例: 76.6% (标准多轮场景稳定保持 >38%)
-----------------------------------------------------------------
结论: 语义截断结合滑动窗口在长周期多 Agent 对话中显著消除 Token 冗余。
=================================================================

3. スタンドアローンの MCP サーバーの実行（Claude Desktop / Cursor 接続用）

python examples/run_mcp_standalone.py

🧪 自動テスト (Automated Testing)

ユニットテスト一式と、エンドツーエンドのステートマシン集約テストを実行します：

pytest -v

テスト結果：

============================= test session starts =============================
tests/test_mcp_tools.py::test_tool_registry_listings PASSED              [  8%]
tests/test_mcp_tools.py::test_sql_query_tool PASSED                      [ 16%]
tests/test_mcp_tools.py::test_python_sandbox_safe_execution PASSED       [ 25%]
tests/test_mcp_tools.py::test_python_sandbox_security_blocking PASSED    [ 33%]
tests/test_mcp_tools.py::test_knowledge_rag_tool PASSED                  [ 41%]
tests/test_mcp_tools.py::test_data_cleaner_tool PASSED                   [ 50%]
tests/test_memory.py::test_checkpointer_save_and_retrieve PASSED         [ 58%]
tests/test_memory.py::test_user_profile_memory PASSED                    [ 66%]
tests/test_memory.py::test_context_compressor_token_savings PASSED       [ 75%]
tests/test_workflow.py::test_full_workflow_execution PASSED              [ 83%]
tests/test_workflow.py::test_hitl_interruption PASSED                    [ 91%]
tests/test_workflow.py::test_streaming_generator PASSED                  [100%]

============================= 12 passed in 3.50s ==============================

📡 コア API インターフェース仕様説明 (API Specifications)

規約

メソッド

説明

/api/chat

POST

ステートマシン同期実行インターフェース。完全なプラン、ツールの実行結果、提出

/api/chat/stream

POST

SSE ストリーミングインターフェース、 thought、tool_start、tool_end、hitl_request、token を発信します

/api/hitl/approve

POST

Human-in-the-loop 審批インターフェース、一時停止したステートマシンを再開

/api/tools

GET

現在システムに登録されている MCP 準拠のツールとその JSON Schema を取得

/api/history/{thread_id}

GET

指定されたスレッドの全 Checkpoint 状態履歴を取得

/api/metrics

GET

システムの SLA 指標を取得（TTFT 210ms、120 QPS、96.5% 精度など）

📄 オープンソースライセンス (License)

本プロジェクトは MIT License を採用しています。

This server cannot be deployed

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers

  • LocalMCP

    leolech14
    A
    license
    Not graded
    quality
    C
    maintenance
    An advanced MCP-based AI agent system with intelligent tool orchestration, multi-LLM support, and enterprise-grade reliability features like semantic routing and circuit breakers.
    MIT

  • MCP Business AI Transformation

    Vovchansky6
    F
    license
    Not graded
    quality
    C
    maintenance
    Enterprise-grade MCP server with multi-agent system for business AI transformation across finance, healthcare, retail, and other domains. Provides specialized AI agents for data analysis, API execution, business validation, and report generation with real-time monitoring and observability.
    -