说实话做Agent项目最怕的不是模型不聪明而是工程结构撑不住。前几个月我接手一个多工具协作的Agent应用代码写了一两千行所有逻辑都塞在一个while循环里调用链一长就开始乱——工具参数错配、上下文爆炸、循环终止条件被模型无视出了问题根本不知道是该查模型、查工具还是查编排。后来我用Harness、Loop、Graph这三层架构把整个系统重新拆了一遍才发现原来很多问题在架构层面就能提前消灭。这篇文章把我实践中的拆解思路、核心实现和踩坑记录梳理出来给正在做Agent工程化、或者在犹豫要不要把Agent从脚本升级成系统的同学一个参考。1. 三层架构的整体设计与思想拆解1.1 单体Agent为什么会失控先还原一下最原始的Agent写法一个while循环里套两步——把历史消息丢给大模型拿到工具调用请求后执行工具再把结果追加回消息列表。逻辑上没错但一旦工具数量超过十个、任务链路超过五步问题就开始冒出来。第一个坑是工具管理。所有工具都堆在一个列表里靠模型自己去选。工具一多同名参数、相似描述、权限差异全变成噪声模型开始选错工具、传错参数而且毫无规律。第二个坑是循环的终止条件是软的。你告诉模型完成后输出FINAL它可能提前收工也可能一直循环下去。唯一的兜底是max_iterations而max_iterations设大了浪费token设小了任务完不成。第三个坑是状态隔离。多个用户同时在用同一个Agent实例跑任务消息列表一旦串了A的任务结果就可能出现在B的上下文里。当时我们排障的流程也很痛苦。工具返回了错误得先看是不是模型理解错再看是不是工具内部崩了最后还要看是不是循环里的状态传递搞坏了数据。每一步都要翻日志翻完一轮下来半天没了。单体结构最大的问题就是职责不分模型调用、工具执行、流程控制、状态管理全部糅在一起任何一环出问题整个系统都跟着遭殃。1.2 三层架构的职责划分拆解之后我把Agent运行时的职责分成了三条线Harness装备层管执行者能用什么和怎么安全地用。负责工具注册、参数绑定、上下文管理、会话快照、权限与沙箱隔离。Loop运行层管Agent怎么持续干活。负责推理与行动的循环调度、终止条件判断、重试策略、并发控制。Graph编排层管先做什么、后做什么、哪些可以并行。负责工作流的节点编排、条件路由、分支合并、人工介入。三者各管一段互不越界。Harness不关心流程怎么走Loop不知道工具的具体细节Graph只定义节点之间的依赖关系。这样拆下来每个层次都能独立测试。我打过一个比方Harness是厨房里的锅碗瓢盆和食材Loop是厨师的做菜流程洗、切、炒、尝、调整Graph是今天这一桌宴席的菜单和上菜顺序。厨具坏了不影响菜单菜单变了也不需要换厨具。1.3 为什么现在才需要这么拆单轮工具调用时代不需要这套架构。那时候模型一次返回一个工具调用执行完就结束本质是增强版的函数调用。但多步骤Agent出现后模型要自己决定调几次工具、调完要不要继续思考甚至是多个模型协作完成一个任务这就必须有Loop和Graph。我见过很多团队还在用一个循环打天下的思路做Agent结果就是代码越写越厚最后变成一座没人敢动的屎山。分层不是制造复杂性而是把复杂性关进笼子里。Graph管流程的复杂性Loop管决策的复杂性Harness管系统集成的复杂性。每一层都可以单独演进、单独降级。2. Harness层装备箱与执行底座2.1 Harness具体在管什么Harness这层最容易被低估。很多人觉得工具不就是一堆函数吗注册一下就行。实际上Harness承担了四大职责。工具注册与Schema管理。每个工具要有名称、描述、参数Schema、执行函数、超时时间、权限标记。Schema写得好不好直接影响模型选工具的准确率。描述写得含糊模型就会拿A工具干B工具的活。上下文管理与窗口控制。大模型输入窗口有限Harness要负责把历史消息、工具返回、系统提示按优先级裁剪压缩。我在项目里给Harness加了一个token预算机制系统提示占多少、历史消息占多少、工具返回占多少超出预算自动压缩。会话快照与恢复。Agent跑到一半崩溃了能不能从上一个稳定状态恢复Harness里我实现了checkpoint机制把消息列表、工具调用记录、临时状态定期落盘。后面Loop层循环中断了可以从快照拉起。安全的工具调用边界。工具执行时不该让Agent碰的东西文件系统敏感目录、真实支付接口、生产库都要在Harness里做白名单拦截。这不是不信任模型是防止prompt injection或者模型误操作带来事故。2.2 工具加载与插件机制工具多了以后不能全写死在代码里得设计成插件式加载。每一个插件包包含工具定义、执行模块、依赖声明。加载器扫描插件目录读取清单文件按依赖顺序逐个加载。这里就有个很常见的报错harness failed to load plugins。我在好几个项目里都遇到过原因不外乎三类插件清单里声明的入口文件路径不对插件的依赖包没装全或者版本不匹配多个插件之间的依赖顺序没声明加载时A插件依赖B插件B还没来得及加载。我踩过一次比较典型的坑装了一个工具的v2版本它的新API已经弃用了另一个插件还在用的老接口。单独加载都没问题放在一起加载后面的插件直接报初始化失败。排查了半天最后是通过对比插件依赖树才找到版本冲突。我的建议是插件加载顺序不要靠运气要显式声明依赖关系加载器根据依赖做一次拓扑排序。同时插件启停要做成配置项而不是改代码。这样生产环境可以做到不改一行代码就动态调整工具集合。2.3 Harness的沙箱与部署实践Harness不只是管理工具还要决定这些工具跑在什么样的环境里。工具执行不是无代价的至少要考虑两件事隔离性和可观测性。隔离性方面我会把高风险工具放进沙箱容器限制CPU、内存、网络。Agent如果被诱导去执行一段恶意脚本沙箱能挡住大部分破坏。网上经常看到codex无法发送消息显示更新agent沙盒其实也是这个逻辑——旧沙盒环境升级后通信方式和策略变了老请求自然就失效。遇到这种问题第一件事是看当前请求有没有走新的沙箱通道。部署方面内网环境是很多团队的刚需。之前做企业项目时要求所有模型调用和工具包都不能走外部服务只能在内网服务器上完成。做法是模型服务本地化部署插件包和工具依赖全部离线打包。这里有个小细节离线环境下插件不要用运行时联网拉依赖应该在构建阶段就把所有依赖打进产物包里否则内网一装插件就会因为缺依赖启动失败。另外我试过在桌面端做一些本地Agent工具比如把本地笔记库、文档库接进Harness让Agent能检索个人知识库。配置的核心就是给Harness配好本地服务地址和访问凭证再声明好哪些目录是只读的。整体思路其实和服务器端Harness没区别。3. Loop层Agent的运行循环与状态机3.1 Agent循环到底在循环什么Loop层解决的核心问题是让Agent在一个任务上持续地观察→思考→行动→再观察直到任务收敛。它关心的是循环本身怎么转、什么时候停、转不动怎么办。最经典的循环范式是ReAct。流程是模型基于当前状态决定下一步动作执行动作后观察结果再把结果重新作为输入给模型。这个循环很像一个厨师做菜看菜谱观察→决定放多少盐思考→放盐尝一口行动观察→决定要不要再调整。核心是每次循环都要产出新的有效信息否则就是在空转。我做了多少个步骤才合适这没有一个标准答案但框架上可以抽象成while not should_terminate(state): action model.decide(state) # 思考 if action.type final_answer: break result harness.execute(action) # 行动 state state.update(action, result) # 观察并更新状态这里的关键是state不能被无限撑大。我见过一个项目把每一步的工具返回都完整保存在state里跑了十几步之后光历史就占掉几千个token后面的模型调用每次都要重新处理一遍这些内容速度越来越慢成本越来越高。Loop层必须管好状态压缩只保留对后续决策有用的关键结果而不是保留全部原始输出。3.2 循环终止与安全兜底很多Agent跑到失控都是终止条件太软。只靠模型觉得自己干完了来停等于把系统稳定性寄托在模型的自觉上。我在架构里把终止条件写成了五道闸模型显式输出结束标记达到最大步骤上限总token消耗超预算单步执行超时连续多步无实质性进展比如反复调同一个工具、返回结果几乎不变。后面这个无进展检测很关键。有个真实案例Agent在做一个数据整理任务时连续四步都在搜索同一个关键词返回结果也一样但它一直不停下来总结。我们加了无进展检测之后连续两步产出相似度超过阈值就直接强制收敛让模型进入总结阶段。这一步省下了大量无效token。还有一个常见报错agent execution terminated due to error。看到这个错误先别急着重跑要查是什么动作触发了终止。我的经验是它往往意味着某个工具抛了未被捕获的异常Loop层把异常当成了终止信号。正确的做法是在执行单个工具时捕获所有异常把错误信息返回给模型去自我修正而不是直接终止整个循环。3.3 并发与资源治理AI Agent怎么扛并发这个问题我经常被问到。Agent的并发模型和普通Web服务不一样一次Agent任务可能持续几十秒甚至几分钟期间要多次调用模型API还要执行多个工具。最简单的方案是asyncio协程加共享Harness实例。每个任务维护自己的state和上下文但工具执行框架是共享的。这种方式扛得住中等并发前提是模型API的并发配额跟得上。另一种是进程池隔离每个Agent任务分配一个独立进程适合工具执行很重、容易互相影响的场景代价是内存开销大。真正的瓶颈通常不在Agent框架本身而在下游模型API限流、工具服务负载、数据库连接数。我在项目里给Loop层加了一个令牌桶限流器模型调用按配额排队避免瞬间打爆API。同时给每个Agent任务分配了独立的日志文件并发一高没有隔离日志根本没法排障。3.4 循环里的状态一致性问题状态管理在Loop层还有一个隐藏雷区循环引用。搜索引擎一搜就有一堆类似self referencing loop detected的报错Agent工程里也常常出现类似的问题只是表现形态不同。我遇到过一个案例某个工具的返回值里包含了一个临时文件路径我们把这个路径直接塞给了下一个清理工具而清理工具的返回结果又包含同一个路径导致循环里不断拿着同一个路径去执行清理动作。表面上是工具设计问题本质上是state里存在自我引用——数据血缘没理清。解法是给每个state字段打上来源标记是用户输入、模型生成、还是工具返回。Loop层在更新state时如果发现某个字段的来源已经在链路上出现过一次以上就停下来检查是否需要截断。这种防御看起来多此一举但生产环境里能挡住不少诡异故障。4. Graph层从单线流程到多分支编排4.1 为什么单条Loop不够用Loop解决的是一条道走到黑的流程但现实任务往往有分支。举个例子Agent执行某个代码任务写完代码先让静态检查工具过一遍检查不过要走修复分支修复完再回到检查检查过了才进入测试分支。这种带条件和回环的流程用纯粹的循环写起来会非常别扭。还有多Agent协作场景一个Agent负责规划任务拆解两个子Agent并行执行不同模块完成后由汇总Agent做整合。这种fan-out/fan-in的结构本质上就是一张图。Graph层的价值在于把流程变成显式的数据。节点是任务步骤边是依赖关系条件边是分支逻辑。流程一旦变成数据就可以做可视化、单元测试、持久化和版本管理。这也是为什么很多成熟的编排框架都会把流程定义和业务逻辑分开。4.2 Graph构建器的核心设计我是在做了两个项目后才意识到Graph构建器的重要性的。当时我们用了一套可视化流程搭建工具类似snap graph builder的思路拖拽节点、连线、设置条件画完图直接生成可执行的流程定义。好处是产品同学也能看懂流程坏处是一旦节点职责划分不清图会变成一张蜘蛛网。设计Graph时应该关注四类元素。节点是最小的执行单元粒度要适可而止。边决定了执行依赖有顺序执行和条件执行两种。全局状态是节点之间传递数据的公共通道。条件路由根据某个状态字段的值决定下一次走哪个节点。graph ( GraphSpec() .add_node(analyze, analyze_task) .add_node(fix, fix_error) .add_node(summary, summarize_result) .add_conditional_edge(analyze, fix, whenlambda s: s.error_count 0) .add_edge(fix, analyze) .add_edge(analyze, summary, whenlambda s: s.error_count 0) )这里面最容易出错的是状态字段的读写。我见过一个团队把整个大字典塞给每个节点节点A改了一个字段节点B拿到后完全不知道这个字段是从哪来的。后来我们把节点之间的接口改成了显式声明每个节点在进入前声明自己需要读哪些字段退出前声明自己会写哪些字段。这样Graph在运行时可以做校验流程也更可控。4.3 生产级Graph的可靠工程Graph层落地的关键不只是能跑通happy path而是要让流程在出错时也有明确行为。我为每个节点都配置了三种策略重试策略、超时策略、降级策略。重试要注意幂等性节点被重试两次时不能让数据重复处理。超时策略解决节点卡住不动的问题超时后走fallback节点。降级策略是当某个并行分支挂了是整体失败还是跳过该分支继续往下走这要在图定义阶段就明确。另外Graph的调试要比Loop麻烦得多。Loop的调试主要看几步循环Graph一旦有几十个节点靠打日志已经不够了。我在项目里给Graph加了执行快照每走完一个节点就把全局状态和当前节点位置存一份。这样出问题之后可以直接回放整个流程看到底是哪个节点的哪个条件导致了当前的路径选择。5. 生产实践从Demo到稳定服务的落地路线5.1 分阶段落地三层架构如果你是刚刚把一个Demo性质的Agent推向生产我的建议是不要一口气把三层都建完按阶段来。第一步先补Harness。把你现有的工具全部整理一遍做统一的注册、Schema管理、调用日志和异常捕获。这一步几乎不改变业务流程但能立刻解决工具调用四处乱飞的问题。同时在Harness层加好沙箱和权限控制这是生产环境最不能省的部分。第二步固化Loop。把你当前Agent的主循环参数全部配置化最大步数、单步超时、总token预算、无进展判定阈值。给循环加上强制终止逻辑保证任何情况下Agent都不会无限空转。这一阶段的目标是让Agent在极端情况下也能体面地结束。第三步再上Graph。当你有多个独立流程或者多个Agent需要协作时才值得引入Graph。把已经跑通的单条Loop包成Graph节点然后用条件边把它们组织起来。这时候不要追求流程的高度灵活先把主流程固化分支宁可少一点。5.2 常见问题与排查速查表我把近期实战中遇到的高频问题整理成了一张速查表直接对应排查方向。现象可能原因快速解法harness failed to load plugins插件依赖缺失、版本冲突、入口路径错误查看加载日志按依赖拓扑排序后逐个加载agent execution terminated due to error工具异常没有被捕获异常被当成终止信号在工具执行层加异常捕获把错误信息返回给模型修正并发一高频次超时模型API触发限流或工具执行线程池耗尽在Loop层加令牌桶限流对工具执行线程池扩容循环不收敛终止条件过弱模型反复执行类似动作加入无进展检测连续相似动作强制收敛工具参数经常传错工具Schema描述不清晰、参数命名模糊重写工具描述用枚举值限制参数选项上下文越来越大工具结果未做裁剪历史消息不做压缩在Harness层实现token预算与消息压缩5.3 可观测性设计生产环境里的Agent如果不可观测就是一颗定时炸弹。我在三层里分别打了三类日志。Harness层记录工具调用详情调用了哪个工具、传了什么参数、返回什么状态、耗时多少。Loop层记录决策步模型每一步的思考、产出动作、步序号、当前状态摘要。Graph层记录流程轨迹经过了哪些节点、触发哪些条件分支、全局状态的变化。三层日志用一个trace_id串起来。每次Agent任务开始时生成一个唯一的trace_id所有日志都带上它。排查问题时拿trace_id一查就能拼出完整链路模型在哪个节点做了什么决策、哪个工具返回了异常数据、哪一步触发了流程跳转。5.4 成本与性能优化最后聊一点成本优化。Agent生产环境最烧钱的地方往往是无效的模型调用和工具调用。Graph层能压缩模型调用次数。如果流程里多个节点都用同一个大模型处理相似问题可以用映射器先做一次合并判断相同或相似问题直接复用上一次的结果。Harness层可以做工具结果缓存。搜索、查库这类读操作如果输入完全相同短时间内的结果可以直接复用。模型选型上也可以分层。Graph里不需要高等推理能力的节点用小模型去跑速度更快也更便宜。只有需要复杂推理的节点才动用大模型。这样三层各司其职成本结构才合理。我在实际项目中还有一个感触比较深的点不要为了高级而Graph化。有些任务只有两三个步骤用Loop就够了硬套Graph反而增加维护成本和调试难度。架构永远是服务于业务复杂度的不是用来炫技的。踩过几次坑之后我现在做Agent第一件事是问自己这个任务的流程是单线的还是分叉的是固定几步还是随机步数想清楚再用对应的层来组织工程上会轻松很多。