1. 从一次线上事故说起为什么我要把 Agent Loop 和 Graph Engineer 绑在一起用去年年底我接手了一个内部工具链项目核心目标是把团队里零散的自动化脚本整合成一个能自主决策、能调用外部工具、还能在失败时自我修正的智能体系统。当时我第一版实现非常朴素一个while True循环里面塞了「思考—行动—观察」三步模型输出什么我就执行什么执行完把结果塞回上下文继续下一轮。这套东西跑 demo 的时候看着挺唬人一旦接入真实业务问题就全暴露出来了——循环停不下来、工具调用参数错得离谱、上下文越滚越长最后直接把 token 撑爆、某一步失败之后整个流程卡死没有任何回退路径。那段时间我几乎每天都在救火直到我把「Agent Loop」和「Graph Engineer」这两个概念真正捏到一起才算是把系统从玩具级别拉到了能上生产的工程级别。这篇内容就是把我踩过的坑、做过的取舍、以及最后落地的那套架构完整讲一遍。如果你正在做智能体相关的开发或者你手里有一堆需要多步骤决策、多工具协作的自动化任务那这篇东西应该能帮你少走至少两三个月的弯路。先说清楚这两个词到底指什么。Agent Loop指的是智能体执行任务时的核心循环机制——它决定了智能体怎么感知当前状态、怎么决定下一步动作、怎么执行、怎么根据执行结果更新自己的认知然后进入下一轮。听起来简单但工程化之后你会发现这个循环里每一个环节都有大量细节要处理。Graph Engineer在这里不是指某个具体岗位而是指用图结构来编排整个任务流程的工程方法——把智能体的每一步决策、每一次工具调用、每一个条件分支都建模成图中的节点和边让整个执行路径变得可追踪、可回放、可干预。把这两者结合的核心动机很直接Agent Loop 负责「动」Graph Engineer 负责「控」。光有循环系统是失控的光有图系统是死的。只有让循环在图的约束下运行才能既保持智能体的自主性又保证工程上的可控性。下面我按实际落地的顺序把整套东西拆开讲。2. 整体架构设计循环与图的职责边界怎么划2.1 为什么不能只用 Agent Loop 硬扛我第一版纯 Loop 的实现大概长这样模型收到用户请求输出一个 JSON 格式的动作指令我解析后执行对应工具把结果拼回消息列表再次调用模型。这个结构在单轮简单任务上没问题但一旦任务需要五步以上、涉及三四个不同工具、还可能出现中间失败需要重试纯 Loop 就会变成一坨意大利面。具体来说有三个致命问题。第一是状态不可见循环跑到第三轮的时候你根本不知道当前处于整个任务的哪个阶段只能靠翻日志猜。第二是无法中断和恢复如果某一步需要人工审批或者服务重启了整个循环就得从头再来。第三是错误处理没有层次模型自己决定重试还是放弃但模型对「这个工具报错是因为参数错了还是因为服务挂了」根本没有判断力结果就是无脑重试把配额烧光。这三个问题的本质是Agent Loop 缺少一个外部的、确定性的控制层。模型擅长的是在开放环境下做模糊决策不擅长的是维护精确的执行状态和边界条件。所以正确的做法是把「决策」和「控制」分开让模型专注做它擅长的把状态管理、流程编排、错误处理交给一个确定性的图结构来做。2.2 Graph 层到底管什么我最终落地的架构里Graph 层承担了四件事。第一是节点定义每个节点代表一个原子操作可以是一次模型调用、一次工具执行、一次条件判断、甚至一次人工介入等待。第二是边定义边决定了节点之间的流转关系包括顺序边、条件边、以及失败回退边。第三是状态管理整个图共享一个状态对象每个节点执行前后都会读写这个状态状态本身是可序列化的所以随时可以存盘和恢复。第四是执行调度决定下一个该走哪个节点这里可以是确定性的规则也可以把决策权交回给模型。这里有个关键设计决策我想强调一下Graph 不是替代 Agent Loop而是承载 Agent Loop。也就是说循环依然存在但循环的每一轮不再是一个黑盒而是图上的一个节点或者一组节点。模型在某个节点里做决策决策结果决定了走哪条边下一条边指向的节点又可能触发新一轮模型调用。这样循环就被「打散」到了图里每一轮都有明确的入口和出口可追踪、可干预。2.3 状态对象的设计要点状态对象是整个系统的命脉设计不好后面全是坑。我的经验是状态对象要满足三个条件可序列化、可增量更新、有明确的 schema。可序列化是为了支持存盘恢复和跨进程传递可增量更新是为了避免每次节点执行都全量复制状态导致性能爆炸有明确 schema 是为了让每个节点知道自己该读什么、该写什么避免节点之间隐式耦合。我用的状态结构大概包含这几块messages存对话历史scratchpad存中间推理结果tool_results存工具调用记录current_step存当前阶段标识error_context存错误信息metadata存一些运行时元数据比如耗时、token 消耗。这里要特别注意messages的增长问题后面讲上下文管理的时候会专门说。3. 核心节点类型与实现细节3.1 模型决策节点怎么让模型输出可解析的动作模型决策节点是整个图里最核心也最容易出问题的节点。它的职责是读取当前状态输出一个结构化的动作指令告诉系统下一步该干什么。这里最大的坑是模型输出的格式稳定性。我试过让模型直接输出 JSON结果十次里有两三次会多带一段解释文字或者少个括号解析直接失败。后来我改成了一套组合策略。首先在 prompt 里用 few-shot 的方式给出三到五个标准输出示例覆盖「调用工具」「直接回答」「请求澄清」三种情况。其次在解析层做容错先用正则提取 JSON 块提取失败再用宽松解析器尝试修复常见错误比如尾逗号、单引号。最后如果还是解析失败不直接报错而是把解析错误信息作为一个观察结果塞回上下文让模型自己修正——这一步很关键它把「格式错误」变成了循环可以自愈的一种情况。动作指令的结构我固定成这几个字段action_type工具调用/直接回答/澄清/终止、tool_name如果是工具调用、tool_input工具参数、reasoning决策理由用于调试和审计。reasoning字段看起来可有可无但实际上在排查问题时价值极高你能直接看到模型当时是怎么想的。3.2 工具执行节点参数校验与超时控制工具执行节点负责把模型给出的动作指令真正落地。这里我踩过最大的坑是盲目信任模型给的参数。有一次模型调用一个查询接口把日期参数写成了「上周三」这种自然语言接口直接报错然后模型看到报错又重试还是同样的错误循环了七八次才停。解决办法是在工具执行节点前面加一层参数校验和规范化。每个工具注册的时候要附带一个参数 schema执行前先按 schema 校验类型不对就尝试转换转换不了就直接返回一个结构化的错误信息给模型明确告诉它「参数 X 期望格式是 YYYY-MM-DD你给的是 Z」。这样模型下一轮就能自我修正。另外超时控制也必须做每个工具调用设置独立的超时时间超时后返回超时错误而不是让整个图卡死。还有一个细节是工具结果的截断。有些工具返回的数据量极大直接塞进上下文会瞬间撑爆 token。我的做法是在工具执行节点里对结果做预处理超过阈值就截断并附上「结果已截断完整数据可通过 XX 方式获取」的提示。这个阈值我一般设在 2000 到 4000 字符之间具体看模型上下文窗口大小。3.3 条件路由节点什么时候该让模型决策什么时候用规则条件路由节点决定了执行完当前节点后该走哪条边。这里有个重要的设计原则能用规则判断的就不要交给模型。比如「工具调用是否成功」这种判断直接看返回状态码就行没必要让模型再判断一次既浪费 token 又不稳定。真正需要模型判断的是那些模糊的、需要语义理解的场景比如「当前收集到的信息是否足以回答用户问题」。我一般把路由分成两类。一类是确定性路由基于状态里的明确字段做判断比如error_context非空就走错误处理分支current_step等于某值就走对应分支。另一类是模型辅助路由把当前状态摘要给模型让它输出一个路由决策。后者要慎用因为每次调用都是一次额外的模型开销而且引入了不确定性。我的经验是模型辅助路由只用在真正需要语义判断的地方占比控制在总路由的 20% 以内。3.4 错误处理节点重试、降级、还是终止错误处理节点是区分玩具系统和生产系统的分水岭。我的错误处理策略分三层。第一层是节点内重试针对那些瞬时故障比如网络抖动在节点内部做有限次重试重试间隔用指数退避。第二层是图级降级如果某个工具连续失败走降级边切换到一个备用方案比如换一个工具、或者跳过这一步用已有信息继续。第三层是终止并上报如果降级也失败就把当前状态完整保存标记为需要人工介入然后优雅退出。这里有个反直觉的经验不要无脑重试。我一开始给所有失败都配了三次重试结果发现很多失败是确定性的比如参数错误、权限不足重试一百次也没用反而浪费时间和配额。后来我改成只有标记为「可重试」的错误类型才重试其他直接走降级或终止。错误类型怎么标记在工具注册的时候就定义好每个工具声明自己可能抛出的错误类型以及对应的处理策略。4. 上下文管理与循环终止两个最容易翻车的地方4.1 上下文膨胀的三种应对策略Agent Loop 跑多轮之后上下文膨胀是必然的因为每一轮的模型输出、工具调用、工具结果都会追加到消息列表里。我实测过一个中等复杂度的任务跑十五轮之后上下文能到两万多 token再跑下去要么超限要么成本失控。我用了三种策略组合应对。第一种是滑动窗口加摘要保留最近 N 轮完整消息更早的消息压缩成一段摘要。摘要不是简单截断而是让模型生成一段「到目前为止发生了什么、得出了什么结论」的浓缩描述。第二种是工具结果外置大的工具结果不直接进上下文而是存到外部存储上下文里只放一个引用和简短描述模型需要时再通过工具取回。第三种是状态字段裁剪状态对象里有些字段只在特定阶段有用过了那个阶段就从上下文视图里移除虽然底层还保留着以备恢复。这三种策略的取舍是滑动窗口加摘要会损失一些细节但实现简单工具结果外置保留完整信息但增加了一次取回的开销状态字段裁剪最省 token但需要仔细设计哪些字段在哪个阶段可见。我一般是三种混用根据任务类型调整比例。4.2 循环终止条件的四重保险循环停不下来是 Agent Loop 最经典的问题。模型有时候会陷入「调用工具—看到结果—再调用同一个工具」的死循环或者一直觉得信息不够反复请求澄清。我设了四重终止条件任何一重触发都会结束循环。第一重是最大轮次限制硬性规定最多跑多少轮超过就强制终止。这个值我一般设在 20 到 30 之间具体看任务复杂度。第二重是重复动作检测如果连续三轮的动作指令高度相似工具名相同、参数相似度超过阈值就判定为死循环强制终止。第三重是显式终止信号模型输出action_type为终止时正常结束。第四重是资源耗尽token 消耗或者时间消耗超过预算时终止。这四重里重复动作检测是最容易被忽略但最有用的。实现上我用了一个简单的相似度计算把最近几轮的动作指令做归一化后比较相似度超过 0.9 就触发。这个阈值可以调调低了容易误杀正常的重试调高了又抓不住死循环我实测 0.9 是个比较平衡的值。5. 图的可观测性与调试出问题时你怎么知道发生了什么5.1 执行轨迹的完整记录图结构最大的好处就是执行轨迹天然可记录。每经过一个节点我就往轨迹里追加一条记录包含节点 ID、进入时间、退出时间、状态变更摘要、以及该节点的输出。这样整个任务的执行过程就是一条线性的轨迹记录出问题时直接看轨迹就能定位到是哪一步出的问题。轨迹记录我建议至少保留这几个字段node_id、node_type、input_state_hash、output_state_hash、duration_ms、token_used、error如果有。input_state_hash和output_state_hash用状态对象的哈希值这样可以快速判断某个节点是否真的改变了状态还是空转了一圈。5.2 回放与断点调试有了完整轨迹之后回放就很简单了。因为状态对象是可序列化的我可以在任意一个节点执行前把状态存下来然后从那个状态重新执行观察后续行为是否符合预期。这个能力在调试复杂任务时简直是救命稻草尤其是那种跑到第十轮才出问题的场景没有回放你只能一遍遍从头跑。断点调试也是类似原理。我在图执行器里加了一个「断点集合」如果下一个要执行的节点在断点集合里就暂停执行等待指令。暂停时可以把当前状态 dump 出来人工检查确认没问题再继续。这个功能在开发阶段用得很多上线后一般关掉但保留着以备线上问题排查。5.3 关键指标的监控生产环境上我还加了几个监控指标。单任务平均轮次反映任务复杂度是否在预期范围内突然升高可能意味着某类任务出了问题。工具调用成功率按工具维度统计某个工具成功率骤降说明它可能挂了或者接口变了。平均 token 消耗反映成本异常升高可能是上下文管理失效。循环终止原因分布统计四重终止条件各自触发了多少次如果「最大轮次限制」触发比例很高说明任务设计或者 prompt 有问题。这些指标我用一个简单的看板展示阈值告警直接推到团队频道。经验是不要等出大事才看监控很多问题在指标轻微异常的时候就有征兆早发现早处理。6. 实操落地从零搭一个最小可用版本6.1 技术选型与依赖我这套东西的实现语言是 Python图执行引擎没有用现成的框架而是自己写了一个轻量的执行器。原因是我试过几个现成的图编排框架要么太重、要么对 Agent Loop 这种动态决策场景支持不好。自己写的话核心代码大概三百行左右可控性最高。核心依赖就几个模型调用用官方 SDK状态序列化用标准库的 json 加一个自定义的 encoder 处理特殊类型异步执行用 asyncio。没有引入额外的重型依赖部署起来很轻。如果你团队已经有现成的图编排基础设施也可以复用但要注意它是否支持动态路由和状态快照这两个关键能力。6.2 最小可用版本的核心代码结构最小可用版本我建议从这几个模块开始搭。state.py定义状态对象和序列化逻辑。nodes.py定义节点基类和几个核心节点类型。graph.py定义图结构和执行器。tools.py定义工具注册和调用逻辑。main.py组装起来跑一个示例任务。节点基类大概长这样class BaseNode: node_id: str node_type: str async def execute(self, state: dict) - dict: raise NotImplementedError def route(self, state: dict) - str: # 返回下一条边的标识 raise NotImplementedError执行器的核心逻辑是一个循环从当前节点开始执行节点根据路由结果找下一条边更新当前节点直到遇到终止节点或者触发终止条件。这个循环里要嵌入前面说的四重终止检查和轨迹记录。6.3 一个完整的示例任务跑通我拿一个实际场景来演示用户给一段需求描述系统需要先分析需求、然后搜索相关资料、再根据资料生成一份结构化文档、最后做一次自检。这个任务涉及四个阶段每个阶段可能调用不同工具中间可能失败需要重试。图的结构是入口节点接收用户输入路由到需求分析节点需求分析节点调用模型做分析路由到搜索节点搜索节点调用搜索工具如果搜索失败走重试边重试超过次数走降级边用模型已有知识继续生成节点根据前面收集的信息生成文档自检节点检查文档质量不合格走回生成节点重新生成合格则终止。这个示例跑通之后你会发现大部分实际任务都是这个结构的变体。掌握了这个骨架后面就是往里填具体的节点和工具。7. 踩过的坑与排查速查表7.1 那些让我加班到凌晨的典型问题第一个坑是模型输出格式漂移。同一个 prompt跑一百次可能有五次输出格式不一样尤其是模型版本更新之后。我的应对是解析层做足容错同时把格式错误作为观察结果回灌给模型让它自修正而不是直接抛异常。第二个坑是工具结果里的隐藏字符。有些工具返回的文本里带了不可见字符或者特殊编码塞进上下文后导致模型解析异常。后来我在工具执行节点里加了一步清洗把所有非打印字符过滤掉。第三个坑是状态并发写冲突。早期我为了性能让多个节点并行执行结果它们同时读写同一个状态对象出现了数据覆盖。后来改成状态更新走一个串行的提交队列虽然损失了一点性能但正确性有了保障。第四个坑是恢复后状态不一致。从存盘状态恢复执行时有些运行时资源比如已打开的文件句柄、已建立的连接没有恢复导致后续节点执行失败。解决办法是把这些资源也纳入状态管理或者设计成节点执行时按需重建。7.2 常见问题速查表问题现象可能原因排查方向解决手段循环停不下来重复动作检测失效看轨迹里最近几轮动作是否相似调低相似度阈值检查检测逻辑上下文超限工具结果过大或轮次过多统计每轮 token 增量启用结果外置和滑动窗口摘要工具调用参数错误模型对参数格式理解偏差看工具返回的错误信息加强参数 schema 校验和错误回灌恢复后行为异常运行时资源未恢复对比恢复前后状态差异资源纳入状态管理或按需重建路由走错分支条件判断逻辑有漏洞检查路由节点的判断条件补充边界情况测试用例模型输出解析失败格式漂移或特殊字符看原始输出内容解析容错加错误回灌7.3 几条用血换来的经验第一条先跑通再优化。我一开始就想着把架构设计得完美结果两周没跑通一个完整任务。后来改成先用最朴素的实现跑通再逐步替换各个模块效率高得多。第二条日志要打够但不要打太多。日志太少出问题没法排查太多又会淹没关键信息。我的做法是每个节点执行前后各打一条结构化日志包含节点 ID 和状态摘要中间过程用 debug 级别默认不输出。第三条测试用例要覆盖失败路径。大部分人写测试只测正常流程但 Agent Loop 出问题几乎都在失败路径上。我后来专门建了一组「故障注入」测试模拟工具超时、返回错误、返回空结果等各种情况确保系统能正确处理。第四条prompt 要版本化管理。prompt 改动对系统行为影响极大但很多人改 prompt 很随意改完也不记录。我后来把 prompt 纳入版本管理每次改动都记录改了什么、为什么改、改完效果如何出问题时可以快速回滚。这套东西我从第一版到现在稳定运行前后迭代了大概七八个版本中间重构过两次。最大的体会是Agent Loop 的工程化难点不在模型本身而在模型之外的那套控制、状态、错误处理机制。模型能力再强如果外围这套东西没做好系统就是不可用的。反过来即使模型能力一般只要外围工程做扎实了也能跑出相当稳定的效果。这个投入产出比做过的人都懂。