最近我们团队把一个编码 Agent 从“跑 3 步就早停”升级到连续执行 8 小时、完成完整功能开发靠的不是换更强的模型而是把Harness 工程做到极致。很多人以为 Agent 好坏只看模型其实 80% 的生产力差距来自 Harness——那个包裹在模型外面的“操作系统”文件系统、沙箱、上下文管理、执行循环、Hooks……今天我就把我们基于LangChain Deep Agents官方明确叫 agent harness Ralph Loop的实战经验全部拆开给你最硬核的实现细节、代码结构、类设计和真实踩坑记录。看完就能直接上手搭一个能打的生产级 Harness。Harness 架构总览四层设计我们把 Harness 分成四层参考 LangChain Deep Agents 自定义扩展Model LayerLLM 调用Claude / GPT / 自定义Executor Layer工具执行 沙箱e2b / DockerState Layer持久化状态FilesystemBackend Git AGENTS.mdOrchestration LayerMiddleware Ralph Loop Subagent 调度LangGraph 状态图核心思想每次循环都用 fresh context所有状态靠文件系统持久化模型只负责“思考”Harness 负责“执行 记忆 续命”。1. FilesystemBackend最基础的生产力基石Deep Agents 内置了可插拔的虚拟文件系统我们直接继承它。核心实现简化版 Workspace 类frompathlibimportPathimportgitfromlangchain_core.toolsimporttoolclassWorkspace:def__init__(self,root:str./agent_workspace):self.rootPath(root)self.root.mkdir(exist_okTrue)self.repogit.Repo.init(self.root)ifnot(self.root/.git).exists()elsegit.Repo(self.root)tooldefread_file(self,path:str,offset:int0,limit:int1000):带行号、支持大文件分段读取full_pathself.root/path linesfull_path.read_text().splitlines()return\n.join([f{i1}:{line}fori,lineinenumerate(lines[offset:offsetlimit])])tooldefwrite_file(self,path:str,content:str):full_pathself.root/path full_path.parent.mkdir(parentsTrue,exist_okTrue)full_path.write_text(content)self.repo.index.add([str(full_path)])returnf已写入{path}defcommit(self,message:str):self.repo.index.commit(message)生产技巧所有大输出20k tokens自动 offload 到文件消息历史只留路径 前 10 行预览。多 Agent 协作直接共享同一个 root_path Git 版本控制天然实现“共享 ledger”。2. 安全沙箱 Bash 执行器Deep Agents 默认支持 sandbox backend我们推荐e2b最简单或自建 Docker。e2b 实战集成5 行代码frome2b_code_interpreterimportSandboxfromdeepagents.backendsimportSandboxBackendclassE2BSandbox(SandboxBackend):def__init__(self):self.sbSandbox(timeout300)defexecute(self,code:str,files:dictNone):iffiles:forname,contentinfiles.items():self.sb.files.write(name,content)executionself.sb.run_code(code)returnexecution.text,execution.error踩坑经验一定要加资源限制CPU 2核、内存 4GB、网络隔离。大文件读写用 stream避免一次 load 全量进内存导致 OOM。命令白名单只允许pip install、pytest、git等高频命令。3. Context Management打败 Context Rot 的三板斧Deep Agents 内置了超级实用的自动机制我们再加一层自定义 middleware。自动 Offloading20k tokens 阈值# deepagents 内置阈值可配iftool_result_tokens20000:pathworkspace.write_file(flogs/tool_output_{step}.txt,full_result)returnf[已卸载到文件]{path}\n预览前10行{full_result[:500]}Summarization Middleware我们最爱fromdeepagents.middlewareimportcreate_summarization_tool_middleware middleware[create_summarization_tool_middleware(modelllm,backendStateBackend(),summary_prompt提取任务目标、关键事实、当前状态、下一步计划控制在 800 tokens)]AGENTS.md 记忆文件跨会话长时记忆每次启动自动注入Agent 可以自己write_file(AGENTS.md, ...)更新规则。4. Ralph Loop让 Agent 真正“长跑”的核武器这是我们能跑 8 小时的核心灵感来自 Geoffrey Huntley 的经典实现 Deep Agents 的 PreCompletionChecklistMiddleware。纯 Python 版 Ralph Loop生产推荐defralph_loop(agent,initial_goal:str,max_iterations200):workspaceWorkspace()step0whilestepmax_iterations:# 1. 读取最新状态fresh contextplanworkspace.read_file(fix_plan.md)agent_memoryworkspace.read_file(AGENTS.md)if(workspace.root/AGENTS.md).exists()else# 2. 注入干净 promptmessages[{role:system,content:f目标{initial_goal}\n当前计划{plan}\n规则{agent_memory}},{role:user,content:继续执行下一步完成一个任务后立即停止思考}]# 3. 执行一轮resultagent.invoke({messages:messages})# 4. 检查是否想提前退出关键词 小模型分类if任务完成inresult.contentoris_exit_intent(result.content):# Ralph 拦截强制续命workspace.write_file(fix_plan.md,update_plan(plan,result))workspace.commit(f完成第{step}步)continue# 重新开启新会话step1关键设计点每轮结束强制 commit 清空消息历史 → 永远 fresh context。用fix_plan.md做状态机避免模型迷失。子任务用 Deep Agents 的task工具委托隔离上下文。5. Middleware Hooks 系统可插拔的“神经中枢”Deep Agents 的 middleware 是神器我们写了三个生产必备# 1. 循环检测防 doom loopclassLoopDetectionMiddleware:def__init__(self,max_edits5):self.edit_count{}def__call__(self,tool_call):ifedit_fileintool_call.name:filetool_call.args[path]self.edit_count[file]self.edit_count.get(file,0)1ifself.edit_count[file]5:return你已经在同一个文件改了 5 次考虑换个方案或跑测试验证returntool_call# 2. 完成前校验PreCompletionChecklistclassPreCompletionMiddleware:def__call__(self,output):ifexitinoutput.lower()or完成inoutput.lower():return请先运行测试并验证结果再决定是否结束returnoutput生产踩过的坑 避坑指南上下文污染永远别让子 Agent 的中间输出进主上下文 → 用 Deep Agents 的task工具强制隔离。成本爆炸开启 token 限制 自动 summarization单次任务从 180 万 tokens 降到 45 万。调试地狱必须接 LangSmith 所有工具输出自动 dump 到 workspace/logs。权限失控interrupt_on{“execute”: True} 人工审批关键命令。模型过拟合同一个模型换不同 Harness性能能差 30%我们 Terminal Bench 实测。最小可运行完整示例直接复制运行fromdeepagentsimportcreate_deep_agentfromdeepagents.middlewareimportcreate_summarization_tool_middlewarefrommy_harnessimportWorkspace,E2BSandbox,ralph_loop agentcreate_deep_agent(modelanthropic:claude-4-sonnet,sandboxE2BSandbox(),middleware[create_summarization_tool_middleware(...),LoopDetectionMiddleware(),PreCompletionMiddleware()],memory[AGENTS.md]# 持久记忆)ralph_loop(agent,实现一个支持用户注册的 FastAPI 项目并写完整测试)总结Agent Model HarnessModel 负责聪明Harness 负责靠谱。我们用 Deep Agents 提供的 Filesystem、Subagent、自动上下文管理作为底座再叠加自定义 Ralph Loop Middleware真正把“demo 玩具”变成了能落地的生产力工具。想快速上手直接pip install deepagents跑官方 quickstart然后把上面的 Workspace Ralph Loop 插进去半小时就能拥有一个能打的 Agent。Harness 工程才是 2026 年真正的内功心法。紫微AI推荐18篇 Harness 精讲深度综述Effective Harnesses for Long-Running Agents2026年AI Agent 的真相模型成了可互换的引擎Harness 才是决定 Agent 能不能真正落地的产品控制论重生Harness Engineering 才是真正的未来工程师工作Harnesses Agent Frameworks 敢诚实回答这个问题的人从瞎试工具的一人公司真正变成知道怎么选、怎么用、怎么赚钱的“智能生意人”。AI Agent 的成功秘诀Harness 才是产品模型只是引擎Harnesses Agent Frameworks 敢诚实回答这个问题的人从瞎试工具的一人公司真正变成知道怎么选、怎么用、怎么赚钱的“智能生意人”。AI Agent 的成功秘诀Harness 才是产品模型只是引擎Agent Harness 工程实战文件系统、沙箱、Ralph Loop 与 Middleware 生产级实现附完整代码​​​​​​​​​​​​​​​​​​​​​AI Agent 的核心秘密不是大模型而是 Harness 工程别再试图让 Agent 适应你的代码库而是让代码库和流程适应 Agent。AI Coding Agent 时代工程师不再是“码农”Harness Engineering 实战 playbook训练环境决定 AI Agent 天花板Harness 如何塑造 RL 训练循环AI Agent 时代模型只是“基础设施”Harness 才是你真正的产品从零手把手用本地Ollama GPT-OSS搭建AI Agent Harness完全离线、私有、零成本让AI真正“永动机”干活LLM Agent 非法动作频发Google DeepMind 用 AutoHarness 自动生成代码“安全带”小模型直接反超大模型Harness 才是王道为什么 3 个工程师能月产百万行代码而你的 Agent 还在原地打转AI Agent 的本质不是模型而是流程设计Harness 才是真正的王牌实战篇大多数开发者以为 AI Agent 拼的是模型能力但 Anthropic 最新实验告诉你真正决定成败的是「生成-评估」分离的 Harness 设计用AI自主开发完整App时你是不是也卡在“代码看着行、实际一用就崩”Anthropic的Harness设计给出答案我是紫微AI我们下期见。完