让大模型去查实时天气、去翻数据库、去执行一条自动化任务——这事听起来不复杂但真落地的时候绝大部分人栽的第一个跟头就是模型会“说”但不会“做”。我做了快一年的开源提示流编排器项目核心就是解决这个问题把大模型的思维能力和外部系统的执行能力打通。作为开源系列的第 09 篇这篇把 Agent 节点和 Tools 工具调用体系完整拆一遍从协议怎么定义、执行引擎怎么编排到实战中怎么避坑一次性讲透。适合正在做 AI 应用落地的工程师也适合想把大模型接进自己业务系统但还没找到头绪的开发者。1. 为什么需要提示流编排器先搞明白 Agent 节点的定位1.1 大模型的“手和脚”到底指什么给大模型装“手和脚”拆开来看其实是两层能力。第一层是工具调用Tool Calling模型在回答的过程中输出结构化的调用指令告诉我们“我想调用哪个函数、传什么参数”然后由程序去真刀真枪地执行。第二层是流程编排Flow Orchestration解决多步之间怎么衔接、条件怎么判断、失败怎么兜底。前者是“手”后者是“走路的方式”。没有编排器你也能用各家大模型自带的 function calling 做一次工具调用。但第二个工具、第三个工具、需要把第一次执行结果作为第二次输入参数的时候代码会迅速变成一坨互相纠缠的 if-else。我在早期原型阶段就干过这事为了做一个“帮我查快递 催发货”的对话机器人写了一个两百行的调度函数里面全是判断“模型这次想调用谁”的分支。后来加了第三个工具改到怀疑人生。编排器要做的事情就是把这一坨随意生长的分支整理成一张可以描述、可以复用、可以可视化的图。节点是图上的点边是数据流动的方向Agent 节点就是这张图上最特殊的那个点——它有大脑能思考还能伸手去摸外部的工具。1.2 Agent 节点从“一问一答”到“闭环执行”普通 LLM 节点的行为模式是一锤子买卖拿 prompt 进去拿文本出来结束。它适合翻译、改写、摘要这类单次推理任务。但真实业务不是这样的用户问“帮我订明天下午两点的会议室顺便通知老王”模型得先查会议室空闲情况再调用预订接口最后生成一条通知消息发给老王。这个过程有三个动作、两个中间结果任何一个环节出错都要重来或另走分支。Agent 节点的本质是把“一问一答”升级成“循环执行”模型先根据用户输入决定下一步动作动作执行完拿到结果再带着这个结果继续思考直到它认为任务完成输出最终答案或者撞上我们设定的最大轮数限制。我在项目里把它叫做“思考—行动—观察”循环也就是业内常说的 ReAct 模式。这个设计带来的最大好处是业务逻辑不再由开发者用代码写死而是由模型在运行时动态决策。开发者只需要注册好“有哪些工具可以用、每个工具怎么用”剩下的路由决策交给 Agent。对业务变化频繁的团队来说这意味着新增能力不用改代码注册一个新工具就行。2. 整体架构与技术选型2.1 分层架构声明式编排与执行引擎分离我踩过最大的坑之一就是把执行逻辑硬写在业务代码里。后来重构成现在的三层结构才真正舒坦了。最上层是编排定义层用 JSON 或 YAML 描述一张流程图有哪些节点、节点之间怎么连、每个节点用什么模型、挂哪些工具。这一层是纯声明式的不包含任何执行逻辑所以可以被存进数据库、被可视化工具渲染、甚至被非技术同事一起 review。中间是执行引擎层负责把定义好的图跑起来处理节点的调度、数据的传递、异常的传播。最下层是工具层每一个 Tool 是一个独立的功能单元内部封装了外部 API、数据库、文件系统等具体实现。分层的理由很朴素把“要做什么”和“怎么做”分开。定义层只关心流程长什么样执行引擎不用管具体业务工具层不关心流程图。任何一层的改动都不会把另外两层带崩。实测下来这个结构让项目在半年内从支持 6 种节点扩展到 14 种节点老节点一个都没重写过。2.2 节点类型如何设计目前我的编排器里沉淀了六类核心节点正好对应大多数 AI 应用的通用流程节点类型作用输入输出输入节点接收用户初始消息或外部参数无用户消息、业务参数提示词节点按模板渲染 prompt 并调用模型模板变量模型文本Agent 节点带工具循环的智能决策节点用户意图、工具列表最终回答或结构化结果工具节点固定调用某个已注册工具参数对象工具执行结果条件节点按规则或模型判断走哪个分支前置结果分支标识聚合节点合并多条路径的输出多个输入合并结果Agent 节点和其他节点的关键差异在于它拥有“自主决策权”。工具节点是提前定好了“无条件去调某个 API”Agent 节点是“让模型决定要不要调、调哪个、调完怎么办”。一个是执行兵一个是指挥官这个边界一定要想清楚。2.3 技术选型自研而不是套现成框架有人会问市面上有 LangChain、LangGraph 这些现成编排框架为什么还要自研我的原因有三条。第一透明性。框架层帮你封装得越多出问题的时候排查链路越长。自研的每一条 code path 都是我一行行写的模型输出异常、工具调用失败我十分钟内能定位到具体环节。第二可控性。框架升级频繁API 三个月变一次而我的项目需要稳定运行在客户的生产环境里自研意味着升级节奏自己掌控。第三轻量。很多框架为了覆盖各种场景引入了大量依赖而自研可以针对自己的业务场景做减法。当然这不代表现成框架不好。如果你只是快速验证一个想法用 LangGraph 没问题。但如果你要做一个长期的、深度的、可控的 AI 业务系统我建议至少理解框架内部的编排原理再决定是改造它还是自己写一个。我的项目选择自研正是因为把它当作品类去打磨而不是当一个临时工具。3. Tools 工具调用体系设计3.1 统一工具协议一套 Schema 打通所有模型工具体系是整个编排器的地基。地基打不好Agent 节点再聪明也白搭。我踩过的第一个坑就是各家用各家的工具格式OpenAI 的 function calling、Claude 的 tool use、国产模型的 function 定义字段名和嵌套结构都不一样。如果 Agent 节点里写死某一种格式换模型就得重构。最终我定下的方案是内部统一采用一套接近 OpenAPI 风格的 JSON Schema 作为工具的“唯一事实来源”对接具体模型时再做一层格式转换。这样工具作者只需要写一份定义适配任何模型。转换逻辑封装在一个独立的 adapter 层里模型接入只是增加一个 adapter 而已。一个典型的工具定义长这样{ type: function, function: { name: query_weather, description: 查询指定城市当前的天气和未来几天的预报。适合回答‘今天热不热’、‘周末适合爬山吗’这类问题。, parameters: { type: object, properties: { city: { type: string, description: 城市名称使用中文全称例如北京、上海、广州 }, days: { type: integer, description: 预报天数取值 1 到 7默认 1 } }, required: [city] } } }关键字段就三个name 是工具唯一标识description 是给模型看的“使用说明”parameters 是参数约束。模型就是靠这三个字段决定“这个工具适不适合当前问题、参数怎么填”。所以这三处的质量直接决定了工具调用的成功率。3.2 工具注册中心的实现工具定义好之后需要有一个地方统一管理。我在项目里实现了一个简洁的工具注册中心ToolRegistry核心逻辑只有几十行class ToolRegistry: def __init__(self): self._tools {} def register(self, tool): tool 是一个包含 name、description、parameters、handler 的对象 self._tools[tool.name] tool def get(self, name): return self._tools.get(name) def schemas(self): 返回给模型看的工具协议列表 return [t.to_schema() for t in self._tools.values()] def call(self, name, arguments: dict): tool self._tools.get(name) if not tool: raise ToolNotFoundError(ftool {name} 不存在) return tool.handler(**arguments)注册中心的职责是登记、检索、调用。注意我没有在注册中心做参数类型校验因为校验逻辑应该放在每个工具的 handler 内部用 pydantic 或者 jsonschema 来做。这样每个工具对自己的输入负责不把脏活累活统一到注册中心避免它变成一个越来越重的“上帝类”。我实际用下来注册中心配合装饰器特别好使。给 handler 加个register_tool的装饰器函数定义完就自动注册省掉手动登记的步骤也不会漏注册from orchestrator import registry registry.register( namequery_weather, description查询指定城市当前天气和未来几天的预报, parameters{ type: object, properties: { city: {type: string, description: 城市名称中文全称}, }, required: [city], }, ) def query_weather(city: str) - dict: data weather_api.fetch(city) return {city: city, current: data[now], forecast: data[daily]}3.3 让模型少犯错的三个描述技巧工具描述怎么写是很多人忽略但效果差异巨大的细节。我对比过同一工具的三种描述写法工具选择准确率能从 70% 拉到 95% 以上。三个技巧分享给大家。第一个是描述里要写“适合什么场景”而不是只写“做什么”。比如“查询天气”这种描述模型确实知道能用它但遇到“周末适不适合跑步”这种间接提问时就不一定会用。改成“查询指定城市当前天气和未来几天的预报。适合回答‘今天热不热’、‘周末适合爬山吗’这类问题”之后模型能明显更准确地判断是否调用。第二个是参数描述里要写清边界和格式。我在参数里明确写“使用中文全称例如北京、上海”模型就会倾向于传“北京”而不是“BJ”或者“Beijing”。如果不写各家模型的表现参差不齐尤其是小参数模型经常把城市名翻译成英文或者带多余标点。第三个是不要堆砌长描述。工具描述不是越详细越好。我把一个工具的描述从 200 字精简到 80 字之后模型调用准确率反而提升了。原因很好理解描述太长会让模型在有限上下文里抓不住重点关键信息被淹没。建议描述控制在 50 到 120 字之间突出功能和适用场景其他边界信息放进参数描述里。4. Agent 节点核心实现4.1 Agent 本质上是一个带工具的 while 循环很多教程把 Agent 说得神乎其神剥开来看也就是一个循环模型输出 → 判断是否要调用工具 → 是则执行工具并将结果回填 → 继续让模型思考 → 直到模型觉得任务完成。理解这一点Agent 节点的实现就没什么神秘的了。唯一的难点在于“循环里的状态怎么管理”。一次工具调用的结果下一次模型思考的时候必须能看到多轮之后前面几轮的内容要不要全部保留。这属于上下文管理问题我放在 4.3 里细说。先看核心循环逻辑。4.2 核心循环的代码骨架我在项目里的 Agent 节点实现核心逻辑可以抽象成下面这段代码def run_agent(registry, llm, query, max_iterations5): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: query}, ] for step in range(max_iterations): response llm.chat( messagesmessages, toolsregistry.schemas(), tool_choiceauto, ) msg response.message messages.append(msg.model_dump()) # 模型没有要求调用工具直接输出最终答案 if not msg.tool_calls: return msg.content # 模型要求调用一个或多个工具逐个执行 for tool_call in msg.tool_calls: arguments parse_arguments(tool_call.arguments) result registry.call(tool_call.name, arguments) messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse), }) # 循环继续把工具结果喂回给模型让它决定下一步 raise AgentTimeoutError(f超过最大迭代次数 {max_iterations}任务终止)这段代码看着简单但有几个细节是硬碰硬试出来的。第一tool_choiceauto必须显式设置。不设的话有些模型默认是“必须调用工具”会强行编一个工具调用来有些模型默认是“从不调用”工具白挂。显式设成 auto 才能保证模型自主决策。第二工具结果要按tool_call_id回填不能只按顺序怼上去。一个模型响应里可能同时返回多个工具调用结果必须一一对应接错了模型会彻底混乱。第三最大迭代次数一定要设。我在生产环境默认设 5复杂的任务可以放宽到 8但绝不能无限循环。否则模型绕进死胡同的时候你的 CPU 和账单都会哭。4.3 上下文管理与终止条件循环跑起来之后上下文会快速膨胀。每轮模型输出、工具调用、工具结果都会追加进 messages三轮下来可能就吃掉几千个 token。如果不做管理长任务跑到第五轮上下文窗口就爆了。我的处理策略是分层级的。第一步工具结果精简存储。天气查询这种工具可能返回十几条数据但真正有用的可能就两三行。我要求工具 handler 返回的结果必须是“经过提炼的摘要”而不是原始 API 响应。这一步能把 token 消耗砍掉一半以上。第二步历史对话压缩。超过一定轮数后把早期的“思考—行动—观察”记录压缩成一条摘要消息替代原始的多条消息。第三步系统性任务完成后强制退出用结构化的最终结果替代整个对话记录这样下游节点拿到的输入足够干净。终止条件方面除了最大迭代次数我还加了“空转检测”如果模型连续两轮输出的工具调用完全相同说明它陷入了死循环此时直接终止并回退到上一轮的有效结果。这个检测在实测中救了无数次场尤其是用小参数模型的时候空转非常常见。5. 实操从零搭一个会查天气、会管日程的 Agent5.1 描述一张编排图理论讲再多不如跑通一个完整例子。我用一个“智能日程助手”来演示用户说“帮我看看明天北京天气如果不下雨就约老王下午三点见面”。首先定义编排图{ id: schedule-assistant, name: 日程助手, nodes: [ { id: agent, type: agent, model: qwen-max, tools: [query_weather, create_event], max_iterations: 5 } ], edges: [] }这里面只有一个 Agent 节点没有多余边。因为整个任务的路由都由 Agent 自己决策查天气、判断是否下雨、创建日程三个动作被模型在循环里动态串联。如果任务里还有固定步骤比如先查天气无论如何都记录日志再拆出一个前置的工具节点让数据流走边。但纯 Agent 能解决的场景我一般不多画边保持图简单。5.2 注册两个真实工具第二个工具是创建日程定义如下registry.register( namecreate_event, description在日历中创建一条日程安排。适合回答‘帮我约...’、‘提醒我...’、‘安排一个会议’这类问题。, parameters{ type: object, properties: { summary: {type: string, description: 日程标题例如与老王喝下午茶}, start_time: {type: string, description: 开始时间ISO8601 格式例如 2025-06-20T15:00:00}, duration_minutes: {type: integer, description: 持续时间分钟默认 60}, }, required: [summary, start_time], }, ) def create_event(summary: str, start_time: str, duration_minutes: int 60) - dict: event_id calendar_backend.insert(summary, start_time, duration_minutes) return {event_id: event_id, status: created, summary: summary, start_time: start_time}注意这个工具的 start_time 参数我写明了“ISO8601 格式”并给了示例这对模型很重要。如果不写格式模型会自由发挥出“明天下午3点”“2025-06-20 15:00”等各种格式后端解析的时候直接崩。5.3 完整执行链路实测跑完整条链路观察 Agent 的思考过程你会发现模型的表现是“查了再答”。大致执行轨迹第一轮模型没有直接调用工具而是先请求查天气tool_call 内容是{name: query_weather, arguments: {city: 北京}}。天气接口返回“明日晴气温 22-30 度无降水”。第二轮模型看到天气结果判断“不下雨适合见面”然后调用create_event传参{summary: 与老王喝下午茶, start_time: 2025-06-20T15:00:00, duration_minutes: 60}。第三轮日程创建成功返回 event_id模型输出最终回复“明天北京天气不错已经帮你和老王约好下午三点见面。”这条链路里最关键的观察点有两个一是模型真的会“先查再定”没有凭空编造天气二是工具结果成功影响了下游决策天气不下雨才触发创建事件。如果你在本地复现时发现模型直接编了一个create_event而没查天气说明 query_weather 的描述没写好或者模型上下文里已经发生过太多次工具调用了。把上面两个工具的 description 对比一下大部分问题能解决。6. 常见问题与排查技巧实录6.1 工具参数解析失败怎么办这是我收到反馈最多的问题现象是模型返回的 arguments 不是合法 JSON比如多了一个括号、字符串里混进了注释、参数名带了空格。传统做法是直接json.loads失败了就整个 Agent 报错体验非常糟糕。我的处理是加一道“鲁棒解析”层先用正则提取最外层花括号包裹的片段再做 JSON 解析解析失败就丢给一个轻量的修复函数把键名两边的多余引号、末尾逗号、单引号替换成双引号最后再试一次。如果还不行就把“参数格式错误”当作工具结果返回给模型让模型自己修正后重新调用。实测这套策略能把参数解析成功率从 85% 拉到 99% 以上。记住宁可让模型多跑一轮也不要在解析层直接抛异常终止整个流程。6.2 模型死活不调用工具模型不调用先别怀疑模型笨通常有三种原因。第一工具描述没有准确覆盖用户问题的语义。用户问“明天适合跑步吗”你的工具描述只写了“查询天气”模型可能觉得不匹配。把适用场景写进描述里这一条概率最大。第二系统提示词里写了“不要使用工具”或者“直接回答用户”。有些模板里遗留了这类指令模型会严格遵守把所有工具请求都挡回去。第三tool_choice设置不对。我有一次调试半天最后发现 adapter 把tool_choice拼错了字段名模型根本没收到这个参数。排查这类问题时我建议先把系统提示词和 tool_choice 打印到日志里逐项核对再去改描述。日志里能看到模型最终收到的请求是最直接的证据。6.3 循环不退出与上下文膨胀Agent 循环不退出一般是两种原因模型觉得自己任务没完成或者陷入了重复调用同一工具的怪圈。前者通过最大迭代次数兜底后者靠我前面提到的空转检测解决。上下文膨胀的问题更隐蔽。哪怕只有三轮循环一整套 messages 可能就超过了模型的上下文窗口最后模型开始“失忆”忘记用户最初问的是什么。我遇到过用户问“帮我查快递”Agent 查完快递后开始自己复盘“我是不是应该查一下物流公司信息”完全跑偏。加上了历史压缩之后这类跑偏明显减少。经验是超过三轮的工具调用就要对前几轮做压缩别指望模型在长上下文里还能准确聚焦。6.4 工具执行超时与并发安全工具是外部系统的入口一个 HTTP 接口超时 10 秒整个 Agent 就卡 10 秒。我在工具层统一加了超时控制默认 5 秒可覆盖超时后把“工具超时”作为结果回传给模型让它决定是重试还是换方案。这比直接抛异常友好太多因为模型能根据超时信息调整策略。并发安全则要注意注册中心和工具 handler 的线程模型。注册中心是只读的多个请求同时读取没有问题但工具 handler 里如果操作了共享资源比如写同一个文件、操作同一个数据库连接必须加锁或用连接池。我踩过一个坑两个用户同时在“创建日程”因为用了同一个全局数据库连接出现了互相覆盖的问题。改成每次调用从连接池取独立连接后问题消失。工具无状态是并发安全的前提这个原则值得写进团队的代码规范。写在最后的个人体会做完这一版 Agent 节点和 Tools 体系之后我最大的体会是大模型应用的技术难点不在某个单独环节而在于把“模型会思考”和“系统会执行”这两件事严丝合缝地接起来。工具协议是接口Agent 循环是流程注册中心是管理这三者缺一不可。每次看到用户在我搭的编排器上跑出一个“先查数据、再判断、再执行、最后总结”的智能应用时我都会觉得当初坚持自研、坚持把每个细节抠清楚是值得的。最后再分享一个小技巧工具体系上线前一定要用一个固定的测试集反复跑回归把每个工具的调用成功率、参数正确率、平均轮数记录下来。这组数字比任何架构文档都更能反映你的编排器健康度。后续这个开源系列我还会继续更新下一期准备讲讲编排器的可观测性与调试面板欢迎有同样兴趣的朋友一起交流。