1. 三层不是分层而是Agent系统演进的三个“生存阶段”你第一次看到“Harness、Loop、Graph”这组词并列出现时大概率会下意识把它当成某种技术栈的缩写组合——就像LAMP、MEAN那样。但事实恰恰相反这不是一个堆叠式技术栈而是一套描述Agent系统在真实生产环境中如何活下来、跑起来、稳住阵脚的演化地图。它不讲“应该怎么做”只讲“不这样就会死”。我带过三支不同行业的Agent落地团队金融风控、工业设备预测性维护、电商智能导购。每支队伍都经历过几乎一模一样的痛苦路径——第一周兴奋地用LangChain搭出能回答问题的Demo第二周发现用户问“上个月华东区退货率最高的SKU是什么”系统直接卡死在SQL生成环节第三周开始疯狂加超时、重试、降级开关代码里塞满if-else判断“当前是否在Loop中”第四周终于把所有模块用K8s编排起来结果监控面板上Graph节点的延迟毛刺像心电图一样跳个不停。这就是Harness、Loop、Graph的真实出场顺序Harness是救命绳Loop是呼吸机Graph是神经系统。它们不是设计出来的是被线上事故逼出来的。Harness解决的是“这个Agent能不能动”的问题——它把LLM调用、工具执行、状态保存这些基础动作封装成可插拔、可观测、可熔断的原子单元Loop解决的是“这个Agent能不能持续动”的问题——它定义了Agent从接收输入到产生输出的完整生命周期处理重试、中断、状态恢复、多轮上下文管理Graph解决的是“这个Agent能不能聪明地动”的问题——它把多个Agent、外部API、数据库、缓存、规则引擎组织成一张有向依赖图让决策流、数据流、控制流真正可视化、可调度、可干预。关键词里反复出现的“deepseek harness”“harness engineering”“loop engineering”背后其实是同一群人在同一类场景下的集体求生反应当Agent不再只是玩具Demo而要扛住每秒200并发请求、处理平均耗时4.7秒的复杂推理链、在30%网络抖动率下保持99.5%成功率时你根本没得选——必须把Harness做扎实把Loop理清楚把Graph建起来。这不是架构师画在PPT上的漂亮分层而是SRE凌晨三点盯着Prometheus面板时手指悬停在“重启Pod”按钮上心里默念的三句咒语。提示别急着翻文档查Harness API怎么写。先问自己你的Agent第一次失败时错误日志里有没有明确指出是LLM超时、工具调用失败、还是状态序列化异常如果没有说明你连Harness的门槛都没跨过去。2. Harness让Agent具备“可诊断性”的最小执行单元Harness这个词在工程语境里本意是“挽具”“束带”用在Agent系统里精准传达了它的核心使命把不可控的LLM调用、不可信的外部工具、不可预知的运行环境用一套标准化的“束带”捆扎起来使其成为可观测、可干预、可替换的确定性组件。它不是框架不是SDK而是一种执行契约。很多团队误以为Harness就是封装一下OpenAI API调用。错。真正的Harness必须同时满足四个硬性条件输入/输出契约化每个Harness单元必须明确定义其输入Schema如{query: string, user_id: uuid}和输出Schema如{result: string, confidence: float, tool_used: enum}。我见过最惨的案例是一家医疗问答AgentHarness单元输出直接返回原始JSON字符串下游模块靠正则匹配提取答案结果当LLM生成带换行符的JSON时整个流水线崩溃——因为契约缺失连最基本的结构校验都做不到。执行过程可插桩Harness必须内置标准埋点接口且默认开启。不是“支持埋点”而是“不埋点就无法启动”。我们强制要求每个Harness单元在以下节点打点before_invoke参数快照、after_invoke响应体摘要、token消耗、耗时、on_error错误类型、重试次数、兜底策略触发标记。这些数据不是为了画大屏而是为了在故障时5分钟内定位到是哪个Harness单元、哪类输入、在哪个集群节点上持续超时。失败处理策略内聚Harness内部必须封装完整的失败应对逻辑而非甩给上层。典型策略包括熔断Circuit Breaker连续3次超时阈值可配置后自动切换至本地缓存或静态兜底响应持续60秒退避重试Exponential Backoff首次重试间隔100ms每次翻倍最多3次降级Fallback当LLM调用失败时自动启用规则引擎或关键词匹配作为替代路径。状态管理外置化Harness单元自身不持有任何状态所有状态如对话历史、临时变量、中间结果必须通过统一的状态服务如Redis Hash TTL存取且Key命名遵循harness:{unit_id}:{session_id}:{timestamp}规范。这保证了Harness单元可以无状态水平扩展也避免了因Pod重启导致状态丢失。以一个真实的电商比价Agent为例其价格查询Harness单元结构如下class PriceQueryHarness(HarnessBase): # 输入契约严格校验 input_schema { type: object, properties: { sku: {type: string, minLength: 8}, region: {type: string, enum: [CN, US, JP]} }, required: [sku] } def execute(self, input_data: dict) - dict: # 1. 埋点记录输入摘要脱敏 self.log_metric(before_invoke, { sku_hash: hashlib.md5(input_data[sku].encode()).hexdigest()[:8], region: input_data[region] }) try: # 2. 熔断器检查基于Redis计数器 if self.circuit_breaker.is_open(): return self.fallback_strategy(input_data) # 3. 执行主逻辑调用价格API response requests.get( fhttps://price-api.example.com/v1/price?sku{input_data[sku]}region{input_data[region]}, timeout3.0 ) # 4. 输出契约校验 result response.json() if not self._validate_output_schema(result): raise SchemaValidationError(Price API returned invalid structure) return result except requests.Timeout: self.log_metric(on_error, {error_type: timeout, retry_count: self.retry_count}) self.circuit_breaker.trip() raise except Exception as e: self.log_metric(on_error, {error_type: type(e).__name__}) raise def fallback_strategy(self, input_data: dict) - dict: # 降级查本地缓存TTL 1小时 cache_key fprice_cache:{input_data[sku]}:{input_data[region]} cached redis_client.hgetall(cache_key) if cached: return {k.decode(): v.decode() for k, v in cached.items()} # 再降级返回静态提示 return {price: 暂未获取到实时价格, source: cache_fallback}这个Harness单元的价值不在于它多聪明而在于当线上价格查询失败率突然飙升到15%时运维同学不需要翻10个微服务的日志只需在Grafana里筛选harness_price_query_on_error指标按error_type分组立刻就能看到92%的错误是ConnectionError进而锁定是第三方API的DNS解析服务出了问题——而不是去怀疑LLM模型本身。注意Harness不是越重越好。我们曾砍掉一个包含“自动重试熔断降级缓存日志监控”的超级Harness拆成三个独立单元PriceAPICaller只负责调用、PriceCacheReader只负责读缓存、PriceFallbackEngine只负责规则降级。原因很简单当某个子单元需要紧急更新时你不想因为一个缓存策略变更被迫重新部署整个价格查询链路。3. LoopAgent的“心跳机制”与状态韧性设计如果说Harness解决了“单次动作”的可靠性那么Loop解决的就是“连续动作”的生存性。Loop不是简单的while循环它是Agent系统的心跳节律器、状态保险丝、上下文锚点。没有LoopAgent就是一次性烟花有了LoopAgent才具备持续服务的生命体征。Loop的核心矛盾在于LLM的非确定性输出 vs. 业务流程的确定性要求。用户问“帮我订一张明天去上海的机票”Agent可能第一步查航班第二步选座位第三步支付第四步发短信。但LLM可能在第二步突然生成“抱歉我无法访问订票系统”或者在第三步生成一段无关的旅游攻略。Loop要做的就是把这种混沌驯化成可预期的节奏。Loop的四个关键设计原则全部来自血泪教训3.1 状态机驱动而非文本驱动早期我们尝试用LLM输出的自然语言文本如“下一步查询航班”来驱动流程结果灾难性失败。LLM会随机生成“请稍候”、“正在处理中”、“让我想想…”等无效状态导致Loop无限等待。正确做法是Loop只识别预定义的、机器可解析的状态码。我们定义了标准状态集WAITING_INPUT等待用户新输入初始态EXECUTING_TOOL正在调用某个Harness单元TOOL_SUCCESSHarness成功返回需LLM生成下一步TOOL_FAILUREHarness失败需执行降级或重试GENERATING_RESPONSELLM正在生成最终回复RESPONSE_READY最终回复已生成等待发送LOOP_COMPLETED任务成功结束LOOP_ABORTED任务主动终止如用户取消每个Harness单元执行完毕后必须返回明确的状态码而非自由文本。LLM的Role Prompt里强制要求“你只能输出JSON包含next_state字段值为上述状态码之一禁止输出任何解释性文字。”3.2 上下文快照与增量同步Loop必须维护两套上下文长期记忆Long-term Memory和短期工作区Working Context。前者存于向量数据库用于跨会话知识检索后者存于内存或Redis仅限当前Loop周期使用。关键创新在于“增量同步”每次Loop迭代结束时只将本次迭代产生的新信息片段如“用户确认了航班号MU5123”、“支付金额为¥1280”写入长期记忆而非全量覆盖。这避免了LLM在生成过程中产生的幻觉内容污染长期记忆。我们用DynamoDB的Conditional Update实现原子性只有当last_sync_version等于当前Loop版本号时才允许写入新片段。3.3 超时熔断与优雅降级Loop必须自带“生命维持系统”。我们设置了三级超时单步超时Step Timeout每个Harness单元执行上限3秒超时即标记TOOL_FAILURE单轮超时Round Timeout从用户输入到生成首个响应上限15秒超时即进入LOOP_ABORTED全程超时Session Timeout整个多轮对话生命周期上限10分钟超时即强制清理所有状态降级路径严格分级首次超时 → 切换至更轻量Harness如用规则引擎替代LLM生成摘要二次超时 → 返回结构化错误码如ERR_PRICE_UNAVAILABLE由前端决定展示文案三次超时 → 触发人工客服转接协议自动填充用户当前上下文快照3.4 中断恢复与幂等重放用户网络中断、页面刷新、App后台杀进程这些不是异常是常态。Loop必须支持从中断点精确恢复。我们的方案是每个Loop迭代生成唯一IDLoopID该ID作为所有操作的幂等Key。当用户重新连接时前端携带最后已知的LoopID发起请求。后端检查该LoopID对应的状态若状态为EXECUTING_TOOL检查Harness是否已返回若未返回则重发请求Harness需支持幂等若状态为GENERATING_RESPONSE直接返回缓存的LLM输出我们用Redis Stream存储中间结果若状态为RESPONSE_READY立即推送最终回复这套机制让我们在电商大促期间面对30%的移动端网络抖动用户会话中断恢复成功率高达99.2%平均恢复耗时200ms。提示Loop的调试成本极高。我们开发了一个Loop Debugger CLI工具可注入任意LoopID实时查看其状态机流转图、各步骤耗时、Harness输入/输出快照、LLM Prompt原文。没有这个工具排查一个Loop卡在TOOL_SUCCESS却迟迟不进入GENERATING_RESPONSE的问题至少需要2小时有了它3分钟定位到是LLM的System Prompt里漏写了next_state字段的约束。4. Graph从单点Agent到协同智能体网络的拓扑革命当Harness确保每个动作可靠Loop保障每次交互存活下一个瓶颈必然浮现单个Agent的能力边界。用户的问题越来越复杂——“对比iPhone15和华为Mate60的影像能力并结合我的摄影习惯推荐一款”——这需要调用相机参数API、图像处理SDK、用户行为分析服务、竞品数据库还要协调多个LLM专家模型影像专家、硬件专家、消费心理专家。这时单点Agent的线性Loop就捉襟见肘了必须升级为多Agent协同的Graph网络。Graph不是指知识图谱而是Agent系统的服务拓扑图节点是Harness单元或子Agent边是数据流与控制流。它把“谁该做什么”、“谁依赖谁”、“数据怎么走”、“失败怎么兜”这些隐性逻辑变成显性的、可编程的、可调度的图结构。我们构建Graph的三个核心实践4.1 节点类型化Harness、Sub-Agent、OrchestratorGraph节点绝非千篇一律。我们严格区分三类节点Harness节点执行原子操作如调用天气API、执行SQL查询无内部状态纯函数式。Sub-Agent节点封装完整业务能力的独立Agent如FlightBookingAgent、HotelRecommendationAgent自带Harness和Loop对外暴露标准接口。Orchestrator节点不执行具体任务只负责调度。它读取Graph定义根据输入动态选择执行路径处理节点间的数据转换与错误传播。例如“旅行规划”Graph中UserIntentClassifierHarness解析用户输入输出意图标签flight,hotel,visaFlightBookingAgentSub-Agent处理机票相关全流程HotelRecommendationAgentSub-Agent处理酒店推荐TripOrchestratorOrchestrator根据意图标签决定并行调用FlightBookingAgent和HotelRecommendationAgent或串行调用VisaRequirementsAgent4.2 边的语义化Data Edge vs. Control EdgeGraph的边必须承载明确语义不能只是“A调用B”。我们定义两种边Data Edge数据边表示结构化数据传递。必须指定Schema如{ departure: string, arrival: string, date: date }且目标节点必须声明兼容该Schema。不匹配则Graph编译失败。Control Edge控制边表示执行流控制。包含条件表达式如$intent flight和失败路由如on_failure - fallback_to_rules。Orchestrator节点据此动态决定下一跳。这种分离让Graph具备强类型安全。当FlightBookingAgent的输出Schema从{ flights: [...] }升级为{ flights: [...], carbon_emission: number }时所有消费该数据的节点如EcoScoreCalculator必须显式声明兼容新Schema否则CI Pipeline直接失败——杜绝了“上游改了字段下游默默出错”的经典陷阱。4.3 动态Graph编译与热加载Graph定义不是静态JSON而是可执行代码。我们采用YAMLJinja2模板定义Graph# trip_plan_graph.yaml nodes: intent_classifier: type: harness module: agents.intent.classifier input_schema: { text: string } output_schema: { intent: enum:[flight, hotel, visa] } flight_agent: type: sub_agent module: agents.flight.booking # ... edges: - from: intent_classifier to: flight_agent condition: $output.intent flight data_mapping: departure: $output.departure_city arrival: $output.arrival_city - from: intent_classifier to: hotel_agent condition: $output.intent hotel data_mapping: location: $output.destination checkin: $output.checkin_dateCI Pipeline会将此YAML编译为Python字节码生成TripPlanGraph类。关键突破在于热加载当新Graph版本发布时Orchestrator节点无需重启通过gRPC接收新字节码验证签名后动态替换内存中的Graph实例。灰度发布时可设置流量比例如10%请求走新Graph实时对比成功率、耗时、错误率。这套Graph系统让我们在金融风控场景中将原本需要3个独立Agent反欺诈、信用评估、合规审查串联的流程重构为一个可动态组合的Graph。当监管新规要求新增“ESG风险扫描”环节时只需在Graph中插入一个新Harness节点并配置Control Edge路由规则2小时内即可上线零代码修改原有Agent。注意Graph的复杂度爆炸是真实风险。我们强制推行“Graph分治”单个Graph节点数不超过7个深度不超过3层。更复杂的流程必须拆分为多个Graph通过Orchestrator节点编排。曾有一个19个节点的Graph上线后因一个节点超时导致整条链路雪崩——根源不是技术是违背了“人脑认知负荷极限”这一基本规律。5. 生产落地从架构图到SLO的残酷校验再精妙的Harness、再健壮的Loop、再优雅的Graph如果不能转化为可衡量的业务价值就只是工程师的自嗨。我们用一套铁律校验生产落地效果所有架构决策必须映射到至少一个SLOService Level Objective指标并接受真实流量的持续压力测试。我们定义的Agent系统核心SLOSLO名称目标值测量方式架构支撑点Harness Success Rate≥99.95%(成功Harness调用数) / (总Harness调用数)Harness熔断、降级、重试策略Loop Completion Rate≥98.5%(成功完成Loop数) / (启动Loop总数)Loop状态机完整性、中断恢复能力Graph End-to-End Latency P95≤3.5s从用户输入到最终响应推送的耗时95分位Graph节点并行度、Harness超时设置、Orchestrator调度开销State Consistency Rate≥99.99%(状态一致的Loop数) / (总Loop数)Loop上下文快照、增量同步、幂等重放机制这些SLO不是摆设。我们建立了“SLO熔断机制”当任意SLO连续5分钟低于目标值95%自动触发三级响应一级告警企业微信机器人推送标注受影响Graph、Loop ID、最近失败Harness二级限流Orchestrator节点自动降低该Graph的QPS配额优先保障高价值用户三级降级强制将该Graph所有请求路由至备用规则引擎直到SLO恢复。去年双11我们的电商导购Graph在流量峰值时Graph End-to-End Latency P95突增至4.2s。SLO熔断机制自动触发Orchestrator将30%流量切至轻量版Graph移除图像理解Harness仅保留文本推荐。运维团队根据告警定位到是ProductImageAnalyzerHarness的GPU资源争抢15分钟内扩容后SLO恢复正常全程未影响用户体验。真正的生产实践永远在架构图与SLO仪表盘之间反复横跳。我们每周举行“SLO复盘会”不聊技术细节只问三个问题哪个SLO没达标差多少是哪个Harness/Loop/Graph环节拖了后腿证据在哪必须指向具体指标、具体时间点、具体日志下周的改进措施能否让这个SLO提升0.1个百分点如何验证这种 brutally honest 的文化让架构讨论脱离了“我觉得”“理论上”扎根于“数据证明”“用户感知”。当你看到Harness Success Rate从99.82%提升到99.96%而Loop Completion Rate同步从97.3%升至98.7%你就知道那几周加班写的熔断逻辑、重试策略、状态快照真的在守护用户的每一次点击。最后分享一个血泪经验不要试图一步到位构建三层架构。我们踩过的最大坑是团队花三个月设计出完美的Graph编译器却连一个稳定的Harness都没有。结果上线后90%的故障源于Harness超时未处理Graph再美也是空中楼阁。正确路径永远是先用最简Harness跑通核心流程 → 加Loop保障多轮交互 → 最后用Graph解耦复杂协作。每一层都必须用真实SLO数据证明它带来了可量化的提升再进入下一层。架构不是画出来的是SLO逼出来的。