做 Agent 框架工程化我最大的体会是模型的能力边界一半在权重里另一半在“它到底能触达什么样的环境”里。我最近在持续打磨一套开源推理模型配套的 Harness 评估框架它要解决的核心问题是评估一个会动手的编码类 Agent 时最容易翻车的三个环节——过程不可见、结果不可复现、行为不可审计。整套设计就两根柱子工具能力全部插件化会话过程完整落盘成可回放的日志。这篇文章把这两根柱子的设计逻辑、实现细节以及我在实际接入中踩过的坑都拆开讲一遍。适合三类人看正在搭 Agent 评测系统的后端工程师、研究 Agent 可观测性的人以及想理解大模型应用怎么工程化落地的读者。1. 整体设计思路拆解为什么 Harness 非做不可1.1 一个会动手的模型靠什么来评估传统 NLP 评测是“输入-输出”式的给模型一段文本拿它与标准答案比对算准确率、算 F1。但编码类 Agent 完全不是这个玩法。给它一个仓库、一个 issue、一个初始 commit它要自己去读代码、定位缺陷、改动文件、执行测试、观察输出、再迭代修改。整个过程是多轮长链路、带环境状态的最终能不能通过测试只反映结果的一部分更关键的是过程——它在哪一步跑偏了、为什么反复修改同一个文件、是不是在靠暴力尝试碰运气这些都要有据可查。这决定了 Harness 不能只是“一个发请求拿结果的客户端”它必须同时具备三个能力。第一提供一个真实、可控、可隔离的执行环境让模型想干嘛就干嘛但干坏事了不会伤到宿主机和其他任务第二把模型的“动手动作”抽象成一组稳定、可枚举、带 schema 的工具接口让模型是通过 API 而不是靠碰运气的方式操作环境第三把每一次观测、思考、调用、结果全部记录下来形成一条可以被事后重放的完整轨迹。这三个需求正好对应 Harness 的三大模块沙箱环境、工具插件、会话日志。我之所以在设计时把这三大模块分开是因为它们各自的演进节奏完全不同——环境镜像更新频繁插件列表随评估任务变化日志格式则要尽量保持稳定。1.2 插件化不是“为了优雅”而是为了活下来刚开始做工具接入时我踩过一个经典的坑直接在核心引擎里写死工具调用。今天要加一个“执行 Python 脚本”就往引擎里塞一个函数明天要加“读文件”再塞一个。看起来很快但三个评估任务之后引擎代码就变成了一锅粥。工具的入参校验、错误处理、超时控制、日志记录全都耦合在一起改一个工具十几个地方跟着改。后来我把工具全部插件化思路其实非常简单就像家里的电源插座——墙上的接口是固定的你插什么电器都行但每个电器的内部实现完全独立。插件化之后核心引擎只认一个稳定的接口插件名、参数 schema、执行入口、返回结果。剩下的事全部交给插件自己处理。模型侧只看到一份工具清单名称、描述、参数定义框架侧只维护一个插件注册表新增能力就是写一个插件类然后注册删除能力就是注销一行。这样做最大的收益不是“代码好看”而是评估任务的可组合性——同一个 Harness 可以同时承载代码修复、数据爬取、系统运维三种完全不同的 Agent 任务只需要在配置里挂不同的插件集合。1.3 会话日志评测链路的黑匣子飞机有黑匣子Agent 评测也需要自己的黑匣子。真实评测中我遇到过太多“看起来失败了但不知道死在哪”的情况模型输出了一段错误的 JSON工具调用抛了个异常沙箱环境重置后复现不出来……如果没有完整日志排查全靠猜。会话日志要承担三个角色。第一是复现依据同一个任务、同一个初始状态、同一份日志应该能重建出几乎一致的执行过程第二是审计凭证评测结果要公平就必须能回答“Agent 当时确实执行过这些命令、看到过这些输出”日志就是证据第三是调优素材模型走偏的每一帧、工具报错的每一条信息都是 Prompt 和工具设计的改进依据。我见过不少团队在评测时只存“最终结果”省空间是省了但出了问题两眼一抹黑。会话日志这件事千万不能省。2. 核心架构与插件机制详解2.1 工具插件把模型的“念头”翻译成环境动作模型通过工具调用与外部世界交互这在今天已经是标准范式。Harness 要做的是把这个范式工程化模型输出一个结构化动作比如“执行命令 ls -la”框架负责解析、路由、执行、回收结果然后原样返回给模型。插件就是这个链条上的执行单元。一个工具插件我建议最少由四个部分组成。名字唯一且语义清晰描述说明工具在什么场景下用、有哪些注意事项这直接决定模型会不会乱用参数 schema用 JSON Schema 描述入参结构和约束框架在路由前先做校验执行函数接收解析好的参数和执行上下文返回结构化的结果。下面是最小实现class ToolPlugin: name description parameters {} # JSON Schema def execute(self, params: dict, ctx: ExecContext) - ToolResult: raise NotImplementedError注册表负责收集和管理插件同时对外暴露两份数据一份给模型看工具清单一份给引擎用路由表。class PluginRegistry: def __init__(self): self._plugins {} def register(self, plugin: ToolPlugin): self._plugins[plugin.name] plugin def tool_schemas(self): return [{ name: p.name, description: p.description, parameters: p.parameters } for p in self._plugins.values()] def invoke(self, name: str, params: dict, ctx: ExecContext): plugin self._plugins[name] return plugin.execute(params, ctx)这里有一个我在实战中反复强调的点插件执行函数里一定要做超时控制和输出截断不是每个工具都能在规定步数内正常返回的。一个卡住的命令如果不 kill整条评测链路都会跟着卡死一个几 MB 的命令输出如果不截断模型下一个回合的上下文窗口可能直接被撑爆。插件是面向“模型”的但它的背面是真实操作系统一切按生产标准来写。2.2 沙箱执行环境给每个 Agent 一间隔离的工作间插件负责“动作”沙箱负责“场所”。刚开始我试过让 Agent 直接在宿主机上跑命令后果可以想象一次误写的删除命令就足以让整个评测环境瘫痪。后来我改用容器化方案每个任务独立启动一个容器里面装好代码仓库、依赖库、评测工具。容器镜像只读、可复现、随建随拆宿主机安全任务之间互不干扰。沙箱设计有几个细节值得展开。一是镜像要提前构建不能等评测开始时在线装依赖否则网络抖动一次整个评测队列全废二是资源配额必须显式声明内存、CPU、磁盘、超时时间都要在任务配置里写清楚防止一个失控 Agent 拖垮同节点的其他任务三是网络策略要按需开放大多数编码类任务不需要公网把外网关闭能避免模型“跑出去”下载一些不可控的东西也可以大幅提升评测安全性。我见过不少框架为了省事让沙箱随用随连公网结果评测结果根本不可复现——同一个任务昨天能跑通今天依赖一更新就挂了这种教训一次就够。2.3 执行引擎与并发调度的取舍引擎是 Harness 的中枢它做的事情可以概括成四步循环取模型输出解析出工具调用交给插件执行把结果连同观测状态写回日志。这个循环本身不复杂复杂的是并发和调度。小规模调试时串行执行最稳一个任务跑完再跑下一个日志顺序清晰问题好定位。但到了需要几百个任务同时评估的场景串行就撑不住了得让沙箱承担并行任务的单元。实操中我采用的方案是把每个沙箱封装成独立的执行服务通过 HTTP 接口对外提供工具调用能力。这样并行调度层我用的是容器编排平台的任务队列只负责“把任务塞给某个沙箱”不关心 Agent 内部状态Agent 控制器只管跟沙箱的 API 通信。所有交互都走接口日志自然也在接口层统一收集这比在每个 Agent 内部单独埋点要可靠得多。这里要提醒一个容易踩的坑并行度不是越高越好。评测任务通常都有资源上限沙箱数量开得太多反而会因为 CPU 争抢导致工具执行变慢、超时频发最后评测结果里混进大量“非模型因素”的噪声。我一般在单机上先把资源基准测一遍再按“每个任务独享配额”倒推并行度。3. 可回放会话日志的工程实现3.1 日志要记录到“每一帧”什么叫“可回放”不是把模型说的话记下来就完了而是要把一次会话里所有能影响后续决策的信息都记下来。我自己最终落地的日志是一个按事件追加的 JSON 文件每个事件有全局递增的序号、类型、时间戳和载荷。事件类型至少包括任务元信息、模型输出、工具调用请求、工具执行结果、环境状态变更、异常事件。{ session_id: task-001, task: { repo: some-repo, base_commit: a1b2c3, prompt: 修复登录接口的越权问题 }, events: [ { step: 1, type: model_output, content: 我先看一下项目结构..., ts: 1710000000.123 }, { step: 2, type: tool_call, tool: bash, params: {command: find . -type f -name *.py | head -50}, ts: 1710000000.150 }, { step: 3, type: tool_result, exit_code: 0, stdout: src/auth.py\nsrc/server.py\n..., stderr: , duration_ms: 42, ts: 1710000000.192 } ] }还有一个细节很重要文件快照。Agent 改过哪些文件、改了什么内容是编码类评测里最关键的证据。我的做法是在每个工具调用回合之间对工作目录做一次增量变更记录如果条件允许还会把改动前的文件内容一起存下来作为附件放在对应事件里。这样回放时不仅能看它说了什么、做了什么还能精确看到它对代码库产生了什么影响。3.2 回放功能的三个层次日志存下来了回放才有意义。我把回放分成三个层次由浅入深。第一个层次是文本回放把 JSON 日志渲染成一份类似聊天记录的 Markdown 或 HTML 文档。模型每一步说了什么、调用了什么工具、工具返回了什么按时间顺序一字排开。这个层次主要服务于人的快速阅读——评测完了先扫一眼大概就知道 Agent 的节奏对不对。第二个层次是状态回放把某一步时刻的完整环境状态还原出来。比如日志里记录了第 12 步之前的文件快照我就可以把工作目录恢复到那一刻手动执行查看、修改、调试相当于“回到过去”检查现场。这个层次对疑难问题定位非常有用因为很多问题只有在特定上下文里才能复现。第三个层次是指标回放从日志里自动抽取结构化指标比如总步数、工具调用次数、各工具耗时分布、异常事件数、首次成功修改文件的步数。这些指标可以批量喂给报告系统做任务级或模型级的横向对比。三个层次的实现成本是递增的但收益也递增。小团队如果时间紧张我建议至少把第一和第三层次做扎实文本回放用于人工排查指标抽取用于自动评估。3.3 回放一致性的三个关键细节保证“回放出来跟原跑一致”比想象中难。我整理出三个最容易出问题的环节。第一事件顺序必须全局单调。不同来源的日志比如模型输出来自网络回调、工具结果来自沙箱进程可能因为异步到达而乱序。我最后的处理办法是统一的中心化日志写入所有事件在写入时分配全局递增序号禁止各模块自行落盘后再合并排序。第二输出必须“完整捕获”而不是“参考捕获”。工具执行结果如果被截断日志里存的应该同时包含截断后的展示内容和指向完整内容的附件路径绝不能只存截断后的片段否则回放时模型看到的上下文和真实情况对不上。第三有状态的操作要记录副作用。比如某个命令悄悄修改了一个系统配置文件、某个环境变量被导出、某个后台进程被启动——这些不会直接出现在工具返回里但会影响后续回合。我的做法是在一个工具调用结束后主动做一次“状态指纹”采集记录关键文件的哈希和进程列表作为事件的附属字段。4. 实操从零搭建可复现的最小 Harness4.1 最小插件注册器与 Bash 工具实现纸上谈兵不如直接动手。我下面给一个最小可跑的 Harness 核心不依赖任何重框架用标准库就能跑通。先看插件侧import subprocess class BashPlugin: name bash description 在沙箱内执行一条 shell 命令 parameters { type: object, properties: { command: { type: string, description: 要执行的完整命令 } }, required: [command] } def __init__(self, timeout10, max_output_bytes8192): self.timeout timeout self.max_output_bytes max_output_bytes def execute(self, params, ctx): result subprocess.run( params[command], shellTrue, capture_outputTrue, textTrue, timeoutself.timeout, ) return { exit_code: result.returncode, stdout: result.stdout[:self.max_output_bytes], stderr: result.stderr[:self.max_output_bytes], }注意 execute 里我加了两个默认参数timeout 和 max_output_bytes。这两个看起来不起眼实战里救命的次数最多——没有超时一个 sleep 命令就能挂死整个评测任务没有截断一次全文输出就能让日志文件膨胀到几 MB。文件读写插件我平时单独拆一个不并进 bash 里主要原因是权限边界不同bash 理论上能碰所有文件文件插件则应限制在任务工作目录内。这种“最小权限”的插件划分既方便审计也避免模型用一招鲜的工具干所有事。4.2 会话日志落盘与 Markdown 回放实现日志模块我给一个足够简单但能用的版本import json import time import os class SessionLogger: def __init__(self, session_id, output_dirtraces): self.session_id session_id self.path os.path.join(output_dir, f{session_id}.json) self.events [] os.makedirs(output_dir, exist_okTrue) def log(self, etype, payload, stepNone): event { step: step if step else len(self.events) 1, type: etype, payload: payload, ts: time.time(), } self.events.append(event) with open(self.path, w, encodingutf-8) as f: json.dump({session_id: self.session_id, events: self.events}, f, ensure_asciiFalse, indent2)这里有一个我踩过坑后的心得每次写入都全量 dump 而不是增量 append看起来效率低但换来的是日志文件永不损坏——进程中途崩溃时文件里始终是“上一次完整状态”解析不会因为半行 JSON 而挂掉。评测任务本身频率不高这点开销完全可以接受。回放渲染也很直接遍历 events 按类型拼 Markdowndef render_markdown(log_path): with open(log_path, encodingutf-8) as f: data json.load(f) lines [f# Session {data[session_id]}] for ev in data[events]: if ev[type] model_output: lines.append(f#### 模型step {ev[step]}\n\n{ev[payload][content]}) elif ev[type] tool_call: lines.append(f#### 调用 {ev[payload][tool]}step {ev[step]}\n\nbash\n{ev[payload][params].get(command, )}\n) elif ev[type] tool_result: lines.append(f**返回码** {ev[payload][exit_code]}\n\n\n{ev[payload][stdout]}\n) return \n\n.join(lines)这个生成逻辑很简单但足够让一个评测结果变成可读的图文报告。要接 HTML 模板、加时间轴、加 diff 视图都是在这个基础上扩展。4.3 完整接入一个 Agent 的流程与配置把上面的模块串起来跑一次完整评测的流程大概是准备沙箱镜像。基于容器引擎基础镜像安装好评测仓库和依赖保存为固定标签。启动沙箱服务。把仓库挂载进去启动执行服务的 HTTP 端口记录访问地址。写任务配置。用 YAML 声明模型接口、插件列表、步数上限、最大 token、日志目录。运行评测主循环。控制器把任务 prompt 发给模型解析模型返回若含工具调用就走注册表 invoke结果写日志并拼回模型上下文到达最大步数或模型认为任务完成则结束。生成回放报告。调用 render_markdown 输出供人审阅。一个最小配置大概是task: repo: sample-repo base_commit: a1b2c3 prompt: 修复登录接口的越权问题 agent: model_endpoint: http://localhost:8000/v1 max_steps: 30 sandbox: image: eval-base:v1 memory_limit: 4g network: offline plugins: - bash - file_read - file_write logs: output_dir: traces这套流程跑通之后你会发现一个很大的红利因为日志是全量可回放的评测的“审查”环节变成了纯纯地读文件不再需要任何人在线盯场。谁在什么时间做了什么、模型看到什么输出才做了决定全部可追溯。这个能力对团队协作和结果复现都非常关键。5. 常见问题排查与避坑记录5.1 高频问题速查表实操里最常踩的问题我整理成一个速查表方便对照排查问题现象可能原因排查与解决思路沙箱内执行命令超时任务依赖网络下载或命令本身阻塞预构建镜像缓存依赖给命令显式超时并 kill 进程日志文件迅速膨胀工具输出没有截断或回放反复写全量 JSON在插件层加输出上限日志每 N 次事件压缩一次回放结果与原跑不一致存在非确定性操作随机数、时间、外部请求记录环境变量、随机种子、系统时间禁用公网依赖多个任务互相干扰共享了挂载目录或同一套临时文件路径每个任务独立命名空间和工作目录禁止共享写路径模型反复调用同一工具工具描述不清晰或返回结果让模型误解检查工具 description补充使用场景和失败示例还有一些比较隐蔽的插件注册顺序影响工具清单展示顺序进而可能影响模型的选择倾向JSON Schema 里忘了写 required模型就会理直气壮地少传参数工具返回的 stderr 被吞掉模型完全看不到报错会一直原地打转。5.2 三个值得展开的坑第一个坑日志“看起来完整”但没法精确回放。我早期用事件轮询拉取模型输出网络抖动时事件会乱序导致回放时模型“先说后想”逻辑对不上。后来痛定思痛改成在 Harness 进程内做单点写入先入先出永不在各子模块本地缓存日志。这个改动让回放可信度大幅提升。第二个坑为了省空间截断工具输出。截断本身没错错的是只截断不保留全量。有一次排查一个分析型任务Agent 明明输出了完整分析却判断失误结果一查日志工具返回被前端截断到 2KB模型根本没有看到完整数据。从那以后我规定日志层永远保留完整输出的附件或哈希展示层才截断。数据可以按需删但证据链不能断。第三个坑并发评测时资源争抢。起初我把并行度拉到机器核心数的两倍结果工具执行时间翻倍、超时率暴涨评测分数被污染。后来改成先压测基准单个任务独占 2 核 4G 内存时平均工具延迟是多少再按 80% 资源水位倒推最大并行度。评测环境要的是“稳定”而不是“榨干”这个观念得摆正。我把这套东西从最初的“写死工具的脚本”一路改到现在的全插件化加可回放日志最直接的感受是框架的复杂度并没有消失而是被转移到了更可控的地方——从“散落在引擎各处的分支逻辑”转移到了“一个个独立插件和一份份结构化日志”里。如果你也在搭 Agent 评测我建议先别追求功能多先把“工具插件化”和“会话可回放”这两根柱子立起来其他能力都是在这两根柱子上长出来的。最后再分享一个小技巧每次改完框架都拿一个历史任务的日志做一遍回放对比关键事件是否一致——这个动作我坚持了很久替我挡掉过至少三次让全量评测结果失真的回归。