AgentGate 是一个开源的 Python 框架，做多 Agent 系统的可靠性。
它解决一个结构性问题：系统里的 Agent 产出，没有人验证。LangChain、CrewAI、LangGraph 的调度器都默认 Agent 产出可信，直接传给下游。这个假设在我跑了 100 多次 12 步管线之后被证伪了------无验证成功率约 60%，而且大部分失败是静默的：Agent 报告成功，磁盘上是空的。
AgentGate 的验证针对的正是这个问题。三道闸门：产出文件必须真实存在且非空；所有 Bash 验证必须带 EXIT_CODE 指纹------Agent 可以编测试结果，编不了退出码；面向客户的产出过脱敏检查。另外下游 Agent 会随机抽查上游声称的接口覆盖。任何一道不过，产出不放行，按错误类型定向回环到对应 Agent 修复，连续失败升级人工闸门。
这篇文章写的是为什么验证层必须存在，以及 5 层架构每一层解决哪类失败。
失败不是随机的：8 类
被 Agent 骗的次数多了，我开始记录每次翻车的原因。记到后面发现没有新的了------多 Agent 系统的失败一共 8 类。
① 执行幻觉。Agent 说「跑了 pytest，28 个测试全过」。实际没跑，这句话是编的。
② 产出幻觉。Agent 说「main.py 写好了」。文件不存在。下游基于这句话继续干活，几步全白做。
③ 能力幻觉。Agent 说「已覆盖全部验收标准」。抽查两条，一条没做。
④ 流程幻觉。要求先读需求再写代码。它跳过了读需求，写出来的东西和需求对不上。
⑤ 上下文幻觉。上游把接口从 /api/users 改成 /api/v2/users，没通知下游。下游调老接口调不通，烧了几轮 token 才发现。
⑥ 提示词幻觉。同一个提示词在 Claude 下正常工作，换到 Qwen 下被理解成完全不同的指令。不是模型笨，是提示词没适配。
⑦ 状态丢失。12 步管线跑到第 8 步崩了。前面 7 步的产出在上下文窗口里，窗口一爆全没了。从头再来，这次生成的代码跟上次不一样。
⑧ 静默卡死。不报错、不超时、不崩溃，就是不动了。三小时后你回来看，卡在第 7 步。
这 8 类有一个共同点：没有一类是模型问题。我从 Claude 换到 Qwen，换到本地的小模型，翻车率基本没变。因为漏洞不在模型里，在系统结构里------Agent 和 Agent 之间的那一段，没有人管。
8 个主流框架，没有一家管这一段
我把 8 个主流框架的文档翻了一遍，看哪家提供了产出验证。
| 框架 | GitHub star | 编排方式 | 产出验证 |
|---|---|---|---|
| Dify | 158K | 可视化工作流 | 无 |
| AutoGen | 61K | 多 Agent 对话 | 无 |
| CrewAI | 59K | 角色协作 | 无 |
| LangGraph | 43K | 状态机 | 无 |
| PydanticAI | 20K | 类型安全 Agent | 无 |
| LlamaStack | 8K | 模型服务层 | 无 |
| AG2 | 5K | 多 Agent 对话 | 无 |
| BeeAI | 3K | 工作流 | 无 |
（star 数截至 2026 年 10 月）
没有一家做验证拦截。这不是某个框架的疏忽，是整个行业的默认假设：Agent 产出可信。RAG 解决的是「引用的事实不存在」这类幻觉，解决不了上面 8 类里的任何一类------RAG 不会告诉你文件不存在，也不会告诉你测试没跑。
AgentGate 反着来：默认所有 Agent 产出都不可信，验证过了才算。
5 层架构：每一层对应哪几类失败
闸门是核心，但只有闸门不够。8 类失败对应 5 层防御。
① 记忆层 → 状态丢失。项目记忆存磁盘，会话日志记进度，断点恢复。Agent 调完不消失。
② 上下文层 → 上下文幻觉。上游产出物化为不可变快照，下游先读 200 字摘要再决定要不要深读源文件，总上下文有预算控制。8K 窗口的模型也不会被 15KB 文档淹掉。
③ 防幻觉层 → 执行/产出/能力/流程幻觉。就是开头说的三道闸门加交叉验证。这里有个细节值得说：EXIT_CODE 指纹。Agent 可以编「测试全过」这句话，编不了 Bash 的退出码。你让它把 EXIT:0 贴出来，有就是有，没有就是编的。
这些闸门卡的不是理论问题。有个项目界面样式改了三次没生效，查了两天------两个 CSS 文件写了同名选择器，后面的静默覆盖前面的。还有一次数据库表全「没了」，Agent 用相对路径 ./data/db.sqlite 连接，工作目录一变，连到了另一个空库。闸门卡的就是这类东西：文件在不在、退出码对不对、覆盖声明真不真。
④ 提示词层 → 提示词幻觉。提示词按五模块结构自动生成，按场景适配。每次运行都会给提示词打分------打分器是正则规则，不是 LLM（打分的人自己不能幻觉）：低于 60 分自动重写，下一次重试时用新提示词；60 到 80 分记入警告。很多时候不是模型不行，是提示词没配好。
⑤ 流程层 → 静默卡死。管线卡住有诊断器自动定位根因；连续失败触发人工闸门，结构化提问，不给空白输入框；失败按错误类型定向回环------代码 bug 回开发 Agent，架构问题回设计脑，而不是无脑从头重跑。
这 5 层不是各管各的。8 类失败会串：上游的产出幻觉，直接喂给下游变成上下文幻觉。缺一层就漏一类，所以 5 层是配套的。
三个不显然的设计决策
设计脑是 LLM，执行脑不是。
AgentGate 有两层大脑。设计脑负责分析需求、拆解 Agent、定义验收标准------需要创造力，用 LLM，只用一次，产出配置文件就下班。执行脑负责调度、过闸门、判定回环------一行 LLM 都不调，纯 Python 规则引擎。每一次 PASS/FAIL、回环到谁、重试几次，全部硬编码，可追查、可复现。
为什么？因为如果执行脑也是 LLM，它自己就会幻觉。CrewAI 的 Manager Agent 就是一个 LLM 在做调度------它可能做出错误决策，而且没人在验证 Manager 的决策。AgentGate 把不信任贯彻到底：连主脑自己也被闸门约束。
约束手，不约束脑。
闸门只卡可验证的东西：文件存在、退出码、接口覆盖。它不管 Agent 怎么思考、用什么推理路径、写什么风格的代码。闸门是地板，不是天花板------只管「不低于」，不管「有多高」。思想没法验证，强行约束只会把模型关进笼子；手可以验证，所以手必须被约束。
不做模型智能，做调用间可靠性。
AgentGate 不训练模型、不优化推理------模型智能是模型厂商的事。它做的是多次调用之间的可靠性。单步调用无所谓，步数越多越值钱。按每步独立出错率估算：12 步管线，无验证成功率约 60%，加验证层 95% 以上。这是估算值，不是基准测试数据，后面会补实测。所有人都在造引擎，刹车赛道是空的。
几个诚实的局限
编排做减法：只支持串行和并行，没有条件分支。不是做不了，是刻意不做------配置一复杂就越来越像代码，违背声明式配置的初衷。复盘真实场景，条件分支的常见需求------错误恢复、内容路由、空数据适配------都能被定向回环和验收标准覆盖。
不做 Agent 运行时。ReAct 循环、工具调用、流式输出是底层框架的事，AgentGate 里的 Agent 可以是 LangChain 封装的，也可以是裸 LLM 调用。
127 个测试通过，每次提交 CI 自动跑。MIT 协议，还在迭代，欢迎 issue。