干Agent开发这两年我最常被问到的问题不是“LangGraph怎么用”而是“Agent Harness 和 Agent Runtime到底有什么区别”。不光刚入门的人懵很多已经上线过Agent项目的团队嘴上说着“运行时”“执行框架”实际排查问题时还是会把两者混在一起。这篇文章我就把这两个概念彻底拆开讲清楚它们分别负责什么、边界在哪里、选型怎么考虑以及在真实项目里到底会遇到哪些坑。先说结论Agent Harness管“Agent怎么被组装出来”Agent Runtime管“组装好的Agent怎么稳定跑起来”。一个是开发态给你搭结构用的框架层一个是运行态负责调度、状态、恢复和观测的设施层。把这层窗户纸捅破后面看很多Agent框架的文档都会顺畅不少。1. 先对齐认知Agent、Agent Harness、Agent Runtime到底指什么1.1 Agent其实是“要交付的东西”不是一层可运行软件很多人一提到Agent默认就是能对话的机器人这没问题。但做工程的人必须清楚Agent本质上是“一个具备感知、决策、行动循环的程序”。它要接收外部输入用户问题、环境变化、事件触发要调用大模型来做推理决策还要执行工具去改变现实或获取信息最后把结果返回。在这个定义下Agent本身是一个“逻辑产物”。我们可以用任何语言把它写出来也可以只写一个脚本跑完就退出。它是可以被交付的东西却不是天然具备“长期运行”“故障恢复”“多人并发访问”能力的服务。也就是说Agent本身不等于一个系统它更像一个“业务逻辑包”。真正让它在生产环境里活下来的是外面的两层一层负责把逻辑拼装得清晰可控另一层负责给拼装好的东西提供运行环境。这就自然引出了Agent Harness 与 Agent Runtime的分工。1.2 为什么“harness和agent的区别”会成为一个高频搜索问题我在各个技术平台搜过一圈发现搜索“harness和agent区别”的人真不少。原因也简单市面上主流的Agent框架中LangChain、LangGraph、CrewAI、AutoGen这类库往往只提供一个“Agent对象”给你直接调用。文档里写agent create_agent(...)很多新手就会误以为“这个agent就是全部了”。但实际上这个agent对象是框架在内存里帮你装好的壳它的背后还挂着一大堆Prompt模板、工具注册表、状态定义、模型绑定。这个“壳”就是harness的产物而不是agent本体。更麻烦的是框架本身经常把Harness和Runtime混在一个包里。你调用LangGraph的app.invoke()时它既做图编排又偷偷替你做了一部分运行时该做的事比如把状态存到checkpointer里。于是你在本地开发时感觉两者就是同一个东西一旦上了生产并发一高、任务一长、进程一重启Runtime缺失的问题就全暴露了。所以本文花大篇幅讲清“harness和runtime的分界”远比单纯区隔“harness和agent”更有用。1.3 用三句话建立整篇文章的认知框架为了便于后续阅读可以先记住三个短句。Agent是你要交付的业务实体负责“该做什么、什么时候做”。Agent Harness是组装Agent的工程骨架负责“用什么模块、按什么顺序、怎么把模型和工具焊在一起”。Agent Runtime是承载Agent运行的基础设施负责“进程活了没、状态碎了没、并发挤不挤、日志丢了没”。这个分层不是理论洁癖而是工程上必须有的分工。没有harnessAgent的复杂度会淹没在重复代码里没有runtimeAgent根本扛不住生产环境的真实流量。接下来我分别把这两层拆开看。2. 拆解Agent Harness它负责Agent“怎么被编出来”2.1 Harness到底包含哪些常见模块Agent Harness这个名字英文原意是“线束”或“夹具”类比到Agent领域很贴切它像电工用的线束一样把模型、记忆、工具、策略这些零件按图纸捆在一起形成一台可以通电的设备。注意这个阶段关注的是“装配”不是“通电运转”。一个典型的Harness框架至少包含下面这些能力。Agent对象的抽象统一封装“模型调用工具选择意图判断”的入口让你不需要每次手写循环。工作流编排模型状态机、图结构、顺序Pipeline或基于角色的多Agent对话流程用来表达“先做什么后做什么”。工具注册体系把外部API、数据库操作、代码解释器作为可被模型调用的工具声明出来并管理参数schema。Prompt与上下文组装把系统提示词、历史对话、工具说明、用户输入拼装成最终请求上下文的逻辑。输出解析与Schema校验让模型输出走结构化协议而不是直接吐一段文本。测试与仿真环境把各种上下文注入Agent模拟不同分支验证编排逻辑是否符合预期。可以这样理解Harness是你在写代码阶段就能感知到的一切“约束性框架”。比如你定义一个ReAct循环本质上就是在说“模型推理一次如需工具就调用观察结果后再推理”。这个循环本身不会平白无故出现是harness在结构上帮你搭好并限制了循环边界。2.2 用LangGraph的一段代码理解“装配”的实感目前开源社区里LangGraph是把Harness层体现得最明显的一个。它用图结构定义Agent的编排你声明节点、声明边、声明状态类型最后调用compile()把它变成可执行对象。比如下面这个非常简化的流程from langgraph.graph import StateGraph, START, END from typing import TypedDict class AgentState(TypedDict): question: str intermediate_steps: list def call_model(state: AgentState): # 实际工程里这里会调用LLM并把结果记录到state return {intermediate_steps: [(call_model, state[question])]} def execute_tool(state: AgentState): # 这里根据模型决定调哪个工具 return {intermediate_steps: state[intermediate_steps] [(execute_tool, ok)]} graph StateGraph(AgentState) graph.add_node(reason, call_model) graph.add_node(act, execute_tool) graph.add_edge(reason, act) graph.add_edge(act, reason) # 循环直到条件满足 graph.add_edge(START, reason) app graph.compile()看到没有这个app对象就是一个被装配好的Agent程序。你定义的图、状态、工具入口都是harness层面的东西。它本身不关心进程崩溃后怎么恢复、多个请求并发时状态会不会串、请求量大了要不要扩机器——这些都是Runtime的事。但框架把图定义和运行封装到了一起很多人因此误以为app就是完整系统。其实它只是一个等待被运行的“程序包”。2.3 Harness设计得好不好直接影响后续Runtime的稳定性这一点特别容易被忽略。很多团队先把Harness选型定了Agent在本地跑得很欢结果部署上线后惨不忍睹。为什么因为Harness里写死的很多假设一到Runtime就成了灾难。举几个真实感受。第一如果Harness在Graph节点里直接用全局变量或内存List存状态那这个Agent在单进程单请求下没问题但在Runtime里一旦并发状态就会互相污染。正确做法是让状态数据流式地记录在状态对象里并把状态对象交给Runtime的checkpoint机制管理。第二如果Harness层把“重试”“退避”逻辑写在工具函数内部而不是交给Runtime的调用链路那一旦工具超时你会发现重复调用和请求熔断混在一起很难排查。工具本身应该尽量“傻一点”把可靠性交给专门的运行设施去管。第三Harness的平台绑定不要做太死。比如你把LangGraph的StateGraph对象直接塞进业务数据库存起来后续版本升级会让你很难受。编译好的图对象应该是可重建的不要随便序列化持久化。实际经验是把Harness当作“前端工程”来治理。频繁变更、依赖重构、要做版本管理还要有回归测试。每次改Prompt模板或图结构都当成一次发版这样后续的Runtime才不会因为harness被塞进一堆脏逻辑而崩溃。3. 拆解Agent Runtime它负责Agent“怎么被跑起来”3.1 Runtime在Agent每次干活时具体做了什么如果Harness是工厂里装配机器的流水线图纸那么Runtime就是给已经造好的机器通电、供料、做安全监控的厂房系统。没有厂房和电力系统图纸再漂亮也只是纸面功夫。Agent Runtime在真实运行时要扛起这几类职责。生命周期管理创建Agent运行实例安排它执行超时或异常时安全终止对长时间运行的Agent还可能要支持暂停、恢复。并发调度与队列多个用户同时触发Agent时要决定谁先谁后哪些任务需要排队哪些任务可以并行。如果Agent内部有循环还要防止死循环把资源耗尽。状态持久化与会话恢复每一轮对话、每一步中间结果、工具返回值都要能落到持久化存储。进程挂了或者发版重启后能根据会话ID把Agent恢复到之前的状态。模型接入与网关统一处理大模型API的调用、鉴权、限流、重试、超时以及Token用量统计和成本控制。工具执行沙箱很多Agent会调用代码解释器、浏览器、文件系统。这些工具如果和Runtime主进程共享权限一旦Prompt注入后果非常严重。所以成熟Runtime会把工具放到隔离沙箱里执行。可观测性与追踪把每一次模型的输入输出、思考链路、工具调用记录保存下来方便调试和事后审计。安全与配额限制单个会话Token消耗、限制工具执行时长、做敏感信息脱敏。你可能会觉得这不就是一个后端服务该做的事吗对本质上Agent Runtime就是一个为“带有推理循环和无固定输入顺序”的AI任务设计的后端运行时。它和普通Web后端最大的区别在于Web请求通常是一次性的短请求而Agent任务可能有几十轮内部循环可能调用多个外部系统还可能需要几分钟甚至几小时才能完成。这导致Runtime必须对任务状态、分布式追踪和恢复能力提出更高要求。3.2 拿一个“天气查询助手”走一遍Runtime链路为了更有体感我举一个最简单的天气Agent例子它内部只做一件事根据用户问题判断要不要调天气API需要就调用再整理结果返回。当用户请求打过来时Runtime一侧实际会发生这些事。第一接入层收到请求并完成鉴权。它根据对话ID去持久层读取会话状态如果这是一个新会话则初始化新的Agent状态。这里如果没有Runtime恢复机制那么每次请求都只能从零开始多轮对话就无从谈起。第二执行引擎把恢复出来的状态交给编译好的Graph也就是Harness产物开始跑第一个节点。模型调用不是直接裸连API而是经过一个统一的LLM网关由网关做超时控制和重试。假如第一个节点因为模型API网络抖动失败了Runtime会判断该节点是否可重试并根据退避策略等待片刻再次调用。第三图跑到“调天气工具”这一步时Runtime会把工具调用请求发到隔离的执行沙箱里。沙箱里没有主进程的数据库连接只有被放行的HTTP出口。返回结果后Runtime将新状态写回Redis或Postgres保证操作可恢复。如果进程这时突然崩溃重启后能从数据库里找到当时执行到哪个节点并继续未完成的部分。第四整轮执行结束后Runtime把最终消息返回用户同时把这次完整调用链路模型调用次数、Token消耗、工具耗时、费用估算写入观测平台。这件链路里哪一步是靠Harness实现的只有“状态类型、节点函数、边的跳转逻辑”。剩下的大量工作——恢复、网关、沙箱、持久化、观测——全是Runtime的职责。所以当你把一个Agent Demo变成一个线上服务时你真正要搭建和运维的其实就是这套Runtime。3.3 自建Runtime时你可以参考哪些组件不是每个团队都需要从零写Runtime。市面已经有很多成熟组件关键是按职责把它们组合起来。我这里给一套个人常用的“最小可生产”组合。功能可选实现为什么这么选LLM接入网关LiteLLM、Portkey、OneAPI统一多家模型API负责限流、重试、密钥管理执行编排引擎Temporal、LangGraph Platform长时任务需要可靠恢复Temporal擅长持久化工作流状态状态保存Redis PostgreSQLRedis用于热会话Postgres负责冷存储与审计组合性价比高工具沙箱gVisor、Firecracker、Docker内运行受限程序隔离不可信的工具代码避免工具逃逸影响主服务可观测追踪Langfuse、LangSmith OpenTelemetry追踪模型思考链路和Token消耗生产排查必备任务队列Redis Stream、RabbitMQ、KafkaHttp接口外的异步触发和批处理任务需要队列缓冲如果团队小、不想自己运维直接使用LangGraph Platform这类托管Runtime是非常省心的选择。它已经把checkpointer、服务接口、后台任务和观测做进一个托管平台里你只需要上传编译好的Harness产物。缺点就是平台绑定后续如果想换更大的执行引擎迁移成本偏高。对大多数还在验证业务阶段的团队来说能用托管就先托管把时间留给业务本身。4. Agent Harness和Agent Runtime的九大区别图解4.1 一张表看透所有关键差异为了彻底把两者分开我列过一张对比表几乎每个项目都有人找我讨要。这里直接放出来。对比维度Agent HarnessAgent Runtime发生阶段开发、装配、编译期部署、调度、运行期面向对象应用开发者平台工程师、运维、SRE核心问题怎么把模型/工具/流程组织成Agent怎么让Agent在长时间、高并发下稳定工作典型产物编译后的Graph对象、可注册的工具集服务、执行器、分布式任务队列修改代价改完要联调测试、发版改完要重启服务、可能影响在线任务故障示例意图判断错误、工具调用参数错、路由死循环进程OOM、会话状态丢失、API限流、上下文串号关键指标准确率、召回率、编排可理解性可用性、P95延迟、恢复时间RTO、成本代表实现LangGraph、CrewAI、Semantic Kernel、AutoGenLangGraph Server、Temporal、Kubernetes、自研AgentService主要日志诉求节点输入输出、Prompt内容、工具参数资源监控、链路追踪、错误堆栈、告警看这张表你会发现Harness关心的问题大多是“这一轮该调用哪个函数”Runtime关心的问题是“这个服务现在还能不能扛得住”。如果遇到问题第一反应是去看Prompt或流程编排说明你在查Harness层如果第一反应是看CPU、看日志、查数据库链接说明你在查Runtime层。4.2 四个最常被问错的实际场景很多人即便看了表到具体场景里还是会判断失误。我整理过四个高频问题你可以拿来自测。场景一Agent在线上回答一半突然中断恢复后却忘记之前已经做过哪几步。很多人会去检查Harness里的状态定义和图节点实际上这个问题的根源在Runtime缺了持久化。只要把状态保存加上Graph本身一行都不用改。场景二我改了Prompt也重新reload了代码但线上Agent还是按老Prompt回答问题。这不是Runtime问题而是harness产物没重新构建发布。不少平台会把编译结果缓存到特定版本你没有生成新版本线上自然不变。记住改harness一定走完整的版本发布流程重启进程不等于发布新图。场景三同一套Agent本地跑一次没问题线上并发一高就频繁出现工具调用串了。这时候不要怀疑Prompt写得不对。真要查通常问题在Runtime的任务调度你为了性能把一个进程内的共享状态对象暴露给了多个会话互相踩踏了。需要对每个会话做隔离或者在Runtime层为每个请求分配独立的状态上下文。场景四Agent明明没有主动运行却过一段时间自己开始调用工具。这也不是Harness的编排逻辑问题而是Runtime的定时触发或后台任务在工作。如果你没配置权限可能是平台默认开启了某种长时Agent的自动恢复。这类情况要去Runtime的触发配置里查别去翻代码里的Graph定义。4.3 真正的选型建议先拆层再选型我见过不少团队在选型时直接把LangGraph全家桶一套上结果发现Graph层很满意Runtime层又觉得不够用最后不得不换。我建议先拆层再选型。如果你只是做原型验证、跑一个离线脚本那LangGraph的库本身够用Harness层和Runtime层都挤在一个进程里无所谓。如果你要做线上API服务多用户并发调用优先确认框架是否提供独立Runtime服务。如果没有要么自己写一层服务来管理会话和并发要么把任务状态交给Redis/Postgres不要裸用库里的内存状态。如果你要做长时间运行、几十步以上的复杂任务Harness用什么其实没那么关键重要的是Runtime的任务队列和执行引擎能不能在服务重启后恢复任务。这种场景我建议直接调研Temporal这类分布式工作流引擎它所提供的可靠执行能力正是Agent Long-running任务的解药。如果你的核心场景是对外部工具高度依赖、安全要求高那么Runtime的沙箱设计就是第一优先级。Harness流程再精巧工具一旦逃逸整个系统都不可信了所以要把精力放到隔离方案上。5. 实操中我踩过的坑以及一套排障速查清单5.1 三个真实事故复盘我过去一年为好几个Agent项目做过架构和排障这里挑三个印象最深的记录一下给后来者提个醒。第一个事故发生在一次图升级后。开发同学在Harness里调整了状态机的边让Agent在“用户拒答”后走澄清节点而不是直接结束。本地测试清晰正确但上线后总是出现Agent不停地追问行为跟本地版本完全对不上。排查了大半天最后发现是平台把编译后的Graph服务按“会话ID”做了缓存老会话仍然用旧版本图继续跑。根因不在Harness逻辑而在Runtime侧的版本切换策略。从那以后我们养成了一个习惯大版本改图时要么弃用所有历史会话要么为会话版本号加迁移逻辑。第二个事故和沙箱权限相关。我们的Agent有一个工具是读取上传的Excel文件。在本地直接跑文件读写没问题一上开发环境工具老报“Permission denied”。当时开发第一反应是harness里的工具函数出了问题反复检查代码没发现异常。后来排查发现环境的工具执行沙箱默认只开放了临时目录而文件上传落盘到了另一个挂载点沙箱内根本访问不到。这就是很典型的Runtime环境和Harness逻辑边界不清导致的排查空转。建议所有工具函数先声明自己需要哪些外部资源然后由Runtime侧统一配置权限不要指望工具自己解决环境问题。第三个事故更隐蔽。我们给会话状态做的持久化键只用了简单的对话ID结果不同渠道来源的同一个对话ID发生碰撞A用户在某一步的工具返回值被B用户下一个请求读到出现了严重的串号。问题出在Runtime层的状态存储设计而Harness完全感知不到。后来我们把持久化键改成了“渠道用户会话”三段式并加了渠道隔离才彻底解决。这类问题特别容易发生在你刚开始并发上线Agent的时候是Runtime设计里最值得提前考虑的一部分。5.2 遇到问题时先判断该查哪一层结合前面的踩坑经验我整理了一套速查思路遇到问题可以按这个顺序判断。现象优先排查Harness还是Runtime排查要点回答内容不符合预期HarnessPrompt、模型参数、图节点逻辑、工具选择请求时好时坏间歇性超时Runtime限流、网关重试、Pod资源、网络账号余额多轮对话记忆丢失Runtime持久化组件、会话ID、checkpointer配置老会话还在用旧逻辑Harness和Runtime都查是否重新编译发版历史会话有没有指定版本工具调用顺序乱了Harness状态机、边条件、上下文更新逻辑工具执行失败但代码正确Runtime沙箱权限、网络策略、依赖库版本、环境变量进程启动后不响应RuntimeCPU/内存/DB连接数、初始化加载是否有死锁异常堆栈指向模型APIRuntime网关密钥、超时参数、模型限流配额这里有个通用原则凡是“单一输入下行为一定”的问题先查Harness凡是“输入一样但行为偶尔不一致、跟并发和资源有关”的问题多半在Runtime。判断时还要注意很多深度链路的故障其实是两层共同作用的结果不建议只盯一层。5.3 给团队分工和代码组织的一点建议最后说说团队分工。一个Agent产品团队至少要有两种角色视角一个是Agent开发负责Harness层的Prompt、Graph、工具设计与质量一个是平台或后端负责人负责Runtime层的服务治理、状态底座、沙箱和观测。如果一个人同时扛两层很容易在排查问题时只盯着自己熟悉的层忽略另一层的风险。代码仓库也建议分清楚。Harness相关的代码库可以叫agent-definitions里面只放图、节点、工具注册。Runtime相关的库叫agent-runtime或agent-service里面只放服务、环境配置、存储、部署脚本。两层之间通过明确的接口或镜像发布物连接。这样当线上出问题时团队第一反应就能按代码归属定位到正确方向。另外日志规范也可以分层。Harness层打的是结构化业务日志哪一轮、哪个节点、哪个工具、模型输入输出摘要。Runtime层打的是系统日志容器重启、内存回收、数据库超时、API调用失败。两层日志用同一个traceId串起来排障效率会高非常多。这是我们在经历数次事故后沉淀下来的最大经验。很多项目最终失败不是输在模型能力不足而是输在环境一复杂就分不清到底是Agent“没想对”还是“没跑稳”。把Harness和Runtime的边界钉在心里你排查问题的思路就会清晰很多。选型时也记住一点Harness可以追新但Runtime尽量走成熟方案。实际操作中我对Harness的改动一定谨慎发版对Runtime的扩容一定提前预判这样做了之后Agent系统的稳定性明显比早期“一锅炖”的时候要好上不少。