做 Agent 开发有一段时间的朋友应该都有同感Agent 这个词被塞进了太多含义。有人说的 Agent 是那个会自己调工具的模型有人说的是把模型包起来的 Harness还有人说的是后台那张由 Loop 和 Graph 共同构成的工作流图。等真正进入生产阶段这三层要是没在架构上掰扯清楚几乎一定会出现同一种症状——单跑一次请求感觉一切正常一上并发、一接外部系统整个状态就彻底失控排查起来根本无从下手。这篇文章想聊的正是 Agent 工程里三条最关键的主线Harness、Loop、Graph。你可以把它们分别理解为运行边界、执行循环、流程编排这也是绝大多数成熟 Agent 项目在事实上的分层方式。无论你是在用 LangChain/LangGraph 这类现成框架还是基于 Rust、Go 自研 Agent 底座这三层的边界划分基本决定了你的代码最终是能上线的工程还是只能跑的 demo。这篇内容适合正在做 Agent 开发、面临框架选型或者被线上并发和问题排查折磨的开发者与架构师参考。1. 从调 API到做工程Agent 项目的三层边界到底划在哪1.1 一个看似正常的 Agent 为什么会悄悄失控先说个很典型的场景。你花一个下午用提示词加 function calling 做出了一个客服 Agent演示时它表现得非常好用户问我的订单到哪了它调起查询工具拿到物流信息组织一段话回复。一切看起来天衣无缝。可一旦这个 Agent 要接入真实业务麻烦立刻出现。第一不是所有用户都有权限查所有订单你得在模型调用工具之前做身份和权限校验第二用户可能会继续追问那什么时候能送到能不能改地址模型需要反复查询、确认、再查询这就不是一个单次推理能解决的事第三订单信息可能分散在订单系统、仓储系统、物流系统三个地方模型需要并行拉取再汇总中间还可能要等待人工审核。等你把这些需求一个个用 if-else 和回调堆进去代码就会变成一团谁都理不清的乱麻。这个例子其实暴露了 Agent 工程的本质问题你不能把 Agent 当作一个更强的 API来用而必须当作一个需要被约束、被驱动、被编排的系统来设计。约束它的是 Harness驱动它的是 Loop编排它的是 Graph。这三层在 demo 阶段可以完全混在一起但在生产阶段必须各司其职。1.2 三层职责的划分逻辑横切线、时间线与全局图为了把这三层的关系说清楚我喜欢用一个新员工入职的类比。Harness 是公司给员工配的工位、门禁和权限。它决定了这名员工能进哪些房间、能碰哪些系统、报销额度是多少、操作哪些事情需要走审批。在 Agent 工程里Harness 就是模型外部的约束框架负责管住它能做什么、不能做什么、能调哪些资源。模型本身再聪明也必须在 Harness 划定的边界内行动。Loop 是员工接到任务后的日常节奏。开会理解目标、动手干活、中途汇报进展、根据反馈调整方向、再继续干直到任务完成。对应到 Agent 工程里Loop 就是这个员工模型代理的节拍器决定它如何在推理—行动—观察之间循环推进。Graph 是整个项目的流程图。它描述的是任务从哪个环节开始、做完一步之后流转到哪里、什么条件下可以并行、什么条件下需要等待人工确认。对应到 Agent 工程里Graph 是多个步骤、多个子任务之间的全局拓扑关系。从维度上看Harness 是横切面贯穿所有环节Loop 是时间线管单个执行体如何迭代Graph 是全局图管多个执行体如何协作。这三层不是互相替代的关系而是叠加的关系。把这三句话记在脑子里后面所有的设计都不会跑偏。2. Harness模型的缰绳先管住工具和权限再谈智能2.1 Harness 不等于 Agent谁在思考谁在约束最近社区里讨论热度很高的 DeepSeek Harness 这类插件以及各路以 harness 命名的开源项目让很多人产生了一个困惑Harness 难道就是 Agent 本身吗其实不是。Harness 这个词最早来源于测试领域的 test harness指的是被测系统之外的一套支持装置负责给被测系统喂数据、模拟环境、收集结果。在 Agent 工程里它的角色被扩展了模型是被测系统Harness 是模型之外那层支持、约束、观测的脚手架。模型负责思考Harness 负责提供思考所需的工具、限制思考能触碰的边界、记录思考留下的痕迹。我见过不少团队把这两者混为一谈结果就是给 Agent 写了一大堆工具调用代码而不是给 Agent 配一个 Harness。两者的差别很大前者是把工具逻辑直接塞给模型模型想调就调后者是在模型和工具之间加了一道闸门每次调用都必须经过授权、超时、审计。看似只是多了一个中间层但生产环境下的安全性、可控性和排查能力全在这个中间层里。2.2 一个合格 Harness 里必须常驻的三类能力具体到落地一个生产级的 Harness 至少要包含三类东西。第一工具注册表与权限模型。不要把所有 function 的 schema 一股脑丢给模型。应该按服务、按账号粒度声明工具名称、入参结构、可见范围。模型可见的工具列表应该是 Harness 根据当前请求的身份动态生成的。用户没权限查的订单对应工具根本不该出现在模型的选项里。这样做既省 token又从源头杜绝了越权调用。第二上下文与记忆管理。系统提示词、工具返回结果、历史对话窗口的裁剪都是 Harness 的职责。它决定模型当前能看到什么。这块要特别注意 token 预算假设上下文窗口是 128kHarness 应该在每次循环前估算已有 token 占用给模型推理留出合理余量而不是等满了才截断。第三审计与操作日志。每次工具调用的入参、出参摘要、耗时、成功失败状态都要记录。注意这里不能只记最终回复否则线上出问题你根本不知道是哪次工具调用给了模型错误信息。日志还要在 Harness 层做脱敏手机号、身份证号这些不能原样落盘。下面是一个比较基础的 Python 风格 Harness 骨架重点看工具调用前校验这个流程class Harness: def __init__(self, user_ctx, tool_registry): self.user_ctx user_ctx # 当前用户身份 self.tools self._filter_tools(tool_registry, user_ctx) def _filter_tools(self, registry, user_ctx): # 根据用户角色过滤可见工具越权工具直接不下发 return [t for t in registry if t.allowed_roles user_ctx.roles] def call_tool(self, name, args): if name not in self.tools: raise PermissionError(ftool {name} not allowed) with tracer.start_span(ftool.{name}) as span: span.set_attribute(args, json.dumps(args, ensure_asciiFalse)[:500]) result invoke_tool(name, args, timeout5) span.set_attribute(result, summarize(result)) return result这段代码要说明的核心是模型不直接触碰工具所有调用都经由 Harness 的 call_tool校验、埋点、超时都在这一层统一处理。2.3 上生产前给 Harness 定下的三条铁律最小权限原则。模型申请调用某个工具时授权范围要精确到具体的操作和具体的资源范围宁可先给窄再放开也不要一开始就全量开放。所有外部调用必须有超时和熔断。工具服务不稳定是常态如果一次工具调用能挂起 30 秒你的 Loop 会被它拖死连带拖垮整个请求队列。超时时间建议控制在 3 到 5 秒失败后给模型返回明确的结构化错误信息让模型有机会换一条路。Harness 保持无状态。Harness 这一层不要存业务状态它只负责执行时的约束和观测。所有要跨请求保留的东西放进外部存储。这一点对水平扩展至关重要否则你会有状态分片和粘性会话的双重麻烦。有人在搭建自研底座时通常会把 Harness 做成插件化的能力集合外部系统通过描述文件把工具、权限、校验逻辑注册进来类似一种即插即用的结构。这也是为什么大家看到以 Harness 命名的插件时会本能地意识到它不是模型能力而是工程能力的外化。3. Loop给 Agent 装上节拍器让循环推进有始有终3.1 四种主流的 Agent 循环形态Loop 是整个 Agent 系统中离模型最近的一层也是最容易写出 bug 的一层。因为循环这种结构天然有跑飞的可能。先看四种常见形态。循环形态核心逻辑典型适用场景主要风险单轮推理模型一次生成回答不调用工具纯问答、知识库检索无法完成任务类事项ReAct 循环思考Thought→ 行动Action→ 观察Observation→ 再思考需要多步工具调用的任务容易陷入反复尝试、不收敛Plan-Execute先写计划再按计划逐条执行复杂任务拆解比如数据分析、报告生成计划一旦错误后续全错带评价的循环每轮执行后用评价器打分低于阈值则重试代码生成、内容创作、需要质量兜底的任务评价逻辑本身不稳定会抖动可以把 ReAct 循环看作是所有形式的基础模型先想一步然后调用工具或输出内容拿到工具结果或环境反馈再决定下一步干什么。Plan-Execute 和带评价的循环本质上是在 ReAct 的某些位置插入额外的控制逻辑。3.2 循环的刹车系统终止条件与死循环防护给 Agent 写个while True是非常危险的就算是最简单的对话任务模型也可能因为提示词里的模棱两可永远追问下去。我线上踩过的坑是某个搜索 Agent 因为搜索结果前后矛盾在搜索—总结—再搜索之间来回了 40 多轮直接把上下文 token 打爆。从那以后我给自己定了一条规矩任何 Agent 循环都必须具备至少四层刹车。最大轮数上限。全局硬限制一般任务 10 到 15 轮足够了复杂任务也不建议超过 30 轮。达到上限后强制收敛返回当前最优结果。Token 预算。以模型上下文窗口的某个比例比如 70%为阈值达到阈值后禁止再追加工具调用。重复动作检测。对最近 N 轮的工具调用参数做哈希如果发现完全相同的调用连续出现说明模型在无效循环应该中断。整段超时。不只是单次工具调用的超时而是整个 Loop 的总时长限制。比如一个任务最多执行 60 秒超时后直接返回部分结果或错误。实际实现时最好把这些参数做成可配置项并且按任务类型分别设置。比如一个查天气的 Agent 轮数上限设置成 5 轮就够了而一个深度调研的 Agent 可能需要 20 轮。硬编码在代码里后面调整一次要动一次版本很烦。class LoopController: def __init__(self, max_iterations12, max_total_tokens8000, timeout_sec60): self.max_iterations max_iterations self.max_total_tokens max_total_tokens self.timeout_sec timeout_sec self.iterations 0 def should_stop(self, state) - bool: if self.iterations self.max_iterations: return True if state.total_tokens self.max_total_tokens: return True if state.recent_actions_duplicated(n3): return True if state.elapsed_sec self.timeout_sec: return True return False这套刹车系统还有一个额外好处它让线上问题变得可解释。当一次任务异常结束时你一眼就能看出是因为达到轮数上限还是检测到重复动作而不是面对一个悬停的无响应进程。3.3 多窗口、多请求并发下的循环隔离Loop 在并发场景下最容易被忽略的问题是状态隔离。特别常见的是多窗口、多会话场景用户同时开着三个会话问问题如果所有请求共享同一个 Loop 运行实例上下文串了A 窗口的工具调用结果会被 B 窗口看到出现答非所问甚至信息泄漏。在工程上每个请求必须拥有独立的 Loop 实例这个实例里的中间状态比如历史消息、已用 token 数、当前步骤都只属于这一个请求。如果进程崩溃要能恢复Loop 的状态需要快照到 Redis 这类外部存储重启后从最近一个稳定快照继续跑。注意不要每轮都全量写入那样写入放大非常严重。我的做法是关键节点快照普通轮次靠日志重建。并发量的控制也要同步考虑。假设同一个用户的三个会话同时在跑每个会话都在高频调用模型 API系统的并发和成本都会快速上升。通常我会给单用户 Loop 并发数和全局 Loop 并发数分别做信号量限制超过阈值的请求进入排队。这一层如果不在 Loop 里做而是靠上游网关硬限流用户体验会很差因为所有请求会统一被拒。4. Graph从单线循环到工作流图编排解决的是依赖问题4.1 单线循环表达不了分支、并行与回退Loop 解决的是一个执行体反复推进的问题但很多真实任务并不是单线的。举个例子一个编写代码的 Agent 可能需要同时做三件事修改主模块、补单元测试、更新文档。这三件事彼此独立完全可以并行。但如果它们都塞进同一个 Loop 里模型只能串行处理先改代码再补测试再写文档整个过程慢且容易前后不一致。再比如线上环境常见的人工审批场景Agent 执行到提交合并请求这一步时可能需要等待人来点击确认然后才能继续下一步。这在 Loop 里很难优雅表达因为你总不能用sleep硬等。这些多分支并行扇出等待人工失败之后回退到上一阶段的语义天然属于图编排的范畴。这也是为什么你会看到类似 Graph Builder 的工具出现在各大 Agent 框架里某种意义上Graph 是 Agent 工作流从线性执行走向拓扑化的必然产物。它不取代 Loop而是把 Loop 当作图中的一个特殊节点让单个循环与整个工作流能够嵌套组合。4.2 图编排的最小建模节点、条件边与共享状态落地一个 Graph 编排层不需要一开始就整太多概念抓住三样东西就够。节点节点的粒度可以是一段提示词加工具调用的小任务也可以是一个完整的 Loop还可以是一个等待事件比如等人工审批。关键是一个节点只做一件事且有明确的输入输出。边边表达节点之间的流转关系。普通边表示前一个完成后直接进入下一个条件边表示根据上一个节点的输出决定走哪条分支。共享状态整个 Graph 运行期间的数据载体所有节点都能读写它。它是图编排的灵魂也是排查问题时最重要的观察对象。下面用一个简单的配置片段示意条件边的长相。不同框架有不同写法但核心语义大同小异nodes: - id: start type: entry - id: search_order type: loop loop: order_query_loop - id: check_permission type: gate - id: human_approval type: wait_human - id: final_reply type: completion edges: - from: start to: search_order - from: search_order to: check_permission - from: check_permission to: human_approval condition: state.need_approval true - from: check_permission to: final_reply condition: state.need_approval false如果看过 LangGraph 这类框架的实现就会发现它们内部的状态机本质就是这样的节点和边引擎。区别只在于引擎的抽象程度和状态持久化策略。4.3 落地时按需选择线性链、条件链、DAGGraph 也不是越复杂越好。我在实际项目里会把图编排的落地分成三个层次。第一层线性链。所有节点按顺序执行没有分支没有并行。这其实是退化成一条链的图很多数据清洗→检索→生成的流水线任务属于这一类。对于线性链用 Graph 的价值在于换来了可读性和可重试性每一步独立成节点单独重跑。第二层条件链。在关键节点后面加了条件边例如如果检索结果置信度低则追加一次追问如果用户身份是 VIP跳过排队直接进入人工。这种结构非常适合规则明确、分支有限的业务流程。第三层带环路的 DAG。支持并行扇出、扇入汇聚、人工审批、失败回退。这是真正的生产级编排适合复杂业务系统。但它的工程复杂度也最高并行节点之间的状态合并要处理冲突回退逻辑要小心别把状态绕成死结。我的建议是从线性链开始能不加分支就不加分文等真实业务流程迫使你增加并行和回退时再逐级升级。很多团队的失败不是 Graph 不好而是一上来就搭了一个非常复杂的图结果开发和排障的心智负担压垮了项目。Graph 应该是被业务需求逼出来的而不是为了技术炫技撑出来的。5. 生产环境三件套一次请求的完整旅程、并发与可观测性5.1 完整走一遍一次请求如何穿过三层把三层架构拼起来一次生产请求的完整旅程大致是这样的请求先进入网关网关带着用户身份信息找到对应的 Harness 实例。Harness 做两件事鉴权和工具过滤生成当前用户可见的工具列表。接着请求落到 Graph 调度器调度器读取外部存储中的图状态找到当前应该执行的起始节点。如果起始节点是一个需要模型推理的节点调度器就会启动一个 Loop。Loop 开始迭代模型生成下一步动作要么是普通文本要么是工具调用如果是工具调用就会回到 Harness 层执行鉴权和调用拿到结果后注入上下文模型继续下一次推理。每迭代一次Loop 会把最近的状态写入图状态如果图配置了条件边调度器会在 Loop 结束后根据状态决定下一个节点是正常流转还是跳到人工审批。最后所有节点完成统一走 Harness 的日志输出链路做一次整体脱敏生成响应返回给用户。整个过程中三层各司其职Harness 管边界和观测Loop 管单点推进Graph 管全局流转。状态存放的职责也很清晰Harness 本身无状态Loop 持有临时运行状态Graph 持有任务级持久状态。5.2 扛并发真正的三个瓶颈有句话很直白Agent 的并发问题大部分不是计算问题而是协调问题。 模型 API 的限流、外部工具的抖动、状态存储的写入放大这三个瓶颈几乎决定了一个 Agent 服务能在多大并发下站稳。第一个瓶颈是模型 API 限流。同一时刻 100 个 Loop 在跑每个 Loop 每轮都在调模型接口放眼望去全是 429。解决思路是用信号量或令牌桶做本地排队配合平滑的退避重试策略而不是把压力全部抛给模型服务。这里有一个很容易踩的坑重试要考虑全局并发如果一个请求的多个 Loop 节点都按自己的退避算法重试重试峰值会叠加反而把模型服务打挂。第二个瓶颈是外部工具依赖抖动。Agent 比普通接口更容易被下游服务拖累因为一个任务可能依赖五六次工具调用任何一次慢查询都会被放大。处理办法是每个工具调用独立超时加上降级方案。比如订单服务不可用时模型可以基于已有缓存信息先回应用户再异步补齐准确数据。第三个瓶颈是状态存储写入放大。Graph 每经过一个节点就写一次状态高并发下存储很快成为瓶颈。解决思路有两个方向一是把频繁更新的状态做成内存快照只在关键节点落地持久化二是采用事件溯源的方式只记录状态变更事件而不是每次写全量快照。5.3 全链路可观测性把三层串进一条 trace生产环境出了问题最怕的是定位不到是哪一层出的问题。我的习惯是让同一条 trace_id 贯穿 Harness、Loop、Graph 三层并且约定好日志格式。Graph 层记录节点 start/end 和小状态迁移Loop 层记录每次迭代的 iteration_id、本轮推理的 token 数、工具调用耗时Harness 层记录每次工具调用的入参、出参摘要、鉴权结果。这样当用户反馈Agent 回答错误的时候你能顺着 trace 找到确切是哪一轮迭代、模型调了哪个工具、拿到了什么结果以及这个结果为什么让模型做出了错误判断。成本统计也建议在这一层一起做。每次迭代的模型 token 消耗、延迟、费用按节点、按用户聚合是判断系统是否值得继续优化的重要数据。我在线上见过的情况是一次任务因为 Loop 反复尝试成本比预期高出 3 倍如果没有可观测性数据这个问题根本不会有人发现。6. 落地的取舍什么场景只配 Loop什么场景必须上 Graph6.1 什么时候该满足于 Loop什么时候必须上 Graph先给一个判据如果你的流程可以画成一条线那就用 Loop只有当它画成线会显得非常别扭时再上 Graph。单任务、单工具链、线性步骤Loop 完全够用。硬上 Graph 只会增加配置复杂度让简单任务读起来像天书。反过来当出现以下迹象时是时候引入 Graph 了出现多个可并行的子任务流程中存在条件路由需要等待人工审批一个任务可能要从失败节点回退重跑多个 Agent 之间需要协作交接。这些情况用 Loop 硬撑代码里会塞满全局标志位和回调函数维护成本远高于 Graph 的成本。6.2 过度设计的两个典型信号第一个信号是给 Graph 强行加了状态机用不到的分支。如果你画出来的 Graph 本质上还是一条直线那 Graph 并没有带来额外价值反而让新接手的人困惑为什么这里要跳过一个节点直接到那里明明可以顺序走。第二个信号是把业务逻辑搬到 Harness 里。Harness 是约束和观测层不是业务逻辑层。有的团队把业务规则、账号体系、审批流程全部塞进 Harness结果 Harness 变成一个内部相互咬合、谁也不敢动的巨型模块。正确的做法是Harness 保持薄只做通用的鉴权、限流、审计业务规则放在 Graph 的节点中由工作流来表达。6.3 最后一点工程心得如果让我给一个刚起步的 Agent 项目提建议我会说先把 Harness 打好再考虑 Loop 的刹车最后才用 Graph 编排。顺序不要反。Harness 的安全边界没做扎实就急着上并发和编排后面每个模块都会返工。此外把 Loop 的轮数上限、超时时间、token 预算全部做成配置项按任务类型动态调整这一个小小的设计能让你在线上少救很多次火。工作流图也要养成先画出来给同事看的习惯如果一张图别人花五分钟看不明白那它上线维护时一定会出事。这三层架构与其说是一套框架不如说是一种把 Agent 当作受控系统的工程态度。坚持这个态度你的 Agent 项目大概率不会从 demo 到生产就崩塌而是能一步步长成真正扛得住业务压力的系统。
做 Agent 开发有一段时间的朋友应该都有同感Agent 这个词被塞进了太多含义。有人说的 Agent 是那个会自己调工具的模型有人说的是把模型包起来的 Harness还有人说的是后台那张由 Loop 和 Graph 共同构成的工作流图。等真正进入生产阶段这三层要是没在架构上掰扯清楚几乎一定会出现同一种症状——单跑一次请求感觉一切正常一上并发、一接外部系统整个状态就彻底失控排查起来根本无从下手。这篇文章想聊的正是 Agent 工程里三条最关键的主线Harness、Loop、Graph。你可以把它们分别理解为运行边界、执行循环、流程编排这也是绝大多数成熟 Agent 项目在事实上的分层方式。无论你是在用 LangChain/LangGraph 这类现成框架还是基于 Rust、Go 自研 Agent 底座这三层的边界划分基本决定了你的代码最终是能上线的工程还是只能跑的 demo。这篇内容适合正在做 Agent 开发、面临框架选型或者被线上并发和问题排查折磨的开发者与架构师参考。1. 从调 API到做工程Agent 项目的三层边界到底划在哪1.1 一个看似正常的 Agent 为什么会悄悄失控先说个很典型的场景。你花一个下午用提示词加 function calling 做出了一个客服 Agent演示时它表现得非常好用户问我的订单到哪了它调起查询工具拿到物流信息组织一段话回复。一切看起来天衣无缝。可一旦这个 Agent 要接入真实业务麻烦立刻出现。第一不是所有用户都有权限查所有订单你得在模型调用工具之前做身份和权限校验第二用户可能会继续追问那什么时候能送到能不能改地址模型需要反复查询、确认、再查询这就不是一个单次推理能解决的事第三订单信息可能分散在订单系统、仓储系统、物流系统三个地方模型需要并行拉取再汇总中间还可能要等待人工审核。等你把这些需求一个个用 if-else 和回调堆进去代码就会变成一团谁都理不清的乱麻。这个例子其实暴露了 Agent 工程的本质问题你不能把 Agent 当作一个更强的 API来用而必须当作一个需要被约束、被驱动、被编排的系统来设计。约束它的是 Harness驱动它的是 Loop编排它的是 Graph。这三层在 demo 阶段可以完全混在一起但在生产阶段必须各司其职。1.2 三层职责的划分逻辑横切线、时间线与全局图为了把这三层的关系说清楚我喜欢用一个新员工入职的类比。Harness 是公司给员工配的工位、门禁和权限。它决定了这名员工能进哪些房间、能碰哪些系统、报销额度是多少、操作哪些事情需要走审批。在 Agent 工程里Harness 就是模型外部的约束框架负责管住它能做什么、不能做什么、能调哪些资源。模型本身再聪明也必须在 Harness 划定的边界内行动。Loop 是员工接到任务后的日常节奏。开会理解目标、动手干活、中途汇报进展、根据反馈调整方向、再继续干直到任务完成。对应到 Agent 工程里Loop 就是这个员工模型代理的节拍器决定它如何在推理—行动—观察之间循环推进。Graph 是整个项目的流程图。它描述的是任务从哪个环节开始、做完一步之后流转到哪里、什么条件下可以并行、什么条件下需要等待人工确认。对应到 Agent 工程里Graph 是多个步骤、多个子任务之间的全局拓扑关系。从维度上看Harness 是横切面贯穿所有环节Loop 是时间线管单个执行体如何迭代Graph 是全局图管多个执行体如何协作。这三层不是互相替代的关系而是叠加的关系。把这三句话记在脑子里后面所有的设计都不会跑偏。2. Harness模型的缰绳先管住工具和权限再谈智能2.1 Harness 不等于 Agent谁在思考谁在约束最近社区里讨论热度很高的 DeepSeek Harness 这类插件以及各路以 harness 命名的开源项目让很多人产生了一个困惑Harness 难道就是 Agent 本身吗其实不是。Harness 这个词最早来源于测试领域的 test harness指的是被测系统之外的一套支持装置负责给被测系统喂数据、模拟环境、收集结果。在 Agent 工程里它的角色被扩展了模型是被测系统Harness 是模型之外那层支持、约束、观测的脚手架。模型负责思考Harness 负责提供思考所需的工具、限制思考能触碰的边界、记录思考留下的痕迹。我见过不少团队把这两者混为一谈结果就是给 Agent 写了一大堆工具调用代码而不是给 Agent 配一个 Harness。两者的差别很大前者是把工具逻辑直接塞给模型模型想调就调后者是在模型和工具之间加了一道闸门每次调用都必须经过授权、超时、审计。看似只是多了一个中间层但生产环境下的安全性、可控性和排查能力全在这个中间层里。2.2 一个合格 Harness 里必须常驻的三类能力具体到落地一个生产级的 Harness 至少要包含三类东西。第一工具注册表与权限模型。不要把所有 function 的 schema 一股脑丢给模型。应该按服务、按账号粒度声明工具名称、入参结构、可见范围。模型可见的工具列表应该是 Harness 根据当前请求的身份动态生成的。用户没权限查的订单对应工具根本不该出现在模型的选项里。这样做既省 token又从源头杜绝了越权调用。第二上下文与记忆管理。系统提示词、工具返回结果、历史对话窗口的裁剪都是 Harness 的职责。它决定模型当前能看到什么。这块要特别注意 token 预算假设上下文窗口是 128kHarness 应该在每次循环前估算已有 token 占用给模型推理留出合理余量而不是等满了才截断。第三审计与操作日志。每次工具调用的入参、出参摘要、耗时、成功失败状态都要记录。注意这里不能只记最终回复否则线上出问题你根本不知道是哪次工具调用给了模型错误信息。日志还要在 Harness 层做脱敏手机号、身份证号这些不能原样落盘。下面是一个比较基础的 Python 风格 Harness 骨架重点看工具调用前校验这个流程class Harness: def __init__(self, user_ctx, tool_registry): self.user_ctx user_ctx # 当前用户身份 self.tools self._filter_tools(tool_registry, user_ctx) def _filter_tools(self, registry, user_ctx): # 根据用户角色过滤可见工具越权工具直接不下发 return [t for t in registry if t.allowed_roles user_ctx.roles] def call_tool(self, name, args): if name not in self.tools: raise PermissionError(ftool {name} not allowed) with tracer.start_span(ftool.{name}) as span: span.set_attribute(args, json.dumps(args, ensure_asciiFalse)[:500]) result invoke_tool(name, args, timeout5) span.set_attribute(result, summarize(result)) return result这段代码要说明的核心是模型不直接触碰工具所有调用都经由 Harness 的 call_tool校验、埋点、超时都在这一层统一处理。2.3 上生产前给 Harness 定下的三条铁律最小权限原则。模型申请调用某个工具时授权范围要精确到具体的操作和具体的资源范围宁可先给窄再放开也不要一开始就全量开放。所有外部调用必须有超时和熔断。工具服务不稳定是常态如果一次工具调用能挂起 30 秒你的 Loop 会被它拖死连带拖垮整个请求队列。超时时间建议控制在 3 到 5 秒失败后给模型返回明确的结构化错误信息让模型有机会换一条路。Harness 保持无状态。Harness 这一层不要存业务状态它只负责执行时的约束和观测。所有要跨请求保留的东西放进外部存储。这一点对水平扩展至关重要否则你会有状态分片和粘性会话的双重麻烦。有人在搭建自研底座时通常会把 Harness 做成插件化的能力集合外部系统通过描述文件把工具、权限、校验逻辑注册进来类似一种即插即用的结构。这也是为什么大家看到以 Harness 命名的插件时会本能地意识到它不是模型能力而是工程能力的外化。3. Loop给 Agent 装上节拍器让循环推进有始有终3.1 四种主流的 Agent 循环形态Loop 是整个 Agent 系统中离模型最近的一层也是最容易写出 bug 的一层。因为循环这种结构天然有跑飞的可能。先看四种常见形态。循环形态核心逻辑典型适用场景主要风险单轮推理模型一次生成回答不调用工具纯问答、知识库检索无法完成任务类事项ReAct 循环思考Thought→ 行动Action→ 观察Observation→ 再思考需要多步工具调用的任务容易陷入反复尝试、不收敛Plan-Execute先写计划再按计划逐条执行复杂任务拆解比如数据分析、报告生成计划一旦错误后续全错带评价的循环每轮执行后用评价器打分低于阈值则重试代码生成、内容创作、需要质量兜底的任务评价逻辑本身不稳定会抖动可以把 ReAct 循环看作是所有形式的基础模型先想一步然后调用工具或输出内容拿到工具结果或环境反馈再决定下一步干什么。Plan-Execute 和带评价的循环本质上是在 ReAct 的某些位置插入额外的控制逻辑。3.2 循环的刹车系统终止条件与死循环防护给 Agent 写个while True是非常危险的就算是最简单的对话任务模型也可能因为提示词里的模棱两可永远追问下去。我线上踩过的坑是某个搜索 Agent 因为搜索结果前后矛盾在搜索—总结—再搜索之间来回了 40 多轮直接把上下文 token 打爆。从那以后我给自己定了一条规矩任何 Agent 循环都必须具备至少四层刹车。最大轮数上限。全局硬限制一般任务 10 到 15 轮足够了复杂任务也不建议超过 30 轮。达到上限后强制收敛返回当前最优结果。Token 预算。以模型上下文窗口的某个比例比如 70%为阈值达到阈值后禁止再追加工具调用。重复动作检测。对最近 N 轮的工具调用参数做哈希如果发现完全相同的调用连续出现说明模型在无效循环应该中断。整段超时。不只是单次工具调用的超时而是整个 Loop 的总时长限制。比如一个任务最多执行 60 秒超时后直接返回部分结果或错误。实际实现时最好把这些参数做成可配置项并且按任务类型分别设置。比如一个查天气的 Agent 轮数上限设置成 5 轮就够了而一个深度调研的 Agent 可能需要 20 轮。硬编码在代码里后面调整一次要动一次版本很烦。class LoopController: def __init__(self, max_iterations12, max_total_tokens8000, timeout_sec60): self.max_iterations max_iterations self.max_total_tokens max_total_tokens self.timeout_sec timeout_sec self.iterations 0 def should_stop(self, state) - bool: if self.iterations self.max_iterations: return True if state.total_tokens self.max_total_tokens: return True if state.recent_actions_duplicated(n3): return True if state.elapsed_sec self.timeout_sec: return True return False这套刹车系统还有一个额外好处它让线上问题变得可解释。当一次任务异常结束时你一眼就能看出是因为达到轮数上限还是检测到重复动作而不是面对一个悬停的无响应进程。3.3 多窗口、多请求并发下的循环隔离Loop 在并发场景下最容易被忽略的问题是状态隔离。特别常见的是多窗口、多会话场景用户同时开着三个会话问问题如果所有请求共享同一个 Loop 运行实例上下文串了A 窗口的工具调用结果会被 B 窗口看到出现答非所问甚至信息泄漏。在工程上每个请求必须拥有独立的 Loop 实例这个实例里的中间状态比如历史消息、已用 token 数、当前步骤都只属于这一个请求。如果进程崩溃要能恢复Loop 的状态需要快照到 Redis 这类外部存储重启后从最近一个稳定快照继续跑。注意不要每轮都全量写入那样写入放大非常严重。我的做法是关键节点快照普通轮次靠日志重建。并发量的控制也要同步考虑。假设同一个用户的三个会话同时在跑每个会话都在高频调用模型 API系统的并发和成本都会快速上升。通常我会给单用户 Loop 并发数和全局 Loop 并发数分别做信号量限制超过阈值的请求进入排队。这一层如果不在 Loop 里做而是靠上游网关硬限流用户体验会很差因为所有请求会统一被拒。4. Graph从单线循环到工作流图编排解决的是依赖问题4.1 单线循环表达不了分支、并行与回退Loop 解决的是一个执行体反复推进的问题但很多真实任务并不是单线的。举个例子一个编写代码的 Agent 可能需要同时做三件事修改主模块、补单元测试、更新文档。这三件事彼此独立完全可以并行。但如果它们都塞进同一个 Loop 里模型只能串行处理先改代码再补测试再写文档整个过程慢且容易前后不一致。再比如线上环境常见的人工审批场景Agent 执行到提交合并请求这一步时可能需要等待人来点击确认然后才能继续下一步。这在 Loop 里很难优雅表达因为你总不能用sleep硬等。这些多分支并行扇出等待人工失败之后回退到上一阶段的语义天然属于图编排的范畴。这也是为什么你会看到类似 Graph Builder 的工具出现在各大 Agent 框架里某种意义上Graph 是 Agent 工作流从线性执行走向拓扑化的必然产物。它不取代 Loop而是把 Loop 当作图中的一个特殊节点让单个循环与整个工作流能够嵌套组合。4.2 图编排的最小建模节点、条件边与共享状态落地一个 Graph 编排层不需要一开始就整太多概念抓住三样东西就够。节点节点的粒度可以是一段提示词加工具调用的小任务也可以是一个完整的 Loop还可以是一个等待事件比如等人工审批。关键是一个节点只做一件事且有明确的输入输出。边边表达节点之间的流转关系。普通边表示前一个完成后直接进入下一个条件边表示根据上一个节点的输出决定走哪条分支。共享状态整个 Graph 运行期间的数据载体所有节点都能读写它。它是图编排的灵魂也是排查问题时最重要的观察对象。下面用一个简单的配置片段示意条件边的长相。不同框架有不同写法但核心语义大同小异nodes: - id: start type: entry - id: search_order type: loop loop: order_query_loop - id: check_permission type: gate - id: human_approval type: wait_human - id: final_reply type: completion edges: - from: start to: search_order - from: search_order to: check_permission - from: check_permission to: human_approval condition: state.need_approval true - from: check_permission to: final_reply condition: state.need_approval false如果看过 LangGraph 这类框架的实现就会发现它们内部的状态机本质就是这样的节点和边引擎。区别只在于引擎的抽象程度和状态持久化策略。4.3 落地时按需选择线性链、条件链、DAGGraph 也不是越复杂越好。我在实际项目里会把图编排的落地分成三个层次。第一层线性链。所有节点按顺序执行没有分支没有并行。这其实是退化成一条链的图很多数据清洗→检索→生成的流水线任务属于这一类。对于线性链用 Graph 的价值在于换来了可读性和可重试性每一步独立成节点单独重跑。第二层条件链。在关键节点后面加了条件边例如如果检索结果置信度低则追加一次追问如果用户身份是 VIP跳过排队直接进入人工。这种结构非常适合规则明确、分支有限的业务流程。第三层带环路的 DAG。支持并行扇出、扇入汇聚、人工审批、失败回退。这是真正的生产级编排适合复杂业务系统。但它的工程复杂度也最高并行节点之间的状态合并要处理冲突回退逻辑要小心别把状态绕成死结。我的建议是从线性链开始能不加分支就不加分文等真实业务流程迫使你增加并行和回退时再逐级升级。很多团队的失败不是 Graph 不好而是一上来就搭了一个非常复杂的图结果开发和排障的心智负担压垮了项目。Graph 应该是被业务需求逼出来的而不是为了技术炫技撑出来的。5. 生产环境三件套一次请求的完整旅程、并发与可观测性5.1 完整走一遍一次请求如何穿过三层把三层架构拼起来一次生产请求的完整旅程大致是这样的请求先进入网关网关带着用户身份信息找到对应的 Harness 实例。Harness 做两件事鉴权和工具过滤生成当前用户可见的工具列表。接着请求落到 Graph 调度器调度器读取外部存储中的图状态找到当前应该执行的起始节点。如果起始节点是一个需要模型推理的节点调度器就会启动一个 Loop。Loop 开始迭代模型生成下一步动作要么是普通文本要么是工具调用如果是工具调用就会回到 Harness 层执行鉴权和调用拿到结果后注入上下文模型继续下一次推理。每迭代一次Loop 会把最近的状态写入图状态如果图配置了条件边调度器会在 Loop 结束后根据状态决定下一个节点是正常流转还是跳到人工审批。最后所有节点完成统一走 Harness 的日志输出链路做一次整体脱敏生成响应返回给用户。整个过程中三层各司其职Harness 管边界和观测Loop 管单点推进Graph 管全局流转。状态存放的职责也很清晰Harness 本身无状态Loop 持有临时运行状态Graph 持有任务级持久状态。5.2 扛并发真正的三个瓶颈有句话很直白Agent 的并发问题大部分不是计算问题而是协调问题。 模型 API 的限流、外部工具的抖动、状态存储的写入放大这三个瓶颈几乎决定了一个 Agent 服务能在多大并发下站稳。第一个瓶颈是模型 API 限流。同一时刻 100 个 Loop 在跑每个 Loop 每轮都在调模型接口放眼望去全是 429。解决思路是用信号量或令牌桶做本地排队配合平滑的退避重试策略而不是把压力全部抛给模型服务。这里有一个很容易踩的坑重试要考虑全局并发如果一个请求的多个 Loop 节点都按自己的退避算法重试重试峰值会叠加反而把模型服务打挂。第二个瓶颈是外部工具依赖抖动。Agent 比普通接口更容易被下游服务拖累因为一个任务可能依赖五六次工具调用任何一次慢查询都会被放大。处理办法是每个工具调用独立超时加上降级方案。比如订单服务不可用时模型可以基于已有缓存信息先回应用户再异步补齐准确数据。第三个瓶颈是状态存储写入放大。Graph 每经过一个节点就写一次状态高并发下存储很快成为瓶颈。解决思路有两个方向一是把频繁更新的状态做成内存快照只在关键节点落地持久化二是采用事件溯源的方式只记录状态变更事件而不是每次写全量快照。5.3 全链路可观测性把三层串进一条 trace生产环境出了问题最怕的是定位不到是哪一层出的问题。我的习惯是让同一条 trace_id 贯穿 Harness、Loop、Graph 三层并且约定好日志格式。Graph 层记录节点 start/end 和小状态迁移Loop 层记录每次迭代的 iteration_id、本轮推理的 token 数、工具调用耗时Harness 层记录每次工具调用的入参、出参摘要、鉴权结果。这样当用户反馈Agent 回答错误的时候你能顺着 trace 找到确切是哪一轮迭代、模型调了哪个工具、拿到了什么结果以及这个结果为什么让模型做出了错误判断。成本统计也建议在这一层一起做。每次迭代的模型 token 消耗、延迟、费用按节点、按用户聚合是判断系统是否值得继续优化的重要数据。我在线上见过的情况是一次任务因为 Loop 反复尝试成本比预期高出 3 倍如果没有可观测性数据这个问题根本不会有人发现。6. 落地的取舍什么场景只配 Loop什么场景必须上 Graph6.1 什么时候该满足于 Loop什么时候必须上 Graph先给一个判据如果你的流程可以画成一条线那就用 Loop只有当它画成线会显得非常别扭时再上 Graph。单任务、单工具链、线性步骤Loop 完全够用。硬上 Graph 只会增加配置复杂度让简单任务读起来像天书。反过来当出现以下迹象时是时候引入 Graph 了出现多个可并行的子任务流程中存在条件路由需要等待人工审批一个任务可能要从失败节点回退重跑多个 Agent 之间需要协作交接。这些情况用 Loop 硬撑代码里会塞满全局标志位和回调函数维护成本远高于 Graph 的成本。6.2 过度设计的两个典型信号第一个信号是给 Graph 强行加了状态机用不到的分支。如果你画出来的 Graph 本质上还是一条直线那 Graph 并没有带来额外价值反而让新接手的人困惑为什么这里要跳过一个节点直接到那里明明可以顺序走。第二个信号是把业务逻辑搬到 Harness 里。Harness 是约束和观测层不是业务逻辑层。有的团队把业务规则、账号体系、审批流程全部塞进 Harness结果 Harness 变成一个内部相互咬合、谁也不敢动的巨型模块。正确的做法是Harness 保持薄只做通用的鉴权、限流、审计业务规则放在 Graph 的节点中由工作流来表达。6.3 最后一点工程心得如果让我给一个刚起步的 Agent 项目提建议我会说先把 Harness 打好再考虑 Loop 的刹车最后才用 Graph 编排。顺序不要反。Harness 的安全边界没做扎实就急着上并发和编排后面每个模块都会返工。此外把 Loop 的轮数上限、超时时间、token 预算全部做成配置项按任务类型动态调整这一个小小的设计能让你在线上少救很多次火。工作流图也要养成先画出来给同事看的习惯如果一张图别人花五分钟看不明白那它上线维护时一定会出事。这三层架构与其说是一套框架不如说是一种把 Agent 当作受控系统的工程态度。坚持这个态度你的 Agent 项目大概率不会从 demo 到生产就崩塌而是能一步步长成真正扛得住业务压力的系统。
