Agent Framework Lab 开发实录：从比较 demo 到企业就绪 Alpha

Fri, 18 Sep 2026 00:00:00 +0000

这是 Agent 框架评测实验室系列第五篇，也是阶段开发记录。

起点：先让不同框架完成同一任务

Lab 最早解决的是兼容性：统一 stdin/stdout 的请求与结果契约，让不同 Python/Node 框架可以在各自隔离环境运行。这个阶段最直观的产物是 matrix 和报告，但也很快暴露问题：

每个 adapter 对 usage 的理解不同；
有的框架隐藏模型重试；
MCP SDK 与 CLI 协议不同；
同名模型可能被 gateway 路由到不同后端；
prompt、工具包装稍有不同，分数就不可比。

因此第一条经验是：先统一证据格式，再谈统一排行榜。

V2.0—V2.1：运行时从附属代码变成核心边界

普通 runner 只关心子进程退出码。企业 Agent 还需要 job、attempt、lease、事件 revision、预算 reservation、checkpoint 和 immutable artifact。

runtime-v1 采用 SQLite WAL 和 append-only event/reducer：

command -> validate current snapshot -> append events
 -> reduce new snapshot -> transactionally persist both

这个阶段没有急着做远程服务，而是坚持单机、一次命令、可验证状态。事实证明这是正确取舍：并发和网络还没加入时，就已经发现事件序列、预算结算和终态工件之间有大量边界条件。

V2.2：恢复不是“再跑一次”

接下来加入 host crash、SQLite reopen、orphan attempt 回收和 checkpoint resume。LangGraph composed 与 OpenAI Agents native 都通过了“researcher 已完成后恢复，只继续 analyst/reviewer”的测试。

Agent 框架开发与评测踩坑实录：从能跑到可审计、可比较

Thu, 17 Sep 2026 18:00:00 +0800

很多 Agent demo 的成功标准是：“模型能调用工具，最后返回一个答案。”

本文现作为《Agent 框架评测实验室系列》的代码型伴读；系列正文进一步讨论公平赛道、企业场景、故障证据、评分统计和项目演进。

但只要把它放进真实系统，问题马上变成另一组问题：任务执行到一半进程崩了怎么办？审批通过的到底是哪一次工具调用？工具重试会不会重复扣款？两个框架比较时，是否真的使用了同一份提示词和工具？模型价格变化后，旧实验的排名还能不能复算？

我在 Agent Framework Lab V2 RC 中把这些问题做成了一个可以运行、恢复、审计和比较的实验台。本文不讲“Agent 很有前景”，只记录实现过程中最容易被低估的坑、最终采用的设计，以及可以直接复制的代码片段。

先给结论：Agent 评测是一条证据链

可信的评测结果必须能回答：这次运行用了哪个框架、模型、provider、提示词和工具？模型调用、工具调用、审批、checkpoint 的顺序是什么？崩溃或重启后哪些动作被恢复，哪些动作绝不能重放？结果怎么评分？换一组权重后能否只重算排名？排名是否因为 ground truth 写错了？

因此数据流不是：

prompt -> model -> score

而是：

任务契约 + 模型契约 + 工具契约
 ↓
 append-only 运行事件
 ↓
 不可变 RunResult 原始证据
 ↓
 可重算的 ScoreProfile
 ↓
 排名、图表和审计报告

坑一：把“任务成功”和“评分高”混成一件事

一次运行可能在运行时层面成功完成，但答案质量只有 60 分；反过来，一个答案看起来不错，也不能掩盖未授权工具调用、预算超限或事件账本损坏。

Lab 将两者拆开：

class RunResult(BaseModel):
 run_id: str
 matrix_id: str
 framework: str
 case_id: str
 status: Literal["completed", "failed", "blocked_gateway_contract", "unavailable"]
 final_output: str = ""
 tool_calls: list[ToolCallRecord] = []
 model_calls: list[ModelCallRecord] = []
 usage: Usage = Usage()
 score: Score | None = None
 trace_id: str | None = None
 metadata: dict[str, Any] = {}

status == completed 只表示执行器完成生命周期；score.total 是评测器对结果的判断。模型返回错误 JSON 时，运行可以成功但结构化输出为 0；预算结算失败时，即使模型输出正确，也必须判为运行时失败；评分规则改变时，可以重算分数，但不能重写原始执行状态。