Agent开发与工具编排实战：从ReAct循环到自研轻量框架

终于写到第六篇了。前五篇基本都在围着“单次交互”打转——模型怎么调用、Prompt怎么调优、上下文怎么管理、RAG怎么做。结果一到实际项目里就发现真正值钱的场景根本不是“你问我答”而是让模型自己判断该干什么、怎么干、干到什么程度算完。这篇我打算换个方向专门聊聊Agent开发与工具编排。列几个我在项目里实际遇到、也实际解决的问题同时把我踩过的坑一并交代清楚。1. 为什么第六篇的内容从“对话”转向了“干活”1.1 之前几篇的总结以及新问题是怎么冒出来的前几篇的学习记录里我折腾了Prompt设计、模型微调、RAG召回还有一个简单的对话记忆系统。当时觉得功能已经能覆盖大多数业务场景了。结果朋友丢给我一个需求“能不能让我用自然语言查数据库我不想再打开那个后台管理界面了。”我第一反应是把自然语言转成SQL然后直接交给模型去生成。试了两版后发现问题远不止“翻译SQL”这么简单因为用户往往会说“帮我看看上个月销售额比前个月涨了多少”。模型光生成一条SQL根本不够它得先判断上个月是几号到几号可能要查两张表还得做一次环比计算。这个链路里每个环节都有可能变化你很难用一段固定的Prompt把全部逻辑写死。正是从这个需求开始我发现必须让模型具备“自己决定调用哪些工具、按什么顺序调用、参数填什么”的能力。这就是Agent最朴素的定义把大模型从“回答问题的人”变成“完成任务的人”。模型不再是简单输出文本而是输出动作序列每个动作对应一次工具调用调用完拿到结果再继续下一步直到任务闭环。1.2 Agent与普通对话系统的核心差异普通对话系统是“一次请求一次响应”模型拿到的输入是用户消息输出是答案。Agent系统则是“多轮内部循环”模型每次拿到的是“用户任务 历史动作结果”的组合输出可能是“再查一次表”或“计算完成”这样的动作指令。你可以把它理解成一个实习生你给他一个任务他自己拆解步骤遇到不懂的地方查资料查不到就问你做完之后再给你汇报。每一步都是独立的但又必须服务于最终目标。这套机制的学名叫ReAct模式即Reasoning推理 Acting行动。说人话就是模型先想一步“我要查销售额数据”然后执行某个查询工具拿到结果后想下一步“这个数据要算环比”然后执行计算工具以此类推。循环的终止条件是模型自己认为任务已经完成输出最终答案。所有可控感、可扩展性都来自这个循环结构而所有坑也藏在循环结构里。2. Agent能力拆解工具调用与任务规划2.1 ReAct模式的基本工作流程我最初理解ReAct的时候总觉得玄乎后来画了一张很朴素的流程图才彻底想明白。整个循环就四步反复执行思考模型根据当前状态决定下一步做什么。这一阶段输出的是纯文本推理比如“用户要的销售额在订单表里我需要先查询订单表”。动作模型从预定义的工具列表里选一个并给出参数。这个动作以结构化形式输出比如{tool: sql_query, params: {sql: SELECT SUM(amount) FROM orders WHERE month2024-10}}。观察系统执行动作把结果文本塞回对话上下文。重复或结束模型看到结果后再次进入思考阶段。如果它认为任务完成就输出最终答案否则继续循环。这个设计的好处在于模型每一步都“有依据”不是一口气编完整段代码而是一步一步接近答案。缺点也很明显每一步都要调用一次模型推理成本会成倍增加。我实测过简单查询问题可能也要3到4轮循环单轮耗时大约2到3秒整个任务下来就是十几秒。2.2 工具定义与参数约束的细节工具是Agent的“手和脚”。定义工具时最忌讳的是把描述写得模棱两可。大模型选择工具的依据其实是工具描述和你给的Prompt文本之间的语义匹配。描述写得越精确模型选错的概率越低。我一般会在工具描述里写明三个信息这个工具做什么、在什么场景下用、输入参数是什么格式。实践中我比较常用的工具定义格式是JSON Schema。用一个字段表示工具名称一个字段放描述一个字段放参数结构。参数结构里需要标明类型、必填与否、取值范围。举个例子一个查询工具的参数就包括SQL语句字符串和数据库标识符。Schema写好后还需要再做一层校验因为模型偶尔会输出非法JSON或者把字符串类型的参数填成数字。我不建议在这一层太宽容宁可系统报错让模型重试也不要用宽松解析去猜它的意图。2.3 任务规划与循环终止条件任务规划分两种一种是模型在执行过程中动态规划另一种是人提前把步骤定义死。前者灵活适合未知场景后者稳定适合已知流程。我之前在财务分析场景里试过动态规划模型四步里能给你整出两个不必要的子查询看起来聪明实际效率很糟糕。后来我改成在系统提示里给出“常用处理路径建议”让模型优先参考已有方案而不是每次重新发明轮子。循环终止是个技术活。最简单的做法是限制最大循环次数比如5步或8步。超过了就强制中断让模型输出当前结论。稍微高级一点的做法是让模型在最后一步输出一个特殊的结束标记系统检测到这个标记就停止。还有更复杂的做法用另一个模型去判断当前结果是否已经满足用户需求。我目前用的还是“最大步数结束标记”的组合简单可靠不至于让任务卡死。如果你对成本不敏感可以试试独立的“完成度判定模型”在多步复杂任务里准确性更高。3. 框架选型为什么我最终弃用了LangChain3.1 当前主流Agent编排框架的对比这段时间我先后试了三个方向直接用编程语言配合模型API手写循环、使用LangChain的Agent模块、使用Dify这类可视化平台。每个方向都有自己的适用场景我也做了横向对比方案上手难度灵活度可控性适合场景手写循环中高高学习、定制化需求多LangChain Agent中低中中快速验证、标准工具Dify/Coze低低中做原型、非技术用户先说结论如果你长期只做一两个固定场景手写循环反而是最稳妥的。LangChain的Agent抽象层把很多逻辑封装了看起来省事但一旦工具数量多了、依赖复杂了调试成本会直线上升。我遇到过一个案例一个工具参数类型给错了错误信息被LangChain内部吞掉最后模型反复用错误参数重试白白浪费了几十次API调用。3.2 LangChain在复杂场景下的局限性分析LangChain的问题不在于框架本身而在于它的抽象层次和业务逻辑之间的界限模糊。用LangChain写个简单示例它确实几行代码就能跑通。但到了真实生产环境你需要处理鉴权、超时、限流、日志追踪、失败重试这些横切逻辑在框架里其实并不好接。每次升级版本都可能让你之前写的回调函数失效。有一阵子我为了适配一个新版本的Tool调用方式前前后后改了两次接口运行结果还是有一处不一致。另外LangChain的社区工具五花八门质量参差不齐。有的工具包装得很薄本质就是HTTP请求的封装有的包装很厚集成了自己的状态管理。如果你引用了五六个第三方工具任何一个底层行为发生变化你的Agent就会莫名其妙失灵。排查起来极其费劲因为你得去读第三方源码。3.3 最终选型自研轻量化Agent框架的核心理由我现在的方案是不引入完整Agent框架只写一个非常薄的循环控制模块外加一系列独立的工具函数。循环控制模块负责管理模型调用、动作解析、工具执行、结果回填所有状态用简单的字典对象传递。工具函数就是普通Python函数加一个装饰器标记它是可用的Agent工具即可。这么做的好处有三点。第一每行代码都看得懂出问题可以直接定位。第二任何第三方服务都只是函数内部的一次调用换成自研实现或者别的服务都很容易。第三不会因为框架升级产生破坏性变更。代价则是很多框架自带的高级能力——比如多轮工具记忆、自动重试策略、分布式执行——需要自己动手实现。但以我目前遇到的业务复杂度来看这些高级能力其实用一个几百行的小模块就能覆盖完全用不着引入一个庞大的依赖。4. 实操从零搭建一个SQL查询Agent4.1 需求场景与基础架构设计我以这篇开头的“自然语言查数据库”需求为例完整跑一遍如何实现一个查询Agent。任务要求是用户用自然语言提问Agent自动解析、查询、计算最后返回可直接阅读的答案。整个系统分为三个大块调用入口、Agent核心、工具层。调用入口接收用户输入调用Agent核心等待最终结果。Agent核心大模型循环负责推理和决策。工具层包括执行SQL查询的工具、计算工具、格式化工具等。工具层是重点。SQL查询工具暴露出来的参数不仅仅是SQL语句还有一个“数据库标识”这样同一个工具可以支持多个数据库。计算工具接收一个数学表达式字符串调用本地解析器求出结果。格式化工具负责把数字改成千分位展示。这三个工具加起来已经能覆盖绝大多数查询需求。4.2 工具层SQL查询工具与计算工具的实现SQL查询工具的实现思路并不复杂难在安全和可控。我先用SQL解析器检查语句类型只允许SELECT开头的查询凡是出现DELETE、UPDATE、DROP这类关键词直接拦截。其次所有查询操作统一走只读账号这个账号只有查询数据表、视图的权限没有写入权限。这样即使模型生成了一条危险语句也不会造成破坏。代码长得像下面这样我稍微简化了业务逻辑只保留关键结构def sql_query(sql: str, db_key: str default): # 1. 语法与权限校验 if not is_read_only_sql(sql): return Error: 只允许SELECT查询 # 2. 连接数据库执行 result db_execute(db_key, sql, timeout10) # 3. 返回结果限制行数避免上下文过长 return format_result(result, max_rows20)计算工具更简单我用了本地表达式求值器不允许eval裸函数避免任意代码执行。表达式中只能包含数字、四则运算符、括号、小数点和百分比符号。只要解析失败就返回空结果。这里我不展开代码了核心思想就是“在可能引狼入室的边界上做严格校验”。4.3 Agent核心循环控制与工具调用的关键代码Agent核心是整个系统的心脏。模型调用的部分我直接使用大模型API重点在于识别模型输出里的动作指令并解析执行。为了让模型更容易输出结构化动作我在系统提示里给了明确的格式要求并在请求里强制关闭了“友好乱聊”的倾向要求每次中间步骤必须严格按JSON格式输出。真正调试时发现模型偶尔会忘记输出动作而是直接给答案。解决办法是在解析层做兜底如果模型输出里没有检测到动作字段就直接把它当作最终结果返回。这样用户不会因为一个解析问题而卡死最多损失一点中间推理的透明度。核心循环的伪代码如下for step in range(max_steps): response model_chat(messages, tools_schema, stop[\n]) parsed parse_action(response) if not parsed or parsed[type] answer: return parsed[content] tool_result execute_tool(parsed[tool_name], parsed[arguments]) messages.append({role: observation, content: tool_result})就这么一个简单循环却是整个Agent系统里最重要的一段逻辑。所有扩展能力——比如多轮记忆、工具重试、结果缓存——都可以在这个循环里插入而不用改动上层接口。4.4 效果验证同一个问题跑三遍的稳定性表现我拿前文提到的“上个月销售额比前个月涨了多少”做了测试。理想流程是这样的模型先查上月销售总额再查前月销售总额然后调用计算工具算百分比最后格式化输出。实际跑下来模型大多能按这个路径走。一次成功率达到70%左右剩余30%的失败主要是SQL写错字段名或者表名在工具层被拦截之后模型重试一两次也能纠正过来。稳定性方面我用同一个问题连续跑了五遍路径基本一致说明在工具描述足够清晰的情况下模型不太会自由发挥。不过我也观察到一旦提问变成“最近三个月的销售走势”模型的处理路径就开始多样化了。有的会做三次查询按月对比有的会直接查整体汇总数据甚至有的会尝试用GROUP BY把三个月的数据查在一起。路径多了出错概率也会上升。如果想强制统一就得在系统提示里给出模板“遇到多个月份对比按月份逐个查询”。5. 踩坑实录在调试过程中遇到的那些问题与排查方法5.1 模型输出不稳定JSON解析失败的应对模型生成JSON时偶尔会把注释带进去或者冒号后面漏了空格这在人来看是小问题机器解析却会直接报错。我刚开始遇到这类问题就让模型重新生成但这样既浪费调用次数又容易陷入循环。后来我写了一个宽容的JSON解析器能用正则把JSON部分抽出来再尝试修复常见格式错误。如果修复不成才发起重试请求。这里给大家一个忠告不要在提示词里写“请保证输出合法JSON”这种废话它有作用但不可靠。务必在代码层面做好容错。我自己就是在重试了十几次便宜API之后才明白这个道理提示词约束只能降低错误概率工程上必须默认错误会随时发生。5.2 Agent陷入工具调用死循环控制策略与最大步数限制这个坑我踩得很深。有一回用户问“为什么上月销售额明显变低”模型居然开始循环查询不同维度的数据先是查总体然后查每个品类、每个区域、最后甚至查库存越跑越远。半天没有形成结论。我在日志里看它每一步的思考感觉它并不清楚“为什么”这个问题需要先形成假设再验证而不是把所有数据遍历一遍。解决方案是加了两条硬控制第一是最大步数限制业务场景里我设为6步超过就中断并输出当前已获得的信息。第二是加入“思考总结”阶段模型在两步查询之后必须写一个简短的中间总结如果总结表明没有新发现后面就不允许再用同类查询工具。这个策略实测下来能省掉一半以上的无效循环。5.3 数据库Schema过大导致的上下文长度爆炸工具描述里如果包含数据库表结构信息模型选择工具会准很多但代价是上下文占用特别大。某个库有三四十张表每张表还有十几个字段如果把全部Schema塞进系统提示一次请求的Token直接爆了。我的解决办法是把Schema按业务域拆成多份工具列表里不直接放Schema内容而是放一个“获取Schema信息”的辅助工具。模型在不确定表名时先调用这个工具查出可用表结构再用具体的SQL查询工具。这样既保证了准确性又避免了无关表结构白白占用上下文。5.4 工具并发与数据一致性多Agent协作设计虽然我现在大部分场景还是单Agent但已经在考虑多Agent协作的问题了。比如一个Agent负责查数、另一个Agent负责校验第三个Agent负责最终回答。这种设计的好处是每个Agent职责清晰坏处是状态共享和一致性控制难度大。我的建议是如果你刚接触Agent先别急着拆分成多Agent把同一个Agent里的工具职责划分清楚效果往往比多Agent更稳定。多Agent只有在任务确实可以并行、且子任务之间基本没有依赖时才真正划算。6. 学习Agent的一些心得与后续规划6.1 从任务到工具再到输入输出的梳理方法这半个月最大的收获是我学会了一种“先定协议再写代码”的开发方式。在做Agent之前先把你希望Agent使用的所有工具以及每个工具的输入输出字段都列出来像做接口设计一样写清楚。然后再去训练循环提示词让模型按这套协议工作。这个习惯帮我省掉了大量调试时间很多不匹配的问题在动手前就能被识别出来。举个例子我当时计划让Agent支持“发送邮件”这个操作但仔细分析了输入输出协议之后发现邮件模板需要用户提供多个字段而且一旦发出去无法撤回。这类高风险工具的准入标准就不同了——它不仅要走权限审核还得在Agent执行前增加一道人工确认。如果你不提前梳理输入输出的业务语义这些细节很容易被忽略。6.2 高频工具与低置信度模型的匹配经验模型对工具的调用置信度有时候和它本身的语义理解能力强相关。高频工具比如SQL查询、数值计算模型基本不会选错。低频工具比如“获取用户的历史搜索记录”模型经常无视描述里的限定条件在不需要的场合也去调。针对这个情况我养成了一个习惯每次开发完新工具先在测试集上统计调用精准度低于80%就改描述或加前置条件而不是硬着头皮上线。6.3 下一步学习方向多Agent协作与记忆增强接下来我想深入两个方向。一个是多Agent协作重点解决“任务分发”和“结果汇总”的机制设计。另一个是Agent记忆增强不是指普通的短期上下文记忆而是让Agent能把每次执行任务的策略沉淀下来下次遇到类似任务时自动套用。目前这块没有特别成熟的开源方案我打算用向量数据库存“任务描述-成功路径”对在推理阶段做检索增强看能不能把Agent的执行效率再提一截。写到现在已经很长了最后分享一个小技巧。在调试Agent的时候强烈建议把模型的每一步思考、动作参数、工具返回值全部打日志一行都不要省。我见过太多人直接就调API、只看最终结果一旦出错完全没法定位是模型出了问题、工具出了问题还是逻辑出了问题。日志打全了排查问题的时间能缩短十倍。这一点也是我踩过无数坑之后最深的体会。