过去三个月我和团队被同一个问题反复折腾Agent在demo里很聪明一上真实任务就掉链子。丢上下文、工具超时、进程崩溃、API抖动任何一个意外都能让一个运行了二十分钟的任务一夜回到解放前。于是我把目光从模型排名榜移开开始认真研究另一个东西——Harness。看完Anthropic在长时任务上的设计又研究了一圈Google AX的声明式调度我越来越确信Agent的下一场竞争不在模型智商而在工程底盘。这篇文章聊聊我对Harness工程的理解以及一路踩过来的一些坑。1. Harness 是 Agent 的“底盘”不是“外壳”先搞清楚我们在讨论什么1.1 从模型到 Agent 的跨度为什么单纯堆上下文不够模型本身的任务很简单接收一段文本生成一段文本。但Agent任务完全不是一回事。你让一个Agent去调研竞品、查数据库、生成图表、发到内部系统整个过程持续两三个小时期间要调用几十次工具这个任务就算“跑起来了”。关键差异就在这里模型对话是短连接Agent任务却是长链路。每一次模型输出“我想调用工具A”你的系统就得真的去执行工具A把结果喂回去它再决定下一步。这几十步链路里任何一环出错——工具超时、进程被杀、API返回429、上下文塞满——整个任务就可能报废。有人觉得上下文窗口大了就能解决问题把1M token全塞进去结果延迟和成本双双爆炸。而且工具返回的结果往往又长又糙如果只是无脑堆积在上下文里Agent很快就会“迷失重点”开始胡言乱语。单纯堆上下文只是在用算力掩盖架构上的懒惰。Agent需要的是一个能替它管理上下文、执行工具、保存进度、处理异常的工程层这个层就是Harness。1.2 三个层次连接、状态、治理我对Harness的理解不是某个具体框架或某件工具而是模型核心之外的那整套工程底座。它大致分三层。第一层是连接与执行层。负责模型API的接入、密钥管理、多模型路由、工具注册以及沙箱内的实际执行。这一层回答的问题是模型说要调用工具谁来跑跑在哪权限是什么第二层是状态与恢复层。负责会话状态持久化、checkpoint、断点续跑、上下文摘要。这一层回答的问题是任务跑到一半挂了还能不能从最近的位置接着跑第三层是治理与观测层。负责工具白名单、敏感操作审批、成本预算、审计日志、任务轨迹回放。这一层回答的问题是这个Agent到底干了什么有没有越权花了多少钱这三层合在一起才是Agent真正可交付、可运维、敢放到业务环境里去跑的形态。只调模型API那不叫Agent工程那叫脚本。1.3 Agent框架和Harness不是一回事现在市面上有很多Agent框架LangGraph、Semantic Kernel甚至一些国产的编排框架。很多人会把框架当成Harness这是个误区。Agent框架解决的是“任务怎么定义”的问题比如节点、边、状态图、流转逻辑。而Harness解决的是“任务挂了怎么办、工具怎么安全执行、状态怎么保存”的运行时问题。框架是代码层的东西Harness是运行时底座。你可以用了很高级的框架却完全没有Harness也可以自己手写一个很朴素的Harness不依赖任何框架。我用一个表格来对比这两者的关注点维度Agent框架Harness工程核心问题任务流程怎么编排任务怎么稳定可靠地跑完关注点图结构、节点、数据流沙箱、checkpoint、重试、审计失败时表现告诉你任务失败了自动恢复、降级、可排查主要资产可复用的代码逻辑运行数据、恢复机制、治理策略护城河恰恰在后者。因为框架是开源的可选替代品而Harness是你自己的工程实践指的是你踩过多少坑、沉淀了多少恢复逻辑、积累了多少真实的运行轨迹。2. Anthropic 长时任务设计里最值得抄的三个作业2.1 长时任务不是把超时调大中断恢复才是核心Anthropic近两年的产品迭代里有一个明显趋势把Claude从短对话助手推向长时任务执行者。Claude Code的会话恢复、云端任务的断点续跑都在解决同一个问题——让Agent任务可以运行几十分钟甚至几小时而不中途夭折。我见过很多团队面对长时任务时的第一反应把HTTP超时从30秒调到300秒把重试次数从3次改成10次。看起来是“为长时间运行做了优化”实际上只是让失败变得更昂贵。超时调大后每次失败都要等更久重试调多后同一个错误会砸好几遍白白烧token。真正长时任务的设计哲学是“随时可中断、中断可恢复”。我常拿电梯做类比短任务像电梯正常上行长任务设计则要求电梯即使停电也得有应急电源和手动盘车把人安全放到最近楼层而不是让人困在轿厢里等救援。具体到Agent这意味着三个方面每个工具调用都要被记录在案、每个关键步骤都要有检查点、每个动作都要有幂等设计。只有这三件事做好了任务中断才真正“不可怕”。2.2 Agent需要持久化什么四个必须保存的东西设计checkpoint的时候最容易犯的错是“过度持久化”——把整个上下文原封不动存下来恢复时候全文加载。这样既慢又贵而且上下文里塞满了中间过程的无用信息。按我这段时间的实践Agent真正需要持久化的东西只有四类。第一类是对话历史的摘要加关键原文。完整历史不可能长期留着要在每轮做完后用模型做一次摘要压缩同时保留最近几轮的原文保证Agent的短期记忆是准确的。第二类是执行轨迹。也就是它调用过哪些工具、传了什么参数、返回了什么结果、每个动作的时间戳。这既是恢复的依据也是事后审计的线索。第三类是中间产物。Agent生成的代码、处理过的临时文件、计算结果缓存这些要落到对象存储或者本地目录并且按任务ID组织不能被其他任务污染。第四类是执行位置。当前Agent推进到任务的第几个节点、子任务栈是什么、还有哪些待办。这四类状态不一定都要放数据库。小任务一个JSON文件就够中等并发用Redis大规模、长链路再用对象存储加向量库。核心原则是分层热状态在内存温状态在Redis冷状态在对象存储。2.3 工具调用治理从 Claude Code 的实战思路说起社区里流传的那本《Claude Code实战 Harness工程之道》很多人只把它当工具教程看我却觉得里面最有价值的部分是工具治理思路。Claude Code本质上是一个CLI形式的Agent而它自带的那套执行机制就是一套Harness参考实现。它做到了几件事第一工具注册表是显式的它知道自己能用Read、Edit、Bash等哪几个工具第二敏感操作有审批很多写操作默认要人工确认第三执行在本地沙箱里不是让模型直接裸跑命令第四会话支持resume断线后能恢复。我从里面提炼出一个工具调用的四原则工具要有清晰的Schema输入输出明确模型才不会乱传参数。调用要有超时与重试策略但重试要区分错误类型4xx别傻重试5xx才值得重试。返回结果要校验工具返回异常时要有机制让Agent感知并纠正而不是硬着头皮继续。写操作、删除操作、高权限操作必须有审批流不能把所有工具都设成自动放行。这一点我是真吃过亏的。之前让Agent自动跑SQL它为了凑一张报表里的某个数字顺手把一个测试订单记录删掉了。事后我加了一道审批流所有写操作必须人工确认才允许执行。从那以后凡是涉及删除、写入、转账、发布的工具我一律默认加审批不商量。3. Google AX 的声明式调度把 Agent 的决定权上收3.1 命令式循环的问题谁来决定下一步如果不用Harness不用调度器自己裸写一个Agent通常会长这个样子while not task_completed: action model.decide(state) result execute(action) state.update(result)这个命令式循环看起来很简洁但放到真实业务里你会立刻发现几个致命问题。第一没有控制点。模型说下一步要执行什么系统就只能跟着执行开发者和运维者完全插不上手。想在某一步加个审批你只能改模型提示词让它“尽量”在危险操作前停下来——这根本不叫控制。第二没有恢复点。任务跑到第18步崩溃了整个循环从头再来前面17步的工具调用全部白做。你甚至说不清楚它到底跑到哪一步了。第三没有预算限额。Agent可能在一个错误分支上反复打转token烧完才发现路径根本不对。命令式循环对这种浪费没有约束力。命令式循环适合demo不适合生产。生产环境需要的是把“下一步做什么”的决定权从模型手里部分上收交给一个更可控、更可观测的执行体系。3.2 声明式任务怎么描述一个调度配置长什么样Google AX这类声明式调度体系我不好说它的每个内部实现细节但从它对外传达的“声明式调度”思路来看核心做法是一致且有借鉴价值的把任务依赖、重试、超时、并发、审批要求全部写成配置调度器负责按配置执行而不是让Agent自己在每一轮自由发挥。一个声明式任务配置大概长这样tasks: - id: research tool: web_search timeout: 30s retry: max_retries: 3 backoff: exponential depends_on: [] output: research_summary - id: summarize tool: llm_call timeout: 60s max_retries: 2 depends_on: - research input: research_summary - id: report tool: generate_doc depends_on: - summarize requires_approval: true声明式的核心好处是任务之间的依赖关系是显式的执行顺序和重试策略是提前声明的单步失败后调度器可以在节点粒度重试而不是整个任务重来。你可以明显感受到这和Kubernetes处理容器是一脉相承的思路。容器不关心自己被调度到哪台机器K8s根据声明状态不断调谐。Agent任务也一样——它不该自己决定全局调度它应该被一个控制面管理它只负责在自己被分配到的那个节点范围内干活。这是工程上的一次权力上收。模型仍然决定“这一步怎么做”但“整个任务怎么组织、哪步能并行、哪步要审批、失败了怎么办”由声明式调度层说了算。3.3 Harness做运行时声明式调度做控制面如果你问我是该先搞Harness还是先搞声明式调度我的答案是它俩是搭档不是二选一。Harness管的是“怎么跑”负责沙箱、工具执行、状态持久化、安全。声明式调度管的是“跑什么、什么时候跑、失败了怎么办”负责依赖编排、重试策略、并发控制、预算。两者角色完全不同。层次Harness运行时声明式调度控制面管什么工具执行、沙箱、状态任务依赖、重试、并发、预算回答的问题这一步怎么执行整个任务怎么组织失败时提供恢复状态决定是否重试、降级关键指标单步成功率、恢复耗时任务完成率、SLA达成率这套组合拳才是Agent工程新范式的完整形态。先让单步执行可靠再用调度层把整个任务组织可靠。缺了任何一环长时任务都跑不稳。4. 从零搭一套带 Harness 的 Agent四层架构与真实接线4.1 最小可用 Harness 的四层骨架我在团队内部搭过一版最小可用的Harness当时的原则是别一上来就上K8s、上向量库、上微服务先跑通再加复杂度。那版Harness一共四层。连接层做模型API适配统一成OpenAI兼容的Chat Completions接口格式同时处理多密钥轮换、429限流重试、按任务类型做模型路由。任务简单就上便宜模型任务难就切贵模型。执行层所有工具调用不进宿主进程统一丢到Docker沙箱里执行。内置工具包括shell命令、文件读写、代码解释器、HTTP请求。每个工具都有明确的超时时间超过就直接砍掉把超时错误返回给模型。状态层checkpoint写入Redis以session_id加步骤号作为键。每次工具调用完成就把最新消息序列和摘要写进去。恢复的时候读取最近的checkpoint从那里继续。治理层工具白名单、单任务成本上限、敏感操作审批、完整审计日志。审计日志记录每一次工具调用的输入输出、耗时、费用方便事后排查。这个四层骨架很朴素但足够支撑大多数真实业务场景。很多Agent项目死就死在第一版就想做全套最后连demo都跑不通。4.2 把 Claude、DeepSeek 这类模型接进 Harness 的接线方式很多人以为Harness绑死了某个模型其实不是。市面上主流模型API大多兼容OpenAI的Chat Completions格式虽然Anthropic原生API格式和OpenAI不完全一致但通过网关适配层可以统一成OpenAI兼容协议。社区里那个DSHDeepSeek Harness工作流本质上就是把DeepSeek接进Harness的一套实践。接线方式其实不复杂。第一步注册工具清单每个工具都写清楚JSON Schema描述参数、返回值、用途。第二步组装系统提示词把任务目标和工具列表给到模型。第三步进入循环模型返回tool_calls时Harness去执行对应工具把结果回填消息列表。第四步每步执行完就写checkpoint。核心代码骨架大概是这个意思import json class MinimalHarness: def __init__(self, model_client, model_name): self.client model_client self.model_name model_name self.tools {} def register(self, name, schema, fn): self.tools[name] {schema: schema, fn: fn} def _tool_defs(self): return [{type: function, function: t[schema]} for t in self.tools.values()] def run(self, session_id, task): messages [{role: system, content: task}] while True: resp self.client.chat.completions.create( modelself.model_name, messagesmessages, toolsself._tool_defs(), ) msg resp.choices[0].message messages.append(msg) if not msg.tool_calls: break for tc in msg.tool_calls: fn self.tools[tc.function.name][fn] result fn(**json.loads(tc.function.arguments)) messages.append({ role: tool, tool_call_id: tc.id, content: json.dumps(result)[:2000], }) self._checkpoint(session_id, messages) return messages[-1].content这段代码只是骨架生产环境必须补上几件事沙箱执行不能让工具函数直接跑在Harness进程里、工具返回要截断防止上下文爆炸、重试时要区分错误类型、写敏感操作前要挂审批。跑通这个骨架后再去接沙箱和调度器心里就不慌了。4.3 并发问题Agent 扛并发核心是状态隔离很多人一聊到Agent并发第一反应是加线程池、加异步、上消息队列。但Agent任务和普通Web请求有一个本质差别每个任务有独立的长期状态、独立的工具副作用、独立的上下文成本。你没法像处理无状态HTTP请求那样随便把请求分发到任何一台机器。Agent任务一旦开始它的状态就和特定的session绑定换一台机器或者换个进程状态就丢了。所以并发问题的第一原则是会话隔离。每个任务一个session_id状态存储按session分片。我踩过最典型的坑就是用全局Redis List存所有任务的checkpoint任务一多恢复的时候互相覆盖最后全乱套。改成session_id哈希分片后问题立刻消失。第二是沙箱隔离。并发任务绝不能在同一个文件系统或者同一个进程中执行工具调用一个任务删除临时文件另一个任务可能就被拖累。每个任务单独起一个沙箱容器是基本要求。第三是API限流。模型API的并发数是有上限的Harness要用令牌桶控制并发不然一堆任务同时打模型API全被限流等于没有并发。第三是checkpoint写入的并发控制。不同任务写自己的分片永远不要用一个全局锁全局锁会在高并发下变成性能瓶颈。Agent扛并发从来不是加几个线程的事而是状态、资源、API三个层面的隔离和限流。5. Harness 常见故障实录插件、网关、内网一个比一个坑5.1 插件加载失败harness failed to load plugins 的排查路径社区里最常见的Harness报错之一就是harness failed to load plugins。我第一次遇到时一脸懵后来顺手还见过更细的变体比如web boot: 1 entry did not activate。这种报错看着吓人本质其实是某个插件没能成功启动。排查路径我总结成三步。第一步看是不是依赖冲突。两个插件如果依赖了同一个库的不同版本启动时很容易加载失败。解决办法是锁版本把插件依赖统一到同一套版本上。第二步查工作目录。Harness经常用相对路径去加载插件目录如果你换了启动目录、换了工作路径插件就会找不到。检查启动日志里打印的路径和插件实际位置对不对得上。第三步做二分禁用。那句“1 entry did not activate”其实是个线索——不是所有插件挂掉而是某一个入口没有激活。先把插件全部禁用然后一批批加回来定位到具体是哪个插件再单独看它的依赖。这个坑给我的教训是别一次性加载所有插件。先最小集跑通再逐个加。凡是插件系统出问题二分法永远比瞎猜快。5.2 API抖动与网关路由错误从连接到模型名的双重坑长时任务最怕API抖动。你正跑着第18步上游API突然返回连接失败Harness断线整个任务泡汤。这个坑绕不开只能靠恢复机制兜底。连接失败的排查链路我是按这个顺序来的先看客户端到API服务的基础网络通不通DNS解析正不正常再用curl直接打API的健康检查端点看HTTP层是否可达第三步检查TLS握手第四步看错误码429是限流5xx是服务端故障连接超时要单独处理。重试策略必须按错误码区分。429要做退避重试5xx可以用指数退避连接超时要考虑切换备用endpoint。恢复后再从checkpoint续跑而不是从零开始。除了连接失败的坑还有一种更隐蔽的坑是网关路由错误。日志里可能出现“doesnt look like an anthropic model: expected a gateway model route”这类提示。这个问题的本质是请求里的模型名在网关路由表里不存在或者类型不匹配。比如你把Harness配置里写了一个自定义模型别名但网关端只识别官方模型名校验就直接拒绝了。这种问题在很多人那里被误判成“API挂了”但其实不是。排查办法是检查网关的路由表确认模型名是官方名称还是自定义别名两边对齐后再跑。统一模型命名是避免这个坑最有效的手段。5.3 内网部署、代码回退与沙箱更新企业里落地Harness绕不开内网。我接过一个项目要求把DeepSeek这类模型部署到内网Harness也要在离线环境跑起来。离线环境下依赖安装、插件分发、skill资源包全都成了难题。内网部署的建议是提前把依赖包、插件包、模型权重全部下载好做成内部私有制品库或者镜像仓库安装时走离线镜像方式不要让安装脚本去外网拉东西skill和工作流插件要作为版本化资源带上校验信息部署时统一分发。大型模型推理用vLLM或者Ollama起内网服务Harness只做API转发不把模型进程塞进Agent进程里。代码回退是另一个容易被忽视的点。Harness配置和Agent代码必须做版本管理checkpoint要带schema版本号。否则你回退了Harness版本老的checkpoint读不进来恢复机制直接失效。schema版本号不一致时要能把旧checkpoint迁移到新格式或者安全丢弃。沙箱镜像升级也讲究套路。镜像版本升级前先把旧版本还在运行的任务腾挪干净别让运行中的任务突然被换掉底层镜像。升级后要留一个旧镜像的备份遇到兼容性问题能立即回滚。6. 当模型越来越同质化Harness 就是那条护城河6.1 模型能力会摊平工程能力不会这两年我的一个明显感受是不同模型之间的效果差距在快速缩小。开源模型追得很猛API模型彼此打分接近你在选模型上花的心思边际收益越来越低。但你的Agent在真实业务里能不能稳定跑这个差距却非常大。同一套模型API有的团队能跑出95%的任务完成率有的团队连demo都撑不过十分钟。差别不在模型而在工程底座。护城河来自三个地方一是稳定性长时任务成功率的积累靠的是把一个个异常修复掉二是工具生态每接入一个业务系统你的Agent就多一分对业务的理解别人要重接一遍三是运行数据Agent执行轨迹是下一轮调优的最好燃料没有这些数据模型调得再强也是无根之木。6.2 接下来两三年Harness 会往哪走我判断未来两三年的演进路径会比较清晰。第一运行时的稳定性会从“加分项”变成“默认项”。没有checkpoint、没有工具幂等、没有沙箱的Agent根本不好意思拿到生产环境去说事。第二控制面会从任务编排走向多Agent协同。现在声明式调度管的是单任务流程下一步会管多个Agent之间的分工、通信、资源配额。第三可观测性会从日志走向完整轨迹回放。出了事故你能像看录像一样逐步回放Agent当时为什么调用这个工具、这个工具返回了什么、模型为什么走到错误分支。第四治理会从规则走向自动审计。模型控制工具工具行为受策略管理审计系统自动检查每一次动作是否符合预期。这套演进的核心方向只有一个让Agent从“聪明的demo”变成“可靠的劳动力”。聪明是模型给的可靠是Harness给的。6.3 用五个问题判断你的 Agent 有没有护城河如果你在评估自己的Agent工程或者评估一个Agent产品到底有没有护城河我建议直接拿这五个问题去问。第一任务跑到一半崩溃了它能自动恢复吗不是重新问一遍而是从断点接着跑。第二工具调用失败了它能自我纠错吗不是死循环重试同一个动作而是能感知失败原因、换个路径再试。第三所有执行过程都可审计吗出了事故你能指出它哪一步走错了吗第四并发跑十个任务状态会串吗每个任务有自己的完整状态不互相干扰吗第五API故障的时候它是优雅降级还是直接崩溃你有没有为断连设计过恢复路径这五个问题里只要有一个答不上来所谓“护城河”就还是空的。最后说点实在的。我在这条路上交过不少学费被Agent误操作拖累过数据库被checkpoint互相覆盖坑过整个团队被API波动毁过一整个批处理任务。但恰恰是这些事故逼着我把Harness越做越扎实——不是重得跑不动而是重到能兜住所有不该由模型负责的意外。护城河从来不在模型排行榜上而在你处理过的每一次异常、沉淀下来的每一条恢复流程里。如果你也在搭Agent我建议从今天起至少把checkpoint和工具幂等这两件事补上哪怕别的什么都不做。
