mcp-multi-agent-dispatch

MCP 工具层 + LangGraph 三代理编排：调度员说一句话，系统查队列、选机器人、算路径、派单、上报故障，写操作走人工审批，重复提交走幂等。

不是"多代理聊天演示"：13 条端到端用例全部走真 MCP 协议（in-memory transport）和真 LangGraph 状态机，覆盖越权、状态冲突、信息不足、重复提交四类边界。

Agent 级指标：正例和负例必须分开算

如果把正负例混在一起算"工具成功率"，AssignAgent 会掉到 0.17——看上去像这个代理基本不工作。真实原因是 5 条负例（低电量、任务已被占用、越权）本来就该被工具拒绝，拒绝是正确行为。

这也解释了为什么没做 token 成本与通信效率：这个项目里 planner 是正则规则、三个代理是顺序函数调用，既没有 LLM 调用也没有 agent 间消息。那两项指标在这里没有定义，硬凑出来就是编的。

跑起来

pip install -e .

python -m dispatch_agent.cli tools                       # 列出 6 个 MCP 工具
python -m dispatch_agent.cli run "查一下 W1 排队的任务" --user U001
python -m dispatch_agent.cli run "把任务 T2002 派给机器人" --user U001
python -m dispatch_agent.cli run "R102 一级故障，马上处理" --user U002 --manual   # 走人工审批
python scripts/eval_graph.py                             # 13 条端到端评测

--transport direct 可绕过 MCP 直调工具实现，只用于排查是"协议问题"还是"逻辑问题"。

要求 Python ≥ 3.11。人工审批那条路径（--manual）用 interrupt() 实现，它靠 ContextVar 取 thread_id； 把 context 传进工作线程的 run_coroutine_threadsafe(context=...) 是 3.11 才有的参数，3.10 上会在审批时抛 Called get_config outside of a runnable context。同步节点不受影响，所以症状是"别的都能跑，只有 --manual 挂"—— 这是解释器版本问题，不是图写错了。原因与验证过程见 docs/design.md §3。

Related MCP server: Codex Control Plane MCP

架构

用户指令
   │
   ▼
┌──────────────┐   规则化解析：intent + slots + 缺失项
│  understand  │   缺参数 → clarify（不猜）
└──────┬───────┘
       ▼
┌──────────────┐   AssignAgent（单任务选车）
│   propose    │   PathAgent（只读路径）
└──────┬───────┘   CollabAgent（批量/异常）
       ▼
┌──────────────┐   只有 write=True 的动作进审批
│    review    │   interrupt + checkpointer，断点可恢复
└──────┬───────┘
       ▼
┌──────────────┐   失败按 fallbacks 换候选；步数上限 8；动作指纹去重
│   execute    │
└──────┬───────┘
       ▼
    finalize  →  中文答复 + 每个工具的执行码

   工具层（MCP）：query_tasks / list_robots / get_battery / plan_path
                  assign_task / report_fault
                  鉴权 → 幂等 → 资源存在 → 业务规则 → 执行

三个关键设计

① 授权在工具层，不在 Agent 层。 Agent 可以"提议"任意操作，但工具自己决定执不执行。模型被诱导、Agent 写错逻辑，都越不过这条线。这也是为什么 authorize() 在 _assign_task 的第一行，而不是在 graph 里。

② 写操作与只读操作共用一条图，只有写操作进审批。 只读（查队列、算路径）直接执行，写（派单、报障）必须过 review。判断依据是 Action.write，不是"哪个 agent 调的"——同一个 agent 可能既查又写。 审批用 interrupt() + checkpointer：暂停时整个 state 被序列化进 checkpoint，恢复时从断点继续、不重新执行 propose。 但要分清机制和配置——demo 配的是 MemorySaver，它活在进程内存里，真的重启进程状态还是丢。所以准确说法是： 「机制上支持断点恢复；demo 的 checkpointer 是内存实现，跨进程要换 Postgres checkpointer」。这就是"能续跑"和"假装能续跑"的差别所在。

③ 防死循环靠三道，但当前这张图其实用不上。

说清楚一件事：当前图是 DAG（understand → propose → review → execute → finalize），没有回边，一个请求最多产生一个写动作，所以这三道在 13 条用例下一次都没触发——stall_events = 0 是正确结果，不是没实现。它们是给"加反思回边"预留的保险丝。

诚实一点讲这件事比硬说"我做了防死循环"更值：能用代码证明它有效的前提，是先说清它什么时候才需要生效。

业务规则（都在 store.py，改这里不影响编排）

机器人与任务数据的口径见 data/mock_business.json：3 个仓库、11 台机器人、7 条任务、4 个角色。

评测怎么做的

scripts/eval_graph.py 里 13 条用例，每条重置内存库再跑（用例间状态污染是这类测试最常见的假通过来源），断言落在三处：

1. 最终回答（是否说清"派给了谁""路径是什么"）

2. 每个工具的返回码（BATTERY_TOO_LOW / UNAUTHORIZED 这些不是异常，是业务语义）

3. 批内一致性（一次派三单不能把同一台机器人派两次）

刻意设计的三类用例：

• 点名但不可用：用户说"派给 R103"，而 R103 电量 18% → 必须拒绝，不能悄悄换成别的机器人。所以点名时 fallbacks 为空。

• 越权：viewer 派单、dispatcher 查别的仓 → 由工具拒绝，不是 Agent 拒绝。

• 重复提交：同一条派单连跑两次 → 第二次返回 IDEMPOTENT_REPLAY，不重复下发给机器人。

三个指标的定义与局限

⚠️ 这几个数都只来自 13 条用例，属于"能证明链路通、不能当性能基准"。3.46 这个数尤其不能外推——它完全取决于 assign 里查了几次、语料里几个仓几台车。

与真实系统的差异（别把它当成生产代码）

保留规则化解析是故意的：换成模型后，每个失败都会变成"模型没理解"这种不可定位的原因，评测数字就不可复现了。先把编排和边界验证对，再换模型。

目录

src/dispatch_agent/
  models.py      枚举与数据结构
  store.py       mock 业务库 + 幂等表 + Dijkstra 路径
  auth.py        工具级 + 仓库级双层鉴权
  tools.py       FastMCP 6 个工具（唯一能改状态的入口）
  planner.py     规则化意图解析
  agents/        AssignAgent / PathAgent / CollabAgent + 工具网关
  graph.py       LangGraph 状态机（含 interrupt 与防死循环）
  cli.py         命令行入口
data/mock_business.json   3 仓库 / 11 机器人 / 7 任务 / 4 角色
scripts/eval_graph.py     13 条端到端评测
results/eval_report.json  实测报告

License

MIT —— 见 LICENSE。data/mock_business.json 为虚构业务数据。