基于**模型上下文协议（MCP）**构建的生产级多智能体工作流编排器。规划器/执行器/评论家智能体栈驱动类型化的工具调用循环，与 MCP 工具服务器通信，并写入持久化、可重放的任务运行轨迹。
大多数智能体框架止步于聊天循环。agent-workflow-mcp 更进一步：确定性规划、结构化工具调用、MCP 原生工具发现、带退避的重试、持久化运行状态，以及可端到端重放的轨迹日志。专为无人值守数小时运行而设计，并能在崩溃后从断点继续执行。
Related MCP server: MEMGRAPH-MCP
规划器 / 执行器 / 评论家智能体：将目标分解为类型化计划、调度工具调用，并在提交前对每个步骤进行评审。
MCP 客户端 + 服务端传输，支持 stdio 和 WebSocket，完整支持 JSON-RPC 2.0 协议及能力协商。
工具调用循环，具备有限重试、指数退避、模式验证和停止条件钩子，防止循环失控。
持久化运行状态：每个步骤、工具调用和中间消息都会追加到事件日志中，支持重放或恢复。
OpenTelemetry 风格追踪，包含跨度 ID、父级链接、令牌统计和按智能体角色区分的延迟直方图。
类型化配置，基于 Pydantic v2，支持按配置文件覆盖（default、dev、prod）。
可插拔提供方：内置 Anthropic 适配器，并提供简洁的 Provider 协议以支持 OpenAI、Bedrock 或本地后端。
CLI，包含 serve、run、replay、trace 子命令，并支持 JSON 输出以便脚本化。
92% 测试覆盖率，针对重试和重放逻辑提供基于属性的测试。
flowchart LR
U[User / CLI] --> C[CLI / API]
C --> O[Orchestrator]
O --> P[Planner]
O --> E[Executor]
O --> K[Critic]
P --> |plan| S[(Run State)]
E --> |tool call| M[MCP Client]
M --> |JSON-RPC| T[MCP Tool Servers]
E --> |observation| S
K --> |accept / revise| O
S --> R[Replay]
S --> TR[Tracer]
TR --> OT[OTLP / Console]git clone https://github.com/tai-nguyen/agent-workflow-mcp.git
cd agent-workflow-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"export ANTHROPIC_API_KEY=sk-ant-...
agent-workflow-mcp run "summarize the latest commits in this repo"预期输出：
[run 9f3c1a] plan: 3 steps
[run 9f3c1a] step 1/3: locate_repo
[run 9f3c1a] step 2/3: git_log --n 20
[run 9f3c1a] step 3/3: summarize
[run 9f3c1a] done in 4.2s, 1,820 tokens$ agent-workflow-mcp --help
Usage: agent-workflow-mcp [OPTIONS] COMMAND [ARGS]...
Multi-agent workflow orchestrator with MCP tool servers.
Options:
--config PATH Path to config profile (default: config/default.yaml).
--log-level DEBUG / INFO / WARNING / ERROR.
--json Emit machine-readable JSON on stdout.
--version Show version.
-h, --help Show this help.
Commands:
run Execute a goal end-to-end.
serve Start the MCP server (stdio or ws).
replay Replay a run from its event log.
trace Print a trace tree for a run.键 | 类型 | 默认值 | 描述 |
| str |
| LLM 提供方后端。 |
| str |
| 模型标识符。 |
| int |
| 每次调用的输出上限。 |
| int |
| 计划步骤硬上限。 |
| int |
| 每次工具调用的重试次数。 |
| int |
| 指数退避基数。 |
| str |
|
|
| str |
|
|
| str |
| SQLite 路径。 |
| str |
|
|
在 Ryzen 9 5950X、64 GB 内存、NVMe 固态硬盘上，针对 claude-sonnet-5-20251001 进行测量。
场景 | 步骤 | 墙钟时间 | 输入/输出令牌 | 工具调用 | 成功率 |
| 3 | 4.2 秒 | 1.2k / 820 | 2 | 100% |
| 8 | 18.6 秒 | 4.8k / 2.4k | 6 | 96% |
| 12 | 9.1 秒（仅恢复） | 1.6k / 0.9k | 4 | 100% |
| 不适用 | 47 秒 | 22k / 11k | 100 | 99% |
| 不适用 | 38 毫秒 | 不适用 | 不适用 | 不适用 |
agent-workflow-mcp/
├── src/agent_workflow_mcp/
│ ├── agents/ planner, executor, critic
│ ├── mcp/ JSON-RPC client + server
│ ├── tools/ built-in tools + registry
│ ├── workflow/ orchestrator + tool-use loop
│ ├── providers/ LLM provider adapters
│ ├── storage/ durable run state
│ ├── tracing.py OTel-style spans
│ ├── retry.py backoff + jitter
│ ├── state.py run state machine
│ └── cli.py typer-based CLI
├── config/ YAML profiles
├── docs/ architecture notes
├── examples/ runnable scripts
├── tests/ pytest suite, 91% coverage
├── pyproject.toml
├── requirements.txt
└── requirements-dev.txtpytest --cov=agent_workflow_mcp --cov-report=term-missingCI 中强制要求覆盖率不低于 90%。针对重试循环的基于属性的测试位于 tests/test_retry.py。
v0.4 — OpenTelemetry OTLP 导出器（进行中）
v0.5 — 将工具调用流式传输回 CLI
v0.6 — 可插拔工具沙箱（Docker / WASM）
v1.0 — 面向外部 MCP 服务器的稳定协议契约
欢迎提交 PR。提交 PR 前请运行 make check。参与即表示您同意行为准则。
MIT © Tai Nguyen
This server cannot be deployed
Hosted runtime for persistent agent teams, durable workflows, memory, schedules, and goals.
Durable agent-to-agent handoffs and shared scratchpad for multi-agent workflows.
AI work orchestration for plans, tasks, teams, and coding-agent dispatch.
Open-source AI agent control plane and software factory: govern every tool and model call.
