过去大半年我一直在折腾深度代理Deep Agents相关的东西团队里也堆了不少模型资源。但我越来越强烈地意识到一件事决定一个代理项目能不能真正落地的往往不是模型智商而是外围那层看不见的工程设施。工具接得稳不稳、上下文给得够不够准、状态会不会丢、出了问题能不能及时按住这些事没搞定模型再聪明也是白搭。这类“外围工程”最近在圈子里有个挺准确的叫法——Harness Engineering。这个词越来越常见不是没道理。它说的不是提示词写得多花哨也不是模型微调得多精细而是围绕深度代理构建的那整套“绳索系统”工具链接入、上下文路由、记忆管理、权限边界、可观测性与止损机制。我自己的体会是把 Harness 做扎实了代理才真正从“实验室演示”变成“生产环境里的同事”否则它永远是个情绪不稳定、随时撂挑子的实习生。这篇文章我想把 Harness Engineering 这件事好好拆一遍结合实际踩坑聊聊深度代理到底怎么通过工程化手段被改造成真正靠谱的执行体。不管你是做代码代理、客服代理还是数据分析助手这套思路都值得完整过一遍。文章会覆盖核心概念、关键设计点、代码级实现和常见问题排查尽量给到能直接“抄作业”的东西。1. Harness Engineering 到底是什么先搞懂它解决的是哪种痛很多人一上来就误解以为 Harness 就是给代理加个循环或者套一层工具调用协议。真要这么简单市面上那么多代理平台就不会翻车翻得那么整齐了。我倾向于用一句话概括Harness 是代理与外界之间的基础设施层它负责给模型配好“接收信息的传感器”和“执行动作的执行器”同时把不可控的混沌堵在核心决策圈之外。1.1 先看一种最典型的失败场景我之前在做内部知识库助手时最早的版本直接用大模型调用若干个搜索 API。模型的推理能力很强面板上看起来什么都能回答。但实际丢给业务同事用的时候问题接二连三冒出来。第一个问题是上下文污染用户问一句“上个季度的数据怎么样”代理会把整个知识库里所有跟“季度”“数据”沾边的文档全部拉进上下文导致回答时既参考了正确报表又参考了一篇过期公告最后给你交叉出一个完全错误的结论。第二个问题是工具滥用模型在连续思考时会反复调用同一个查询接口因为每次调用返回的信息都太碎它得不到全貌就一遍一遍重试钱和时间全耗在循环里了。第三个问题是越权有一次模型在调试过程中居然直接调用了删除类接口虽然当时是测试环境但那一瞬间我后背全是冷汗。这三个问题没有一个是模型能力不够造成的。根源都在于代理缺少一道严格的“出入关卡”缺少对上下文的主动管理缺少对工具调用的约束规则。而这套缺失的部分就是 Harness Engineering 要补齐的内容。1.2 “挽具”这个比喻其实非常贴切Harness 在英文里的本意是马具、安全带、降落伞背带核心作用是把动力源与负载安全地连接起来。模型就好比那个强大的动力源它有能力规划、理解、生成但它不能自己进入到外部系统里拿数据、改配置、发请求。任何人试图让模型直接握住所有工具的把手都会导致灾难。把中层连接拆解出来它要做的事情大致有四类信息接入与控制决定哪些外部数据能进入模型视野以什么方式、什么顺序、多少体量进入以及什么内容坚决不让进。动作授权与约束决定模型能调用哪些工具参数怎么校验调用结果如何回传哪些操作在什么条件下直接被拦截。状态流转与持久化在多轮复杂任务中维护内部状态让代理不会“做完这一步就忘了上一步”同时保证可恢复。观测、审计与止损记录每一步决策依据、工具调用、成本消耗并在异常时及时熔断把损失控制在最小范围。这些职责单拎出来都不算难但揉在一起、叠加模型的不确定性之后就变成了一门挺深的工程学问。圈内把专门做这件事的人叫 Harness Engineer很贴切因为这门手艺的本质不是让马跑得更快而是让马和车之间的连接更稳。1.3 模型能力与工程投入的剪刀差我做过一个粗略的统计。同样是让代理做一个“跨三张表生成月度经营分析”的任务模型从 GPT-4 级换到 GPT-5 级任务完成率大概从 40% 提到了 65%。但当我花时间把上下文结构重新设计、给工具接口加上清晰的 schema 文档、加入一轮自我检查机制之后完成率直接跳到了 90% 以上而且这里的模型底子还只是上一代。这个结果让我确定了当前阶段与其把希望全押在下一代模型身上不如把精力押在 Harness 的升级上。模型能力的提升像 CPU 升级确实有效但 Harness 的优化更像操作系统的结构优化动一下整个系统的上限都会被拉高。2. Deep Agents 的工作闭环与 Harness 的介入位置要设计好 Harness 工程必须先弄清楚深度代理的内部运转方式。业界现在提 Deep Agents指的是那种“能自主拆解任务、循环调用工具、根据中间结果不断修正计划”的代理形态。它们跟传统客服机器人的最大区别在于不是一问一答而是“感知-决策-行动-再感知”的持续闭环。2.1 深度代理的自我循环机制一次标准的深度代理执行过程大概是这样的接收用户目标通常是模糊的、口语化的指令。代理内部启动“规划模块”把大目标拆成若干子任务并为每个子任务预设需要的工具。执行第一个子任务调用工具、获取结果、把结果拼回上下文。观察结果是否符合预期如果不符合调整计划重新尝试。循环往复直到所有子任务完成汇聚成最终答案。这个循环看着简单但隐藏的变量太多了。工具返回的数据格式可能千奇百怪有的特别长有的字段缺失网络请求可能超时用户的指令可能本身就存在歧义多个子任务之间还可能存在依赖关系。代理之所以看起来“聪明”是因为模型能从这些变量里推断出下一步行动但它也极其容易在某个不正常的中间态里越走越偏。Harness 在这里的核心任务就是给循环的每一步兜底。它不取代模型做判断但它要保证模型每一步拿到的输入是可控的动作是被限制的异常能被感知并处理。2.2 介入的三个关键接缝我习惯把 Harness 的介入点归纳为三个接缝工具接缝、状态接缝、反馈接缝。工具接缝指代理与外部系统交互的那条线。这条线是 Harness 最重要的把关位。工具返回结果进上下文之前必须经过清洗、截断、摘要工具调用指令发出之前必须经过参数合法性校验、权限校验、频率控制。很多教训都发生在这一层。比如模型会臆想出一些不存在的参数或者把枚举值传成自由文本如果没有校验系统就会静默失败然后模型开始瞎猜原因整个任务就越跑越偏。状态接缝指代理自身工作记忆的维护。深度代理不是无状态的。执行到第三步时它需要记住第一步修正过的假设、第二步排除掉的方案。最简单的状态管理就是塞进上下文里但上下文长度有限且杂乱堆积的信息会降低模型决策的准确率。Harness 要做的是设计一套结构化的状态表示比如用 JSON 维护任务进度、关键决策、中间结果摘要在每次循环后更新并选择性注入到下一轮提示词中。反馈接缝指代理如何获取执行效果的好坏信息。比如代码代理跑完单元测试Harness 应该把哪些测试失败信息、日志片段、覆盖率摘要回传给模型。回传太少模型瞎猜回传太多烟雾弹满天飞。这层的核心是设计信息密度适中的反馈回路。2.3 有 Harness 与无 Harness 的对比我整理了实际对照体验放到一张表里更直观维度无 Harness 的裸代理有 Harness 的工程化代理工具接入模型直接读原始返回格式不统一统一结构化、清洗截断后注入权限控制模型可触碰全部接口风险极高白名单校验高危操作须人工复核上下文管理无限堆叠很快遇到长文本退化有裁剪、摘要、重点优先排序任务状态依赖模型临场记忆极易丢失外部持久化循环间显式同步错误处理模型自行猜测容易陷入死循环有熔断、重试策略、备用路径可观测性只能看到最终回答过程是黑盒每步留痕可回放、可审计成本控制完全失控重复调用高发有预算桶超限自动降级差距就是这么明显。说白了无 Harness 的代理是在靠模型临场发挥打天下有 Harness 的代理是用工程纪律把模型能力锁在轨道上跑。后者也许看着“限制多”但生产环境追求的本就不是自由发挥而是稳定交付。3. 搭建可靠 Harness 的四个核心工程实践知道了介入点接下来要落地。我在多个项目里反复调整之后觉得有四块内容属于 Harness 工程的地基上下文管理、工具定义与授权、状态持久化、可观测性与止损。每一项都值得单独抠细节。3.1 上下文管理决定模型“视野”的质量上下文是深度代理最重要的资源。同一件事上下文里的信息组织好了模型一针见血组织糟糕模型就会在次要信息上反复纠缠。我见过最典型的反面案例是把所有检索结果原封不动全塞进去好几万 token模型被冗余信息淹没别说回答用户问题了连做到不把名字搞混都难。我现在的做法是分层上下文管理。第一层是“核心指令最新任务状态”永远固定在最前面保证模型每轮都知道当前目标是什么、已经推进到哪里。第二层是“工具返回的高价值信息”经过摘要和去重之后注入单条信息原则上不超过 500 字。第三层是“长期记忆”包括历史决策记录和用户偏好以压缩后的条目嵌入。摘要这一步特别重要。工具返回一篇 3000 字的文档模型真正需要的关键信息可能只有一句话。我的做法是做两遍先用一个轻量模型生成结构化摘要提取关键结论和数字再让主代理仅基于摘要做后续推理。这样既省 token又能大幅降低噪声干扰。还有一个容易忽略的细节上下文边界要明显。我习惯在提示词里用清晰的 XML 标签区分指令区、工具结果区、内部思考区。模型对标签的遵从度其实很高分区之后它很少再把不同区域的内容混在一起理解。3.2 工具定义与授权边界把“不能做的事”提前讲清楚工具接入是 Harness 最硬的一道门。现在很多框架都支持工具调用但大家往往忽略一件事工具的描述写得不好模型就会用错。我见过一个例子工具名叫query_user_info描述写了“根据用户 ID 查询用户信息”但没写清楚 ID 参数是数字还是字符串结果模型每次都传字符串接口端强制转换后偶尔出 bug整个任务就卡在那里。工具定义至少要包含五要素清晰的名字、一段说明“什么时候用、什么时候不用”的描述、完整的参数 schema、默认值和边界值说明、以及典型调用示例。工具数量少的时候随便写写也能跑工具一多描述就是模型选择工具的唯一依据这块不能懒。权限控制同样要紧。我的原则是“默认拒绝白名单放行”。模型只能在预设工具集合里挑选任何超出集合的调用请求直接返回“无此权限”。在集合内部高危险操作再加一道人工确认闸门。比如设计一个删除类的工具Harness 层要拦住先把待删除的内容预览给用户等确认后再真正执行。这看着像多此一举但能救命的。注意千万不要把内部接口地址直接暴露给模型。对模型展示的工具应该是封装好的、带明确语义的业务动作而不是原始 HTTP 端点。否则模型一旦产生幻觉很容易拼出不存在的路径排查起来完全是噩梦。3.3 状态持久化让代理拥有“记事本”而不是“记忆力”纯靠模型上下文记住任务进度等于让一个人用大脑记所有事。短任务还行任务一长、步骤一多记忆就开始漂移。深度代理必须配备外部状态存储也就是“记事本”。我会为每个任务维护一个 JSON 结构字段包括任务目标、当前步骤索引、已完成动作列表、每个动作的结果摘要、当前悬而未决的问题、计划修正记录。每个循环结束时更新这个 JSON下个循环开始时把它注入提示词的状态区。这样做有两个好处一是模型不再需要凭记忆回溯二是任务中断时可以随时从状态文件恢复。状态更新要警惕“过度写入”的问题。如果每次工具返回的都原样存进状态状态文件很快会膨胀。我常常在更新状态前加一步合并摘要旧的关键信息留下来细节丢掉。这个状态摘要的过程其实质上也是模型决策质量的生命线。3.4 可观测性与止损机制让代理在“玻璃房”里干活我见过太多代理项目上线后变成黑盒用户只看到最终回答中间过程完全没有记录。一旦回答错了排查成本极高。深度代理的调试本来就难因为模型不是确定性的同样的输入两次执行可能走完全不同的路径。没有过程日志复现 bug 几乎等于大海捞针。所以 Harness 层必须做到全链路追踪。每一轮循环记录模型输入摘要、模型选择的动作、调用工具的参数与返回摘要、状态更新结果。这些日志除了用于事后排查还能做行为分析比如高频失败的工具是哪几个、哪些错误让模型反复重试。止损机制更是不容忽视。我给代理设置了三个熔断级别单步超时熔断某个工具连续失败三次直接终止当前分支切换备用方案或上报人工。成本预算熔断每个任务分配一个 token 预算池烧完就降级为简单的兜底回答不再继续循环。异常行为熔断检测到代理在短时间内高频调用同一工具、或在相似错误里循环超过三次自动暂停并触发告警。这套机制一开始做的时候觉得“太多限制了”但跑几个月下来事故率下降得很明显。代理可以自由发挥但必须在玻璃房里发挥而且玻璃房要有急停按钮。4. 代码级拆解一个最小可用的 Harness 循环光讲概念没用我直接把之前从零搭的一个最小 Harness 循环核心骨架贴出来代码做了简化但能体现关键思路。去掉外部框架的干扰用最原生的方式展示 Harness 应该管哪些事。4.1 最小 Harness 的数据模型首先定义一个任务状态结构和一个工具注册表。工具注册表是关键枢纽模型接触到的所有能力都从这里取。from dataclasses import dataclass, field from typing import Callable, Any, Dict, List, Optional import json, time, uuid dataclass class ToolSpec: name: str description: str parameters_schema: Dict[str, Any] func: Callable[..., Any] requires_confirm: bool False dataclass class TaskState: task_id: str field(default_factorylambda: uuid.uuid4().hex) goal: str step_index: int 0 completed_steps: List[Dict[str, Any]] field(default_factorylist) pending_issues: List[str] field(default_factorylist) context: Dict[str, Any] field(default_factorydict) def to_prompt_section(self) - str: # 把当前状态序列化为文本块供模型阅读 return json.dumps({ goal: self.goal, step_index: self.step_index, completed_steps: self.completed_steps[-5:], # 只保留最近几步摘要 pending_issues: self.pending_issues, }, ensure_asciiFalse, indent2)工具注册的时候就必须带好 schema。这个 schema 不只是给模型看的Harness 层在真正执行前还会拿它做参数校验双重保障。4.2 工具调用与参数校验模型会输出一个结构化的工具调用指令但外部接口不一定能信任这个伪代码。我们做的事是先解析模型输出再通过 schema 校验参数不合格就直接拦截并提示模型重新生成。import jsonschema class ToolRegistry: def __init__(self): self._tools: Dict[str, ToolSpec] {} def register(self, spec: ToolSpec): self._tools[spec.name] spec def dispatch(self, name: str, params: Dict[str, Any], need_confirm: bool False): spec self._tools.get(name) if spec is None: return {error: fUnknown tool: {name}} # 参数校验失败则返回给模型让它修正 try: jsonschema.validate(instanceparams, schemaspec.parameters_schema) except jsonschema.ValidationError as e: return {error: fParameter validation failed: {e.message}} # 高危操作需要外部确认 if spec.requires_confirm and not need_confirm: return {error: This operation requires human confirmation., confirm_required: True} # 真正执行 try: result spec.func(**params) return {result: result} except Exception as e: return {error: fTool execution error: {e}}这层 dispatch 看似简单却是整个 Harness 的咽喉要道。所有外部副作用都必须经过这里那么权限校验、审计日志、频率控制就都有了统一的落点。后续想加限流只要在 dispatch 里加个计数器即可。4.3 主循环规划、执行、反思接下来是最核心的代理循环。我会把模型调用封装成一个小函数里面包含三个环节读取当前任务状态、调用模型生成下一步行动、执行行动并更新状态。def agent_loop(model_api, registry: ToolRegistry, initial_goal: str, max_steps: int 10): state TaskState(goalinitial_goal) step_ctx state.to_prompt_section() for _ in range(max_steps): # 1. 组装上下文核心指令 状态 系统约束 messages [ {role: system, content: 你是一个工程化深度代理必须遵循工作区约束。}, {role: user, content: f当前任务状态{step_ctx}\n可用工具列表见工具描述。请输出下一步要执行的动作。} ] # 2. 调用模型 response model_api.chat(messages) action parse_action(response) # 从模型输出中提取动作指令 if action[type] finish: return {answer: action.get(answer, ), state: state} if action[type] tool_call: result registry.dispatch(action[tool], action[params]) # 3. 将执行结果浓缩后写回状态 concise_result summarize(result) state.completed_steps.append({ index: state.step_index, tool: action[tool], params: action[params], result_summary: concise_result, }) state.step_index 1 step_ctx state.to_prompt_section() # 4. 止损检测 if consecutive_failures(state, 3): return {error: Excessive consecutive failures. Need human intervention., state: state} return {error: Max steps exceeded., state: state}这里最容易被低估的是summarize这一步。很多代理项目不做结果浓缩把原始结果直接塞进去跑两轮上下文就爆炸了。我通常会用模型自身生成一个不超过百字的执行摘要包含“确认了什么信息、得到什么关键数据、下一步可选方向”。这样状态文件干净模型后续决策也精准。4.4 把我踩过的调试细节写在这里这段代码看着挺顺但我第一次跑通它花了整整两天。主要问题出在动作解析上。模型输出的动作格式不稳定有时候是 JSON有时候是自然语言夹杂 JSON有时候一个动作里包含多个工具调用。我一开始写了解析函数只支持严格的 JSON结果模型连续输出带 markdown 代码块的 JSON解析直接失败代理死循环在那里反复重试同一件事。后来我总结出一个原则给模型的输出格式约束绝对不能只有文字描述还要在解析层做容错。先做格式清洗把代码块标记剥掉再做多重尝试解析最后如果还是解析失败就把“解析失败”作为反馈回传给模型让它重新输出。这样循环就能自己恢复而不是卡死。另外模型的工具选择有时会被上次工具返回的 error 信息带偏。比如某个工具超时了模型可能下次就直接换工具但其实只是网络抖动。我在 dispatch 层对 error 做了分类可重试错误、参数错误、权限错误、未知错误。只有参数错误需要模型修正输出其他错误可以直接自动重试或走熔断。这个分类机制后来帮我省了非常多额外的模型调用。5. 深度代理落地中的常见问题与排查实录再好的理论也扛不住真实环境的一顿毒打。这一节我挑几个高频问题把我自己的排查思路和解决办法列出来方便大家遇到类似情况时有个参考。5.1 模型反复调用同一个工具陷入死循环这是深度代理最典型的问题。我见过的最夸张的案例是一个解析文件的任务代理连续 14 次调用同一个解析函数每次都报错但每次都生成一模一样的参数重新调用直到成本熔断才停下。排查思路先看日志确认返回的 error 是否一致。如果一致说明模型没有从错误里学到新信息通常有两个原因。一是错误信息太抽象比如“解析失败”模型根本不知道失败的具体原因自然没法调整参数二是模型在参数生成时本身就是随机采样有可能被策略带偏。解法我推荐双管齐下。第一让工具返回“可定位的错误”解析失败时返回具体到字段级别的信息比如“第 3 行缺少分号”。第二在 Harness 层加上循环检测同一个工具、相似的错误连续出现三次直接把模型下一步的动作替换成“重新评估任务目标不要调用工具”强制它跳出惯性。5.2 上下文爆炸导致回答质量急剧滑坡上下文越长模型对早期信息的注意力越弱这是大模型众所周知的问题。我遇到过的梯度是最开始几千 token 时模型很敏锐到两三万 token 时开始犯懒五万以上时经常遗忘关键约束。解决方案就是强制做信息浓缩。工具返回内容进入上下文之前先提取关键结论记忆超过阈值后用摘要替代原始内容。另外我还会设置“轮次压缩”每五轮循环结束把之前五轮的所有对话和状态扔给模型做一次整体摘要得到一个精简版工作笔记覆盖旧上下文。这样上下文长度始终能被压住模型决策质量也就稳住了。5.3 多步任务中途失败恢复成本高深度代理跑长任务最怕中途崩了。系统重启、网络中断、服务重部署任何意外都可能导致状态丢失。模型自己靠上下文记忆的任务一旦上下文丢了要么从头再来要么给出一个残缺结果。这块我从一开始就坚持状态外置。每完成一个子任务立即写入持久化存储任务进程可以随时被杀掉、重启再从状态文件恢复。恢复时把任务目标和已完成步骤列表注入上下文让模型基于真实进度继续推进而不是一脸懵地重来。实测下来长任务的完成率和稳定性都能得到显著提升。5.4 代理输出结果有条理但数据错了怎么办这类问题最恶心因为结果看着正确但答案里的关键数字是编的。原因通常是工具返回的数据没有对应上模型的问题模型基于缺失信息脑补了一个看起来合理的值。排查方向有两点。一个是看工具选择是否正确模型有没有调错工具、取错字段这个从日志里的工具调用参数可以直接看出来。另一个是看工具返回是否被过度摘要如果摘要过程把关键数据丢掉了模型只能编一个。我的经验是涉及数字的摘要一律保留原始数值和单位并且摘要模型要明确“不得新增未出现的信息”。注意在生产环境里对涉及金额、时间、用户信息等敏感数据的输出最好加一道“校验器”用规则引擎或独立模型交叉验证回答与工具结果的一致性。这层虽然会多消耗一些成本但比给用户交付错误数据再道歉强太多。6. 一些总结性的实操心法写完这么多最后再分享几个我平时特别注重的实操心法。它们不直接对应某段代码但贯穿了整个 Harness 设计过程也算是我踩过无数坑之后沉淀下来的东西。第一Harness 的设计目标不是“限制模型”而是“放大模型”。很多人一开始觉得加这么多校验、状态管理、熔断机制会不会让代理变得迟钝。其实恰恰相反当模型把精力从“处理脏数据、猜测下一步、反复试错”中解放出来它的决策质量反而会更高。好的 Harness 让模型在干净的轨道上全力冲刺。第二把代理当作新人员工来管理。新人进公司你得给他配电脑、开权限、定流程、加审批、装监控而不是直接把他扔进服务器机房让他自己折腾。Harness 就是这套新人管理体系。工具白名单是权限系统状态管理是工作日志可观测性是监控大屏人工确认是双人复核。这个类比每次跟业务方解释的时候都特别管用。第三迭代 Harness 一定要基于日志不要靠感觉。我习惯定期拉取代理运行日志统计每个工具的调用频率、失败率、平均耗时以及每轮循环的 token 消耗。某个工具失败率异常高先检查工具本身某类任务总是在同一节点超时优化该节点的上下文输入成本暴涨看看是不是某个工具返回超长文本导致上下文膨胀。数据驱动的优化方向永远比拍脑袋靠谱。我自己最近的体会是Harness Engineering 正在从一种“个人技巧”变成团队级的工程标准。尤其是深度代理进入生产环节之后光靠提示词工程和模型调优已经不够了必须把代理放到一个完整的、可管理的工作框架里。谁的 Harness 做得更扎实谁的代理项目就更容易从 Demo 走向规模化。这些经验也是我希望团队里每个人都尽快掌握的。如果你也在做深度代理建议下一段周期别只顾着换模型、调提示词先静下心把 Harness 这层补齐效果可能会超出你的预期。
Harness Engineering：让深度代理真正落地的核心工程实践
过去大半年我一直在折腾深度代理Deep Agents相关的东西团队里也堆了不少模型资源。但我越来越强烈地意识到一件事决定一个代理项目能不能真正落地的往往不是模型智商而是外围那层看不见的工程设施。工具接得稳不稳、上下文给得够不够准、状态会不会丢、出了问题能不能及时按住这些事没搞定模型再聪明也是白搭。这类“外围工程”最近在圈子里有个挺准确的叫法——Harness Engineering。这个词越来越常见不是没道理。它说的不是提示词写得多花哨也不是模型微调得多精细而是围绕深度代理构建的那整套“绳索系统”工具链接入、上下文路由、记忆管理、权限边界、可观测性与止损机制。我自己的体会是把 Harness 做扎实了代理才真正从“实验室演示”变成“生产环境里的同事”否则它永远是个情绪不稳定、随时撂挑子的实习生。这篇文章我想把 Harness Engineering 这件事好好拆一遍结合实际踩坑聊聊深度代理到底怎么通过工程化手段被改造成真正靠谱的执行体。不管你是做代码代理、客服代理还是数据分析助手这套思路都值得完整过一遍。文章会覆盖核心概念、关键设计点、代码级实现和常见问题排查尽量给到能直接“抄作业”的东西。1. Harness Engineering 到底是什么先搞懂它解决的是哪种痛很多人一上来就误解以为 Harness 就是给代理加个循环或者套一层工具调用协议。真要这么简单市面上那么多代理平台就不会翻车翻得那么整齐了。我倾向于用一句话概括Harness 是代理与外界之间的基础设施层它负责给模型配好“接收信息的传感器”和“执行动作的执行器”同时把不可控的混沌堵在核心决策圈之外。1.1 先看一种最典型的失败场景我之前在做内部知识库助手时最早的版本直接用大模型调用若干个搜索 API。模型的推理能力很强面板上看起来什么都能回答。但实际丢给业务同事用的时候问题接二连三冒出来。第一个问题是上下文污染用户问一句“上个季度的数据怎么样”代理会把整个知识库里所有跟“季度”“数据”沾边的文档全部拉进上下文导致回答时既参考了正确报表又参考了一篇过期公告最后给你交叉出一个完全错误的结论。第二个问题是工具滥用模型在连续思考时会反复调用同一个查询接口因为每次调用返回的信息都太碎它得不到全貌就一遍一遍重试钱和时间全耗在循环里了。第三个问题是越权有一次模型在调试过程中居然直接调用了删除类接口虽然当时是测试环境但那一瞬间我后背全是冷汗。这三个问题没有一个是模型能力不够造成的。根源都在于代理缺少一道严格的“出入关卡”缺少对上下文的主动管理缺少对工具调用的约束规则。而这套缺失的部分就是 Harness Engineering 要补齐的内容。1.2 “挽具”这个比喻其实非常贴切Harness 在英文里的本意是马具、安全带、降落伞背带核心作用是把动力源与负载安全地连接起来。模型就好比那个强大的动力源它有能力规划、理解、生成但它不能自己进入到外部系统里拿数据、改配置、发请求。任何人试图让模型直接握住所有工具的把手都会导致灾难。把中层连接拆解出来它要做的事情大致有四类信息接入与控制决定哪些外部数据能进入模型视野以什么方式、什么顺序、多少体量进入以及什么内容坚决不让进。动作授权与约束决定模型能调用哪些工具参数怎么校验调用结果如何回传哪些操作在什么条件下直接被拦截。状态流转与持久化在多轮复杂任务中维护内部状态让代理不会“做完这一步就忘了上一步”同时保证可恢复。观测、审计与止损记录每一步决策依据、工具调用、成本消耗并在异常时及时熔断把损失控制在最小范围。这些职责单拎出来都不算难但揉在一起、叠加模型的不确定性之后就变成了一门挺深的工程学问。圈内把专门做这件事的人叫 Harness Engineer很贴切因为这门手艺的本质不是让马跑得更快而是让马和车之间的连接更稳。1.3 模型能力与工程投入的剪刀差我做过一个粗略的统计。同样是让代理做一个“跨三张表生成月度经营分析”的任务模型从 GPT-4 级换到 GPT-5 级任务完成率大概从 40% 提到了 65%。但当我花时间把上下文结构重新设计、给工具接口加上清晰的 schema 文档、加入一轮自我检查机制之后完成率直接跳到了 90% 以上而且这里的模型底子还只是上一代。这个结果让我确定了当前阶段与其把希望全押在下一代模型身上不如把精力押在 Harness 的升级上。模型能力的提升像 CPU 升级确实有效但 Harness 的优化更像操作系统的结构优化动一下整个系统的上限都会被拉高。2. Deep Agents 的工作闭环与 Harness 的介入位置要设计好 Harness 工程必须先弄清楚深度代理的内部运转方式。业界现在提 Deep Agents指的是那种“能自主拆解任务、循环调用工具、根据中间结果不断修正计划”的代理形态。它们跟传统客服机器人的最大区别在于不是一问一答而是“感知-决策-行动-再感知”的持续闭环。2.1 深度代理的自我循环机制一次标准的深度代理执行过程大概是这样的接收用户目标通常是模糊的、口语化的指令。代理内部启动“规划模块”把大目标拆成若干子任务并为每个子任务预设需要的工具。执行第一个子任务调用工具、获取结果、把结果拼回上下文。观察结果是否符合预期如果不符合调整计划重新尝试。循环往复直到所有子任务完成汇聚成最终答案。这个循环看着简单但隐藏的变量太多了。工具返回的数据格式可能千奇百怪有的特别长有的字段缺失网络请求可能超时用户的指令可能本身就存在歧义多个子任务之间还可能存在依赖关系。代理之所以看起来“聪明”是因为模型能从这些变量里推断出下一步行动但它也极其容易在某个不正常的中间态里越走越偏。Harness 在这里的核心任务就是给循环的每一步兜底。它不取代模型做判断但它要保证模型每一步拿到的输入是可控的动作是被限制的异常能被感知并处理。2.2 介入的三个关键接缝我习惯把 Harness 的介入点归纳为三个接缝工具接缝、状态接缝、反馈接缝。工具接缝指代理与外部系统交互的那条线。这条线是 Harness 最重要的把关位。工具返回结果进上下文之前必须经过清洗、截断、摘要工具调用指令发出之前必须经过参数合法性校验、权限校验、频率控制。很多教训都发生在这一层。比如模型会臆想出一些不存在的参数或者把枚举值传成自由文本如果没有校验系统就会静默失败然后模型开始瞎猜原因整个任务就越跑越偏。状态接缝指代理自身工作记忆的维护。深度代理不是无状态的。执行到第三步时它需要记住第一步修正过的假设、第二步排除掉的方案。最简单的状态管理就是塞进上下文里但上下文长度有限且杂乱堆积的信息会降低模型决策的准确率。Harness 要做的是设计一套结构化的状态表示比如用 JSON 维护任务进度、关键决策、中间结果摘要在每次循环后更新并选择性注入到下一轮提示词中。反馈接缝指代理如何获取执行效果的好坏信息。比如代码代理跑完单元测试Harness 应该把哪些测试失败信息、日志片段、覆盖率摘要回传给模型。回传太少模型瞎猜回传太多烟雾弹满天飞。这层的核心是设计信息密度适中的反馈回路。2.3 有 Harness 与无 Harness 的对比我整理了实际对照体验放到一张表里更直观维度无 Harness 的裸代理有 Harness 的工程化代理工具接入模型直接读原始返回格式不统一统一结构化、清洗截断后注入权限控制模型可触碰全部接口风险极高白名单校验高危操作须人工复核上下文管理无限堆叠很快遇到长文本退化有裁剪、摘要、重点优先排序任务状态依赖模型临场记忆极易丢失外部持久化循环间显式同步错误处理模型自行猜测容易陷入死循环有熔断、重试策略、备用路径可观测性只能看到最终回答过程是黑盒每步留痕可回放、可审计成本控制完全失控重复调用高发有预算桶超限自动降级差距就是这么明显。说白了无 Harness 的代理是在靠模型临场发挥打天下有 Harness 的代理是用工程纪律把模型能力锁在轨道上跑。后者也许看着“限制多”但生产环境追求的本就不是自由发挥而是稳定交付。3. 搭建可靠 Harness 的四个核心工程实践知道了介入点接下来要落地。我在多个项目里反复调整之后觉得有四块内容属于 Harness 工程的地基上下文管理、工具定义与授权、状态持久化、可观测性与止损。每一项都值得单独抠细节。3.1 上下文管理决定模型“视野”的质量上下文是深度代理最重要的资源。同一件事上下文里的信息组织好了模型一针见血组织糟糕模型就会在次要信息上反复纠缠。我见过最典型的反面案例是把所有检索结果原封不动全塞进去好几万 token模型被冗余信息淹没别说回答用户问题了连做到不把名字搞混都难。我现在的做法是分层上下文管理。第一层是“核心指令最新任务状态”永远固定在最前面保证模型每轮都知道当前目标是什么、已经推进到哪里。第二层是“工具返回的高价值信息”经过摘要和去重之后注入单条信息原则上不超过 500 字。第三层是“长期记忆”包括历史决策记录和用户偏好以压缩后的条目嵌入。摘要这一步特别重要。工具返回一篇 3000 字的文档模型真正需要的关键信息可能只有一句话。我的做法是做两遍先用一个轻量模型生成结构化摘要提取关键结论和数字再让主代理仅基于摘要做后续推理。这样既省 token又能大幅降低噪声干扰。还有一个容易忽略的细节上下文边界要明显。我习惯在提示词里用清晰的 XML 标签区分指令区、工具结果区、内部思考区。模型对标签的遵从度其实很高分区之后它很少再把不同区域的内容混在一起理解。3.2 工具定义与授权边界把“不能做的事”提前讲清楚工具接入是 Harness 最硬的一道门。现在很多框架都支持工具调用但大家往往忽略一件事工具的描述写得不好模型就会用错。我见过一个例子工具名叫query_user_info描述写了“根据用户 ID 查询用户信息”但没写清楚 ID 参数是数字还是字符串结果模型每次都传字符串接口端强制转换后偶尔出 bug整个任务就卡在那里。工具定义至少要包含五要素清晰的名字、一段说明“什么时候用、什么时候不用”的描述、完整的参数 schema、默认值和边界值说明、以及典型调用示例。工具数量少的时候随便写写也能跑工具一多描述就是模型选择工具的唯一依据这块不能懒。权限控制同样要紧。我的原则是“默认拒绝白名单放行”。模型只能在预设工具集合里挑选任何超出集合的调用请求直接返回“无此权限”。在集合内部高危险操作再加一道人工确认闸门。比如设计一个删除类的工具Harness 层要拦住先把待删除的内容预览给用户等确认后再真正执行。这看着像多此一举但能救命的。注意千万不要把内部接口地址直接暴露给模型。对模型展示的工具应该是封装好的、带明确语义的业务动作而不是原始 HTTP 端点。否则模型一旦产生幻觉很容易拼出不存在的路径排查起来完全是噩梦。3.3 状态持久化让代理拥有“记事本”而不是“记忆力”纯靠模型上下文记住任务进度等于让一个人用大脑记所有事。短任务还行任务一长、步骤一多记忆就开始漂移。深度代理必须配备外部状态存储也就是“记事本”。我会为每个任务维护一个 JSON 结构字段包括任务目标、当前步骤索引、已完成动作列表、每个动作的结果摘要、当前悬而未决的问题、计划修正记录。每个循环结束时更新这个 JSON下个循环开始时把它注入提示词的状态区。这样做有两个好处一是模型不再需要凭记忆回溯二是任务中断时可以随时从状态文件恢复。状态更新要警惕“过度写入”的问题。如果每次工具返回的都原样存进状态状态文件很快会膨胀。我常常在更新状态前加一步合并摘要旧的关键信息留下来细节丢掉。这个状态摘要的过程其实质上也是模型决策质量的生命线。3.4 可观测性与止损机制让代理在“玻璃房”里干活我见过太多代理项目上线后变成黑盒用户只看到最终回答中间过程完全没有记录。一旦回答错了排查成本极高。深度代理的调试本来就难因为模型不是确定性的同样的输入两次执行可能走完全不同的路径。没有过程日志复现 bug 几乎等于大海捞针。所以 Harness 层必须做到全链路追踪。每一轮循环记录模型输入摘要、模型选择的动作、调用工具的参数与返回摘要、状态更新结果。这些日志除了用于事后排查还能做行为分析比如高频失败的工具是哪几个、哪些错误让模型反复重试。止损机制更是不容忽视。我给代理设置了三个熔断级别单步超时熔断某个工具连续失败三次直接终止当前分支切换备用方案或上报人工。成本预算熔断每个任务分配一个 token 预算池烧完就降级为简单的兜底回答不再继续循环。异常行为熔断检测到代理在短时间内高频调用同一工具、或在相似错误里循环超过三次自动暂停并触发告警。这套机制一开始做的时候觉得“太多限制了”但跑几个月下来事故率下降得很明显。代理可以自由发挥但必须在玻璃房里发挥而且玻璃房要有急停按钮。4. 代码级拆解一个最小可用的 Harness 循环光讲概念没用我直接把之前从零搭的一个最小 Harness 循环核心骨架贴出来代码做了简化但能体现关键思路。去掉外部框架的干扰用最原生的方式展示 Harness 应该管哪些事。4.1 最小 Harness 的数据模型首先定义一个任务状态结构和一个工具注册表。工具注册表是关键枢纽模型接触到的所有能力都从这里取。from dataclasses import dataclass, field from typing import Callable, Any, Dict, List, Optional import json, time, uuid dataclass class ToolSpec: name: str description: str parameters_schema: Dict[str, Any] func: Callable[..., Any] requires_confirm: bool False dataclass class TaskState: task_id: str field(default_factorylambda: uuid.uuid4().hex) goal: str step_index: int 0 completed_steps: List[Dict[str, Any]] field(default_factorylist) pending_issues: List[str] field(default_factorylist) context: Dict[str, Any] field(default_factorydict) def to_prompt_section(self) - str: # 把当前状态序列化为文本块供模型阅读 return json.dumps({ goal: self.goal, step_index: self.step_index, completed_steps: self.completed_steps[-5:], # 只保留最近几步摘要 pending_issues: self.pending_issues, }, ensure_asciiFalse, indent2)工具注册的时候就必须带好 schema。这个 schema 不只是给模型看的Harness 层在真正执行前还会拿它做参数校验双重保障。4.2 工具调用与参数校验模型会输出一个结构化的工具调用指令但外部接口不一定能信任这个伪代码。我们做的事是先解析模型输出再通过 schema 校验参数不合格就直接拦截并提示模型重新生成。import jsonschema class ToolRegistry: def __init__(self): self._tools: Dict[str, ToolSpec] {} def register(self, spec: ToolSpec): self._tools[spec.name] spec def dispatch(self, name: str, params: Dict[str, Any], need_confirm: bool False): spec self._tools.get(name) if spec is None: return {error: fUnknown tool: {name}} # 参数校验失败则返回给模型让它修正 try: jsonschema.validate(instanceparams, schemaspec.parameters_schema) except jsonschema.ValidationError as e: return {error: fParameter validation failed: {e.message}} # 高危操作需要外部确认 if spec.requires_confirm and not need_confirm: return {error: This operation requires human confirmation., confirm_required: True} # 真正执行 try: result spec.func(**params) return {result: result} except Exception as e: return {error: fTool execution error: {e}}这层 dispatch 看似简单却是整个 Harness 的咽喉要道。所有外部副作用都必须经过这里那么权限校验、审计日志、频率控制就都有了统一的落点。后续想加限流只要在 dispatch 里加个计数器即可。4.3 主循环规划、执行、反思接下来是最核心的代理循环。我会把模型调用封装成一个小函数里面包含三个环节读取当前任务状态、调用模型生成下一步行动、执行行动并更新状态。def agent_loop(model_api, registry: ToolRegistry, initial_goal: str, max_steps: int 10): state TaskState(goalinitial_goal) step_ctx state.to_prompt_section() for _ in range(max_steps): # 1. 组装上下文核心指令 状态 系统约束 messages [ {role: system, content: 你是一个工程化深度代理必须遵循工作区约束。}, {role: user, content: f当前任务状态{step_ctx}\n可用工具列表见工具描述。请输出下一步要执行的动作。} ] # 2. 调用模型 response model_api.chat(messages) action parse_action(response) # 从模型输出中提取动作指令 if action[type] finish: return {answer: action.get(answer, ), state: state} if action[type] tool_call: result registry.dispatch(action[tool], action[params]) # 3. 将执行结果浓缩后写回状态 concise_result summarize(result) state.completed_steps.append({ index: state.step_index, tool: action[tool], params: action[params], result_summary: concise_result, }) state.step_index 1 step_ctx state.to_prompt_section() # 4. 止损检测 if consecutive_failures(state, 3): return {error: Excessive consecutive failures. Need human intervention., state: state} return {error: Max steps exceeded., state: state}这里最容易被低估的是summarize这一步。很多代理项目不做结果浓缩把原始结果直接塞进去跑两轮上下文就爆炸了。我通常会用模型自身生成一个不超过百字的执行摘要包含“确认了什么信息、得到什么关键数据、下一步可选方向”。这样状态文件干净模型后续决策也精准。4.4 把我踩过的调试细节写在这里这段代码看着挺顺但我第一次跑通它花了整整两天。主要问题出在动作解析上。模型输出的动作格式不稳定有时候是 JSON有时候是自然语言夹杂 JSON有时候一个动作里包含多个工具调用。我一开始写了解析函数只支持严格的 JSON结果模型连续输出带 markdown 代码块的 JSON解析直接失败代理死循环在那里反复重试同一件事。后来我总结出一个原则给模型的输出格式约束绝对不能只有文字描述还要在解析层做容错。先做格式清洗把代码块标记剥掉再做多重尝试解析最后如果还是解析失败就把“解析失败”作为反馈回传给模型让它重新输出。这样循环就能自己恢复而不是卡死。另外模型的工具选择有时会被上次工具返回的 error 信息带偏。比如某个工具超时了模型可能下次就直接换工具但其实只是网络抖动。我在 dispatch 层对 error 做了分类可重试错误、参数错误、权限错误、未知错误。只有参数错误需要模型修正输出其他错误可以直接自动重试或走熔断。这个分类机制后来帮我省了非常多额外的模型调用。5. 深度代理落地中的常见问题与排查实录再好的理论也扛不住真实环境的一顿毒打。这一节我挑几个高频问题把我自己的排查思路和解决办法列出来方便大家遇到类似情况时有个参考。5.1 模型反复调用同一个工具陷入死循环这是深度代理最典型的问题。我见过的最夸张的案例是一个解析文件的任务代理连续 14 次调用同一个解析函数每次都报错但每次都生成一模一样的参数重新调用直到成本熔断才停下。排查思路先看日志确认返回的 error 是否一致。如果一致说明模型没有从错误里学到新信息通常有两个原因。一是错误信息太抽象比如“解析失败”模型根本不知道失败的具体原因自然没法调整参数二是模型在参数生成时本身就是随机采样有可能被策略带偏。解法我推荐双管齐下。第一让工具返回“可定位的错误”解析失败时返回具体到字段级别的信息比如“第 3 行缺少分号”。第二在 Harness 层加上循环检测同一个工具、相似的错误连续出现三次直接把模型下一步的动作替换成“重新评估任务目标不要调用工具”强制它跳出惯性。5.2 上下文爆炸导致回答质量急剧滑坡上下文越长模型对早期信息的注意力越弱这是大模型众所周知的问题。我遇到过的梯度是最开始几千 token 时模型很敏锐到两三万 token 时开始犯懒五万以上时经常遗忘关键约束。解决方案就是强制做信息浓缩。工具返回内容进入上下文之前先提取关键结论记忆超过阈值后用摘要替代原始内容。另外我还会设置“轮次压缩”每五轮循环结束把之前五轮的所有对话和状态扔给模型做一次整体摘要得到一个精简版工作笔记覆盖旧上下文。这样上下文长度始终能被压住模型决策质量也就稳住了。5.3 多步任务中途失败恢复成本高深度代理跑长任务最怕中途崩了。系统重启、网络中断、服务重部署任何意外都可能导致状态丢失。模型自己靠上下文记忆的任务一旦上下文丢了要么从头再来要么给出一个残缺结果。这块我从一开始就坚持状态外置。每完成一个子任务立即写入持久化存储任务进程可以随时被杀掉、重启再从状态文件恢复。恢复时把任务目标和已完成步骤列表注入上下文让模型基于真实进度继续推进而不是一脸懵地重来。实测下来长任务的完成率和稳定性都能得到显著提升。5.4 代理输出结果有条理但数据错了怎么办这类问题最恶心因为结果看着正确但答案里的关键数字是编的。原因通常是工具返回的数据没有对应上模型的问题模型基于缺失信息脑补了一个看起来合理的值。排查方向有两点。一个是看工具选择是否正确模型有没有调错工具、取错字段这个从日志里的工具调用参数可以直接看出来。另一个是看工具返回是否被过度摘要如果摘要过程把关键数据丢掉了模型只能编一个。我的经验是涉及数字的摘要一律保留原始数值和单位并且摘要模型要明确“不得新增未出现的信息”。注意在生产环境里对涉及金额、时间、用户信息等敏感数据的输出最好加一道“校验器”用规则引擎或独立模型交叉验证回答与工具结果的一致性。这层虽然会多消耗一些成本但比给用户交付错误数据再道歉强太多。6. 一些总结性的实操心法写完这么多最后再分享几个我平时特别注重的实操心法。它们不直接对应某段代码但贯穿了整个 Harness 设计过程也算是我踩过无数坑之后沉淀下来的东西。第一Harness 的设计目标不是“限制模型”而是“放大模型”。很多人一开始觉得加这么多校验、状态管理、熔断机制会不会让代理变得迟钝。其实恰恰相反当模型把精力从“处理脏数据、猜测下一步、反复试错”中解放出来它的决策质量反而会更高。好的 Harness 让模型在干净的轨道上全力冲刺。第二把代理当作新人员工来管理。新人进公司你得给他配电脑、开权限、定流程、加审批、装监控而不是直接把他扔进服务器机房让他自己折腾。Harness 就是这套新人管理体系。工具白名单是权限系统状态管理是工作日志可观测性是监控大屏人工确认是双人复核。这个类比每次跟业务方解释的时候都特别管用。第三迭代 Harness 一定要基于日志不要靠感觉。我习惯定期拉取代理运行日志统计每个工具的调用频率、失败率、平均耗时以及每轮循环的 token 消耗。某个工具失败率异常高先检查工具本身某类任务总是在同一节点超时优化该节点的上下文输入成本暴涨看看是不是某个工具返回超长文本导致上下文膨胀。数据驱动的优化方向永远比拍脑袋靠谱。我自己最近的体会是Harness Engineering 正在从一种“个人技巧”变成团队级的工程标准。尤其是深度代理进入生产环节之后光靠提示词工程和模型调优已经不够了必须把代理放到一个完整的、可管理的工作框架里。谁的 Harness 做得更扎实谁的代理项目就更容易从 Demo 走向规模化。这些经验也是我希望团队里每个人都尽快掌握的。如果你也在做深度代理建议下一段周期别只顾着换模型、调提示词先静下心把 Harness 这层补齐效果可能会超出你的预期。
