选 Agent 框架，先验证控制流和失败路径

选 Agent 框架，先验证控制流和失败路径

框架的功能清单、社区热度和单次演示都不足以决定是否适合题解服务。要看的是它能否让请求在超时、取消、工具失败和流量过载时以可预测的方式结束。

对需要编译、检索和模型调用的任务，状态机往往比自由循环的多 Agent 更容易观察和测试：每个状态有输入、最大执行时间、允许的下一状态和失败出口。使用成熟框架也可以做到这一点，关键不在于“自研”还是“开源”。

type Step interface { Run(context.Context, Task) (Task, error) }

func run(ctx context.Context, steps []Step, task Task) (Task, error) {
	for _, step := range steps {
		var err error
		task, err = step.Run(ctx, task)
		if err != nil { return task, err }
	}
	return task, nil
}

选型验证至少覆盖：并发上限下的排队或拒绝、外部调用超时、重复工具调用、取消传播和结构化输出校验。记录框架版本、配置、负载和观测方式，才能比较不同方案。性能或内存结论不能脱离这些条件。

先把一次任务画成能结束的流程

例如，一次题解诊断可以拆成“校验输入、编译、运行测试、整理结果”四步。每一步都应声明成功后的去向，以及失败时是直接返回、允许重试，还是降级为只给出静态建议。框架把这些边暴露出来，排障才有入口；如果控制流藏在提示词或回调里，出了问题很难判断请求到底卡在哪一步。

上面的 run 是顺序执行的最小形式。它没有自动重试、并行分支和补偿逻辑。不要把这些能力默认加进去：编译失败通常不是瞬时错误，重复运行只会浪费资源；检索服务临时不可用，才可能适合在总超时内有限重试。重试次数、退避方式和幂等条件应该由具体 Step 决定。

用故障注入验证，而不是只跑通演示

测试时可以替换一个 Step，让它返回超时、格式错误或可重试错误，并检查后续步骤是否被阻止、调用方是否收到可识别的错误。再用已取消的 context 启动任务，确认编译和外部调用没有继续占用资源。对于会写入状态或触发工具的步骤，还要验证重复执行不会产生重复副作用。

选框架时，最有价值的产物不是一张功能对比表，而是一组能反复运行的验收用例。框架升级、配置修改或切换模型后，都用同一组用例回归，才能知道控制流是否仍符合预期。

3. 让状态转换能被现场还原

Agent 任务出问题时，单看最后一段回答没有用。需要记录任务从哪个节点进入、依据什么条件离开、使用了哪一版输入摘要，以及每次工具调用的结果类别。记录不必保存完整提示词或敏感数据；保留状态版本、节点名、耗时和经过脱敏的原因码，已经足够重建大多数失败路径。

这样做也能约束框架选择。某个框架如果很容易跑出演示，却难以导出状态快照和中断后的恢复点，接入生产后排查成本会很高。先拿一条真实工作流做故障注入，再比较记录质量和恢复方式，比看组件数量更有参考价值。

4. 人工接管必须有入口

涉及付款、发布或修改权限的节点，不应只依赖模型自己判断是否继续。状态图中应预留人工接管节点，展示当前证据、待确认动作和可选的终止路径。接管后再恢复任务时，系统要记录是谁在什么条件下继续，避免同一副作用被重复执行。

这类设计也让失败更可控：模型不确定时可以停在明确的位置，而不是编造一个看似完整的结果。把接管次数和原因汇总起来，后续才能判断是提示词不足、工具契约不清，还是流程本身不适合自动化。