从零理解 Agent 与 Harness：揭秘 AI 工程化核心，打造可靠智能系统！

本文深入探讨了 AI 工程化中的 Agent 与 Harness 概念。Agent 是指具备动态自主决策能力的系统而 Harness 则是确保 Agent 可靠工作的工程化手段。文章对比了 LangChain 和 OpenAI 对 Harness 的两种理解视角并详细阐述了 Harness 的七大核心职责包括状态管理与路由、短路机制、上下文组装、Agent 层自主推理与工具调用、流式双通道推送、可观测性以及两种 Agent 模式。通过真实项目 PAI 的案例文章展示了如何通过 Harness Engineering 构建可靠、可扩展、可复现的基础设施从而真正“看清”模型的能力边界和行为特征。开篇什么是 Agent什么是 Harness2026 年初Mitchell HashimotoHashiCorp 联合创始人在一篇博客中提出了“Engineer the Harness”的概念。随后几天内OpenAI 发布了 Harness Engineering 实践报告LangChain 发表了 The Anatomy of an Agent HarnessMartin Fowler 也跟进了分析文章。“Harness Engineering” 一夜之间成了 AI 工程领域的热词。但热度归热度很多人对 Agent 和 Harness 的关系仍然模糊。这篇文章先把概念理清再用一个真实项目带你看它们是怎么落地的。Agent动态自主决策的系统先说 Agent。Agent 不是调 API 的脚本也不仅仅是一个 ReAct 循环。按照 Anthropic 在 Building Effective Agents 中的定义Agent 的核心属性是LLM 动态自主决策——模型自己决定下一步做什么、调用哪些工具、什么时候结束整个过程由环境反馈驱动而不是由预定义的代码路径控制。这和Workflow形成对比。Workflow 是预定义的编排——你在代码里写好先做 A、再做 B、如果 X 就做 C。Agent 则是把决策权交给 LLM让它根据当前状态自主规划执行路径。ReActReasoning Acting是 Agent 的一种经典实现模式但不是唯一的。Agent 还可以包括规划Planning、子 Agent 委派、记忆检索、验证循环等更复杂的行为。Harrison ChaseLangChain CEO在 2025 年提出的“Deep Agent”概念就是指那些拥有复杂基础设施支撑的 Agent。一句话Agent 的本质是LLM 拿着工具自主干活。Harness让 Agent 可靠工作的一切工程手段再说 Harness。Hashimoto 的原始定义很务实每当你发现 Agent 犯了一个错你就工程化一个方案让它再也不犯这个错。这些方案的总和就是 Harness。但Harness 到底是什么这个问题业界目前有两种理解视角一Harness 在 Agent 内部LangChainLangChain 在 The Anatomy of an Agent Harness 中给出的公式Agent Model Harness“A harness is every piece of code, configuration, and execution logic that isn’t the model itself.”在这个框架里Harness 是 Agent 的内部组成部分——模型之外、Agent 之内的一切基础设施。裸模型不是 Agent加上 Harness 之后才变成 Agent。视角二Harness 在 Agent 外部OpenAI / HashimotoOpenAI 在 Harness Engineering 和 Hashimoto 的原文中Agent 本身已经是一个完整的实体模型 推理循环Harness 是围绕 Agent 的外部环境——AGENTS.md 文档、Lint 规则、沙箱、自检脚本、模块边界约束等。两种视角的本质区别LangChainOpenAI / HashimotoHarness 位置Agent 内部包裹 ModelAgent 外部包裹 AgentAgent 是什么Model Harness 的组合体已有的完整工具如 Codex、Claude Code典型场景从零构建一个 Agent 应用使用现有 Agent 产品工程化其运行环境Harness 的例子Prompt 模板、状态管理、RAG 管线AGENTS.md、Lint 规则、沙箱、自检脚本这两种视角并不矛盾只是站在不同的抽象层如果你在构建 Agent比如用 LangChain/LangGraph 开发你会自然地把 Harness 理解为 Agent 内部的基础设施——因为你在搭建模型周围的一切。如果你在使用 Agent比如用 Codex、Claude Code 写代码你会自然地把 Harness 理解为 Agent 外部的环境——因为 Agent 对你来说是个黑盒你能控制的是它运行的环境。核心共识是一致的Harness 是所有让 LLM 可靠工作的非模型推理部分。区别只在于你把Agent的边界画在哪里。为什么需要 Harness Engineering因为Agent 在真实场景中不够可靠。Demo 阶段裸 Agent 表现惊艳——给它几个工具写几句 prompt它就能跑起来。但一旦上生产环境问题就来了1. 可靠性问题。Agent 的行为是概率性的。同样的输入它可能走不同的推理路径调用不同的工具产出不同的结果。在 Demo 里这叫灵活在生产环境里这叫不可控。用户说确认Agent 有时理解成确认操作有时理解成闲聊——你能接受 95% 的成功率吗在交易、医疗、运维这些场景里答案是不能。2. 成本与延迟问题。每次 LLM 调用都有时间和金钱成本。很多请求根本不需要 LLM 介入——状态查询、确认操作、格式转换——但如果所有逻辑都塞在 Agent 里每条消息都要跑一遍完整的推理循环。3. 可观测性问题。Agent 是个黑盒。它为什么调了这个工具为什么选了这个参数出错时怎么定位没有 Harness 提供的日志、追踪、审计机制调试 Agent 就像蒙着眼睛修车。4. 上下文管理问题。模型有上下文窗口限制。随着对话变长、知识增多如何决定哪些信息送给模型、哪些丢弃、什么时候做摘要这些不是模型能自己解决的。5. 交互与环境问题。模型只能输入和输出文本但实际场景中 Agent 需要读写文件、执行命令、操作浏览器、调用外部 API。Codex 要和 PC 上的代码仓库交互Claude Code 要在终端执行命令并解析输出Devin 要操控浏览器和 IDE。如何把模型的文本输出转化为真实世界的操作如何把环境的反馈转化为模型能理解的输入这整个交互层——沙箱、文件系统访问、命令执行管线、流式 UI 反馈——都是 Harness 要解决的。6. 安全与边界问题。Agent 能调用工具意味着它能产生副作用——写数据库、发消息、执行代码。如何限制它的能力边界如何防止 prompt injection 导致的越权操作这些需要在 Agent 之外建立防护。这些问题的共同点是靠调 prompt 解决不了。你可以在 prompt 里写请不要调用危险工具但这是概率性的约束——模型可能遵循也可能不遵循。Hashimoto 的实践经验一针见血每次 Agent 犯错不要去改 prompt 碰运气而是工程化一个确定性的方案。这就是 Harness Engineering 的核心构建可靠、可扩展、可复现的基础设施让我们能真正看清模型的能力边界和行为特征而不是凭感觉判断模型好不好。它是模型开发闭环中不可或缺的一环。理解了这些概念之后我们来看一个真实项目是怎么做的。PAI 是一个从零构建的 Agent 应用所以它天然属于LangChain 视角——我们在搭建模型周围的一切基础设施Harness 是 Agent 的内部组成部分。本文使用的代码仓库Lsogod/personal-ai-pai如果对你有帮助欢迎点个Star。项目简介PAI 是一个基于 LangChain / LangGraph 构建的个人 AI 助理支持智能记账、日程提醒、长期记忆和多端同步Web 微信小程序。分支说明main— 多节点路由架构Router → 专业领域节点feat/single-agent— 单 Agent 全工具集架构本文基于此分支前置阅读如果你对工具系统还不熟悉建议先看 [从真实项目拆解 Agent 工具系统]。下面这张图是 PAI 的 Harness 全貌——对照上面的七个组件看看一个真实项目中每个组件对应了什么一、Harness 的第一个职责状态管理与路由PAI 的 Harness 用 LangGraph 的 StateGraph 实现。整个图只有三个节点条件判断是一个纯逻辑函数新用户的setup_stage 3走引导流程已完成设置的用户进入 Agent。def_route_setup(state: GraphState)-str:Pure logic gate — no LLM call.if state.get(user_setup_stage,0)3:returnonboardingreturnagent注释里的“no LLM call”是刻意写的——提醒每个读代码的人这里不该有 LLM 调用。路由判断是 Harness 的活儿不是 Agent 的活儿。状态通过 Redis Checkpointer 持久化。断线重连、服务重启后对话的user_id、conversation_id、setup_stage这些数据不会丢。代码里做了优雅降级——Redis 连不上就回退到内存存储开发环境不用为了跑一个 Agent 先搭 Redis。二、Harness 最有价值的设计短路机制进入 Agent 节点之后Harness 不会立即创建 Agent而是先做一轮短路检查。什么是短路举个真实场景用户发了一张小票图片 → Agent 识别出三笔消费生成预览 → 用户回复确认这个确认需要 LLM 来理解吗不需要。Redis 里已经存了待确认状态pending_ledger用户的下一条消息只要命中这个状态就直接交给专用处理器——插入数据库、清除 pending 状态、返回已记账。整个过程零 LLM 调用。节省的不仅是 token 成本更关键的是延迟——一次 LLM 推理通常 1-3 秒短路可以在毫秒级完成。PAI 里有两类短路待确认账单pending_ledger小票 OCR 识别后等用户确认待确认日程pending_reminder_plan日程计划生成后等用户确认还有一个设计细节如果用户这次发了新图片即使有 pending 状态也不走短路。因为新图片意味着用户可能在发一张新的小票而不是在确认上一张。这种边界条件的处理就是 Harness 的价值——在 prompt 里写如果有新图片就忽略 pending 状态远不如一个if not current_image_urls可靠。三、Harness 的第二个职责上下文组装短路检查通过后Harness 开始为 Agent 准备工作包。这是 Harness 和 Agent 之间的交接面——Harness 把所有信息收集好、格式化好打包成一个 System Prompt 交给 Agent。这个工作包包含七层信息层内容来源身份用户昵称、AI 助手名称、角色设定数据库图片预分析图片类型、OCR 文字、结构化摘要预调用 analyze_image工具使用原则工具调用规范、错误处理策略硬编码模板行为约束最大调用次数、安全边界硬编码模板会话上下文最近 16 轮对话 超窗口摘要GraphState.extra长期记忆用户偏好、习惯带优先级标签PostgreSQL技能文档用户启用的自定义技能说明技能系统图片预分析为什么在 Harness 里做用户发了一张图片说帮我记一下Agent 需要先知道这是小票还是风景照才能决定调analyze_receipt还是analyze_image。如果不预分析Agent 的第一轮推理就是盲猜很可能浪费一轮工具调用。Harness 在创建 Agent 之前先调一次analyze_image做预分析把结果注入 System Prompt。Agent 拿到的上下文已经包含了这是一张超市小票有 3 笔商品这样的结论第一轮就能直接调用正确的工具。省掉一轮工具调用 省掉一次 LLM 推理。这种优化只能在 Harness 层做因为 Agent 还没创建。上下文渲染的关键设计会话上下文由render_conversation_context()渲染它支持灵活配置——包不包含助手消息、包不包含长期记忆、上下文窗口多大。这些决策由 Harness 做出Agent 完全不感知。Agent 的认知边界 System Prompt 的内容。Harness 决定了这个边界。Agent 不需要知道记忆是从 PostgreSQL 还是 Redis 来的不需要知道摘要是怎么生成的不需要知道上下文窗口是 16 轮还是 32 轮。它只看到一个已经渲染好的字符串。四、Agent 层自主推理与工具调用上下文准备好后Harness 才创建 Agent。在 PAI 里Agent 用create_agent()创建是一个标准的 ReAct 循环每一轮 LLM 推理模型会做一个判断调工具还是直接回复如果调工具执行完工具后把结果喂回去进入下一轮。如果直接回复循环结束。硬限制recursion_limit12同时在 System Prompt 里软约束最多调用 6 次工具——双重保险。工具可见性Harness 的权限控制Agent 能看到哪些工具不是 Agent 自己决定的而是 Harness 通过toolsets.py在代码层面控制。主 Agent 拥有全部 28 个工具。但短路处理器ledger_manager_node、schedule_manager_node只能看到自己领域的工具子集——记账处理器看不到日程工具日程处理器看不到记账工具。这些处理器不是 StateGraph 的独立节点而是main_agent_node内部的短路分支——当检测到 pending 状态时直接调用对应的处理器跳过主 Agent 的创建。这种隔离不依赖 prompt 约束“请不要调用日程工具”而是在代码层面根本不注册那些工具。比 prompt 约束可靠得多。五、流式双通道文本和工具事件的统一推送Agent 推理不是等到全部结束再返回结果。PAI 用astream_events实现了实时流式推送而且同时推送两种信息通道内容客户端表现文本流LLM 输出的每个 token打字机效果逐字显示回复工具事件工具调用的开始和结束显示正在记账…“查询完成 ✓”两个通道走的是同一个流通过特殊前缀\x00TOOL_EVENT:区分。为什么不用单独的 WebSocket 通道因为工具事件和文本流有严格的时序关系——用户需要先看到正在查天气…然后看到天气结果出现在回复文字里。如果走两个独立通道时序对齐就变成了一个分布式时钟同步问题。走同一个流顺序天然保证。这个设计决策看起来不起眼但在实际开发中省掉了大量的前端时序同步代码。六、可观测性不侵入业务代码的审计机制每次工具调用都需要记录审计日志——谁调了什么工具、参数是什么、耗时多久、成功还是失败。但这个逻辑不应该写在每个工具函数里面。PAI 用了闭包 ContextVar的模式在main_agent_node入口创建审计钩子通过 Python 的ContextVar注入到工具执行链中。工具代码完全不知道审计钩子的存在它只是被调用、返回结果审计在外层自动发生。这个模式的好处是三重的工具代码保持纯净——不混入日志逻辑生命周期可控——每个请求有自己的钩子实例通过 ContextVar 做协程级隔离不会跨请求泄漏可插拔——测试时不设置钩子审计逻辑就不执行ContextVar在这里至关重要。FastAPI 是异步架构同一进程内可能有几十个请求并发执行。线程局部变量threading.local在异步场景下会互相污染而ContextVar是协程安全的——每个协程有自己的上下文副本。七、两种 Agent 模式同一个 Harness 的不同 AgentPAI 在两个分支上演进了两种完全不同的 Agent 模式。它们共享同一个 Harness。模式 ARouter 专用节点main 分支每条消息先经过一个 Router轻量 LLM 调用分类成记账“日程”闲聊等意图然后路由到对应的专用节点。每个节点只能看到自己领域的工具。适合场景LLM 工具选择能力较弱时通过工具隔离降低误调风险。每个节点的 prompt 更精简、更专注。代价是每条消息多一次 LLM 调用路由以及跨领域任务需要额外编排。模式 B单 Agent 全工具feat/single-agent 分支线上运行没有 RouterAgent 直接看到全部 28 个工具自主决策调什么。适合场景LLM 足够强GPT、Claude 等在 20 工具的场景下依然能精准选择。零路由开销跨领域任务一轮循环内链式完成。怎么选这不是一个哪个更好的问题而是你的 LLM 够不够强的问题。模型工具选择能力强 → 单 Agent 更高效。模型容易选错 → Router 隔离更安全。关键是两种模式切换的成本只在 Agent 层。Harness 的状态管理、短路机制、上下文组装、审计日志——全部不变。这就是分层的价值。八、总结从 PAI 中提炼的 Harness Engineering 原则回到 Hashimoto 的原始洞察每次 Agent 犯错就工程化一个方案让它再也不犯。PAI 的每个 Harness 组件都是这个思路的体现1. 能用if解决的不要用 LLM短路机制是这个原则的极致体现。确认流程、状态检查、权限判断——确定性逻辑比 LLM 快 100 倍且 100% 可靠。这不是优化而是通过确定性的基础设施明确划定了模型的介入边界——哪些事情需要模型哪些根本不需要。2. 控制 Model 的认知边界Agent Model Harness而 Model 能看到什么完全由 Harness 决定。System Prompt 的内容、工具的可见性、上下文的窗口大小——这些都是 Harness 的配置项不是 Model 的选择。在代码层面不注册某个工具比在 prompt 里写请不要调这个工具可靠得多。3. 验证优于祈祷图片预分析是一种验证——在 Model 推理之前先确认输入类型避免盲猜。pending 确认流也是一种验证——用确定性的状态检查替代 LLM 对确认的语义理解。每一个验证环节都在让模型的行为变得更可观测、更可复现。4. 可观测性是 Harness 的必备组件你无法改进你无法观测的东西。审计钩子让每次工具调用都有迹可循流式双通道让用户实时感知 Agent 的工作状态。这些不是锦上添花而是 Harness 的基础能力。5. Harness 是稳定的Model 是可换的PAI 在两个分支上运行着完全不同的 Agent 模式——Router 多节点 vs 单 Agent 全工具。切换的成本只在 Model 层Harness 的状态管理、上下文组装、审计日志、流式推送全部不变。这就是Agent Model Harness这个公式的实际价值Model 可以随时换Harness 是你的长期资产。假如你从2026年开始学大模型按这个步骤走准能稳步进阶。接下来告诉你一条最快的邪修路线3个月即可成为模型大师薪资直接起飞。阶段1:大模型基础阶段2:RAG应用开发工程阶段3:大模型Agent应用架构阶段4:大模型微调与私有化部署配套文档资源全套AI 大模型 学习资料朋友们如果需要可以微信扫描下方二维码免费领取【保证100%免费】配套文档资源全套AI 大模型 学习资料朋友们如果需要可以微信扫描下方二维码免费领取【保证100%免费】