Agent 可靠性工程实战（一）：先给智能循环装一只不可失忆的黑匣子

很多 Agent 教程从模型、提示词和工具调用开始演示效果很热闹却跳过了最先该解决的问题一次任务失败以后我们能否准确回答模型看到了什么、调用了什么、工具返回了什么、为什么停止。普通文本日志只记录人类觉得重要的句子无法支撑确定性回放。这个系列从一个名为ProofLoop的本地代码修复执行器开始第一篇只建骨架和事件账本不接真实模型。整个项目遵守一个边界模型可以提出动作宿主程序决定是否执行裁判程序决定结果是否合格。三者不能共用一团可随意修改的内存状态。我们先把每一步写成追加式 JSONL 事件让后续九篇都把runs/run_id/events.jsonl当输入。一、事件不是调试字符串而是状态事实传统日志写“正在运行测试”但这句话没有稳定字段换一句措辞就无法统计。事件则包含序号、任务编号、事件类型、时间和结构化载荷。序号负责定义因果顺序任务编号隔离并发执行事件类型形成可版本化协议。时间只用于观察耗时不能决定业务顺序因为系统时钟会回拨多线程也可能在同一微秒写入。下面的ledger.py使用标准库实现最小账本。每次追加先序列化为单行 JSON再刷新并同步文件描述符。它不能让磁盘永不损坏却把“Python 返回成功但数据仍停在用户态缓冲区”的窗口缩小。载荷只允许 JSON 类型模型原始回答若包含敏感信息应在进入账本前脱敏。from__future__importannotationsimportjsonimportosfromdataclassesimportasdict,dataclassfromdatetimeimportdatetime,timezonefrompathlibimportPathfromtypingimportAnydataclass(frozenTrue)classEvent:seq:intrun_id:strkind:strat:strpayload:dict[str,Any]classLedger:def__init__(self,path:Path,run_id:str)-None:self.pathpath self.run_idrun_id self.path.parent.mkdir(parentsTrue,exist_okTrue)self.next_seqself._count_lines()1def_count_lines(self)-int:ifnotself.path.exists():return0withself.path.open(encodingutf-8)ashandle:returnsum(1forlineinhandleifline.strip())defappend(self,kind:str,payload:dict[str,Any])-Event:eventEvent(seqself.next_seq,run_idself.run_id,kindkind,atdatetime.now(timezone.utc).isoformat(),payloadpayload,)encodedjson.dumps(asdict(event),ensure_asciiFalse,separators(,,:))withself.path.open(a,encodingutf-8)ashandle:handle.write(encoded\n)handle.flush()os.fsync(handle.fileno())self.next_seq1returneventdefmain()-int:ledgerLedger(Path(runs/demo-001/events.jsonl),demo-001)ledger.append(run_started,{goal:修复折扣计算})ledger.append(model_proposed,{tool:read_file,path:price.py})print(fevents2 next_seq{ledger.next_seq}path{ledger.path})return0if__name____main__:raiseSystemExit(main())运行输出events2 next_seq3 pathruns/demo-001/events.jsonl二、为什么选择 JSONL 而不是一个大 JSON一个大数组只有在任务结束时才能完整关闭进程中断时尾部括号可能缺失整个文件无法解析。JSONL 每行是独立记录已经同步的前缀仍然有效。它还允许流式读取不必把长任务全部装进内存。代价是跨事件约束需要读取器自己检查因此我们必须验证序号连续、任务编号一致、每行都能解析。记住一句不太直觉的话时间戳用于观察序号才用于证明先后。如果把时间当顺序NTP 校时或虚拟机暂停恢复会让事件“穿越”如果只相信文件行号手工拼接文件又可能隐藏缺口。显式seq让缺失和重复都可检测。importjsonfrompathlibimportPathdefload_events(path:Path)-list[dict]:events[]withpath.open(encodingutf-8)ashandle:forline_no,lineinenumerate(handle,start1):try:eventjson.loads(line)exceptjson.JSONDecodeErrorasexc:raiseValueError(fbroken json at line{line_no})fromexc expectedlen(events)1ifevent[seq]!expected:raiseValueError(fexpected seq{expected}, got{event[seq]})events.append(event)returnevents eventsload_events(Path(runs/demo-001/events.jsonl))print([event[kind]foreventinevents])运行输出[run_started, model_proposed]三、追加式不等于绝对不可篡改文件以追加模式打开只能防止业务代码无意覆盖不能防止拥有同一文件权限的进程重写历史。后续会加入摘要链和只读裁判此时先把所有状态变化变成事件避免“内存里已经重试三次磁盘只看到最终成功”的选择性记忆。异常也必须写事件工具超时、权限拒绝和预算耗尽不是日志噪声而是任务结论的一部分。另一个坑是把完整提示词、令牌或客户源码直接塞进账本。审计需要的是可验证引用不一定是原文。可保存内容摘要、相对路径和脱敏片段把敏感正文留在权限更严格的工件目录。账本越完整泄漏后的影响也越大所以可审计与最小披露必须一起设计。四、首篇交付什么本篇产物是ledger.py和runs/demo-001/events.jsonl。验收不是看终端出现两行文字而是重新启动程序后序号从 3 继续读取器能发现截断行与跳号两个任务不会写进同一目录。下一篇将直接读取这份事件文件中的model_proposed用tools.json判断read_file是否被授权并把允许或拒绝结果继续追加到同一账本。参考来源Dev.toThe Dirty Secret Behind AI AgentsPython 文档json — JSON encoder and decoder 觉得有用就点个赞 收藏方便回头查阅有疑问直接在评论区留言我看到都会回。 本文属于《Agent可靠性工程实战》系列持续更新关注不迷路。 文章里的代码都能直接跑。想要可直接 clone 的完整工程 配套部署脚本 / 踩坑清单评论一声或发邮件到cj2664qq.com我免费发你。如果你正好在做类似系统、或有工程化难题想找人做也欢迎邮件聊一句——我按实际情况评估能落地的就接单或出方案。评论和邮件都能直接找到我不用跳别的平台。