PTC架构：将Agent工具编排从模型循环剥离到运行时

做Agent落地的人，十有八九都被“工具编排”折磨过。最初版本的工具调用往往写死在模型循环里，模型返回一个tool_call，应用执行一次，结果再塞回messages里让模型继续推理。这种模式在工具少、链路短的时候很香，但一旦工具超过五个、调用链超过两步，问题就开始冒头——延迟叠加、失败无法回退、并发控制全靠手写、换个模型要重构一遍。这篇要聊的PTC（Plan-Tool-Call，把“规划-工具调用-回调”抽到运行时统一调度的编排范式），就是我在几个Agent项目里反复尝试后沉淀下来的一套解法。核心思路一句话：模型只负责把用户的请求翻译成结构化意图，工具能不能调、按什么顺序调、失败了怎么处理，全部交给运行时。这篇文章适合正在做Agent平台、或者被function calling循环搞到头疼的工程师参考。

1. 模型循环里做工具编排，痛点到底在哪

先别急着上方案，把问题拆透。我见过太多项目，一开始图省事，把全部工具调用逻辑塞进模型循环里，等到业务量上来，代码已经变成一团乱麻。搞清楚痛点在哪里，才知道PTC这步棋到底解决了什么。

1.1 一眼看穿：模型循环是怎么拖慢整个应用的

传统的模型循环长这样：用户输入，模型判断需要调用工具，返回一个tool_call指令，应用端执行对应函数，拿到结果后再拼回messages里，然后重新请求模型做下一轮推理。逻辑上很顺，但性能上很吃亏。每调用一次工具，都要等一次完整的模型生成。模型生成不是瞬时操作，一次请求通常要两到八秒，视模型大小和排队情况而定。

可以算一笔账。假设一个任务需要调用三个工具，第一步模型判断出需要两个工具，第二步根据第一个工具的结果调用第二个，第三步根据第二个结果调用第三个。三步下来，至少三次模型往返，每次按四秒算，光模型等待就十二秒，再加上工具自身执行时间，用户体感已经逼近二十秒。如果某一步工具返回了异常数据，模型还得重新推理一次，又是四秒起步。这个延迟在demo阶段能忍，上了生产环境会被用户投诉到怀疑人生。

更隐蔽的问题是，模型循环天然是串行的。哪怕两个工具之间完全没有数据依赖，比如同时查两个城市的天气，模型也会一个接一个地返回tool_call，应用端只能老老实实按顺序执行。并发能力被模型生成节奏卡死，吞吐量上不去，这是模型循环在架构上的天花板，不是靠优化代码能解决的。

1.2 工具编排逻辑和模型强耦合，换个模型就要重写

模型循环的第二个大坑，是编排逻辑和具体模型厂商的协议深度绑定。拿OpenAI和开源模型对比，同样是把工具描述传给模型，有的用functions字段，有的用tools字段，多工具调用有的是单次返回多个tool_calls，有的是分批返回，强制工具名称的写法也不一样。

最难受的是迁移场景。我之前把一个项目的底层模型从闭源模型切到本地部署的开源模型，原本代码里全是指定tool_calls数组的写法，新模型一次只返回一个工具调用，导致原本设计成“一次循环处理多个并行工具”的逻辑全部作废。为了兼容两套返回格式，不得不在循环里加了一堆分支判断，代码长了不说，调试时两个模型返回结构不一样，心智负担直接翻倍。工具编排一旦混进模型循环，模型的协议细节就变成了业务代码的一部分，换模型等于重构，这个账怎么算都不划算。

1.3 重试、并发、超时这些“脏活”没人管

模型循环模式里，工具执行几乎都是裸奔状态。开发者最常写的代码就是try-except包一层，工具报错就随便返回一个“执行失败”给模型，让模型自己想辙。但如果失败的场景是“第三个工具调用失败，但前两个已经产生了副作用”，这就不是简单的重试能解决的。比如订酒店成功、订机票失败，重试的时候会不会重复预订酒店？这种业务级的编排逻辑，塞在模型循环里会很快失控。

除此之外，超时控制也是大问题。模型循环里工具执行如果卡住，整个循环就卡住，模型不会主动帮我们结束这个死等。一次调用卡三十秒，用户早就刷新页面了。还有重试策略，一个偶发网络错误导致的失败，和一个因为参数不合法导致的失败，显然不应该用同一种处理方式。但这些策略在模型循环里根本无从谈起，因为循环的注意力全在“模型下一步生成什么”，根本没人关心工具执行层面的调度质量。

2. PTC架构的核心设计：模型给意图，运行时去执行

既然模型循环这条路走不通，那就换个思路：把工具编排从模型推理过程中剥离出来。模型还是那个会思考的大脑，但它思考的结果不再是“直接调这个函数”，而是“我打算做这件事”的结构化表达，真正去调用工具的，是独立的运行时执行引擎。

2.1 PTC的三层模块划分

PTC模式把系统拆成三个独立模块，边界清晰，各自演进。

第一层是意图解析层。模型输出被严格约束成结构化意图，而不是自由的工具调用指令。意图只描述用户要达成的目标和必要参数，不涉及任何实际执行。第二层是工具注册层。所有可被调用的工具都以元数据的形式登记在注册表里，包括工具名称、描述、参数JSON Schema、依赖关系、超时时间等。注册表的意义在于，执行引擎可以用统一的方式发现和校验工具，模型不用关心工具内部怎么实现。第三层是执行引擎。引擎拿到意图后，负责解析当前是否有缺失参数、判断依赖顺序、并发调度、超时控制、失败重试，以及把中间结果写回共享Buffer，供后续节点使用。

这三层各管一摊：模型管“要做什么”，注册表管“有哪些工具”，执行引擎管“怎么把事做成”。原来纠缠在模型循环里的职责被拆开了，每一块都能独立的进行单元测试。

2.2 意图数据模型设计

PTC落地最关键的一步，是定义出一套稳定的意图数据模型。我在项目中实践下来的经验是，至少要设计三类意图。

第一类是tool_call意图，表示“我想调用某个工具”，包含工具名和参数对象。第二类是task意图，表示“这是一个需要多步骤才能完成的任务”，包含一个子目标和上下文上下文要求，引擎会基于它创建执行计划。第三类是human意图，表示“当前参数不足，需要向用户澄清”，这是运行时向用户发起追问的通道。

三类意图的统一格式类似这样：

@dataclass class Intent: intent_type: str # tool_call / task / human tool_name: str = "" params: dict = None task_description: str = "" ask_user: str = "" request_id: str = ""

模型输出的任何内容都会被校验后转成这个结构，不符合schema的输出一律判为解析失败，要求模型重新生成。别小看这层约束，有了它，执行引擎才能提前判断“这个参数是不是合法枚举”“这个日期格式对不对”，而不是等工具执行到一半才发现参数是脏数据。

2.3 依赖解析与执行顺序：DAG才是核心

工具之间的依赖关系要交给执行引擎处理，怎么建模？我的做法是，在工具注册表里，为每个工具声明它依赖的上游节点。例如“查询天气”没有依赖，但“根据天气生成穿衣建议”依赖“查询天气”的输出。这样一组工具就构成一个有向无环图DAG。

引擎运行时的调度规则很简单：一个节点不满足条件时，不能执行；节点的上游全部完成后，节点才进入可执行队列；多个没有依赖关系的节点可以并发执行。这里不必去实现一个复杂的通用DAG计算引擎，用一个轻量的事件循环就能跑起来，核心数据结构是一个待执行队列和一层依赖计数。

举例来说，用户请求“帮我根据天气订一张明早去上海的机票”。意图解析后产生两个节点：天气查询节点和机票预订节点，其中机票节点依赖天气节点的结果。引擎先执行天气节点，拿到结果写入Buffer，再检查机票节点的依赖计数归零，然后才触发机票查询工具。整个过程不需要模型介入，引擎自己就能完成调度。这套设计的好处是，模型只需要负责“翻译”，复杂的流程编排成了纯工程问题。

3. 实操：从模型循环改造到PTC的完整过程

说完了理念，看看到底怎么落代码。我挑一个相对完整的例子走一遍：一个简单的出行助手，涉及天气查询和机票查询两个工具，演示怎么把工具调用从模型循环搬进运行时。

3.1 先说环境：这个改造需要哪些基础件

我是用纯Python实现的，依赖极少。环境是Python 3.10以上，模型接口用一个OpenAI兼容的本地服务，通过requests调用即可。不引入额外的Agent框架，因为框架会自带一套编排规则，反而干扰我们理解PTC的核心思路。

整个工程的结构分四个文件：intent.py放意图数据模型，registry.py放工具注册表，engine.py放执行引擎，main.py模拟一次完整请求。为了便于演示，工具函数先做桩实现，返回假数据。

3.2 第一步：把工具调用改成意图输出

改造前，我们直接让模型输出tool_call列表，然后程序照做。改造后，需要在system prompt里明确告诉模型：你的任务只是理解用户意图，输出结构化的意图JSON，禁止提到任何执行细节。

我用的prompt模板如下：

你是一个意图理解模块。用户会提供一段自然语言请求。 请解析请求，输出JSON，格式为： {"intent_type": "tool_call", "tool_name": "query_weather", "params": {...}} 或者 {"intent_type": "task", "task_description": "根据目的地天气，为用户推荐合适航班"} 注意： 1. 你只能意图，不能直接调用任何工具。 2. 如果参数缺失，输出intent_type为human，并说明需要用户补齐什么信息。

这一步是PTC和传统模式的分水岭。以前模型返回的是“我要调用函数A”，现在模型返回的是“用户想达成目的B”，工具选择和执行退到了模型视野之外。从Prompt工程角度看，模型的任务变得简单了，输出的稳定性也会更好。

3.3 第二步：实现一个轻量工具注册表

工具注册表的代码不复杂，但它是执行引擎能“看见”所有工具的基础。

class ToolRegistry: def __init__(self): self._tools = {} def register(self, name, handler, schema, dependencies=None): self._tools[name] = { "handler": handler, "schema": schema, "dependencies": dependencies or [], } def get(self, name): return self._tools.get(name) def names(self): return list(self._tools.keys()) registry = ToolRegistry() registry.register( name="query_weather", handler=lambda params: {"temperature": 28, "condition": "晴"}, schema={"type": "object", "properties": {"city": {"type": "string"}}}, ) registry.register( name="query_flight", handler=lambda params: {"flight": "MU5123", "departure": "08:30"}, schema={"type": "object", "properties": {"date": {"type": "string"}, "from": {"type": "string"}, "to": {"type": "string"}}}, dependencies=["query_weather"], # 仅演示一个依赖关系 )

注册表里存放的不仅是函数指针，还包括参数schema和依赖声明。执行引擎不需要知道工具内部实现，只需要知道三个关键信息：合法参数长什么样、工具的调用边界是什么、必须先做哪个上游步骤。

3.4 第三步：执行引擎编排循环

执行引擎是核心。引擎持有一个待执行队列和一个Buffer。Buffer用来存放所有中间节点的输出，每个意图执行后的结果都会写入Buffer。引擎循环可以这样实现：

class ExecuteEngine: def __init__(self, registry): self.registry = registry self.buffer = {} def add_task(self, intent): # 简单起见，每个tool_call意图直接变成一个执行节点 self.pending.append({ "intent": intent, "dependencies": self.registry.get(intent.tool_name)["dependencies"], "status": "pending", }) def run(self): while self.pending: ready = [ t for t in self.pending if t["status"] == "pending" and all(dep in self.buffer for dep in t["dependencies"]) ] if not ready: # 依赖没法满足，报错或走人工澄清 raise RuntimeError("circular dependency or missing parameter") for task in ready: task["status"] = "running" tool = self.registry.get(task["intent"].tool_name) result = tool["handler"](task["intent"].params) self.buffer[task["intent"].tool_name] = result task["status"] = "done" self.pending.remove(task) return self.buffer

这里还不算一个生产级引擎，但核心机制都有了：pending队列负责等待，依赖判断用“上游结果是否已在Buffer中”来支撑，不涉及模型的反复调用。真实项目里，我会在这个基础上加并发执行，直接把ready列表里的任务丢进线程池；加超时控制，给每个工具包裹一个asyncio.wait_for；加失败重试，在任务状态里引入retry_count字段。

3.5 一个真实任务的完整运行记录

用下面这个请求走一遍完整流程：用户说“我想知道上海明天天气怎么样，如果天气好，帮我订一张去上海的最早航班”。

模型解析后，可能返回这样一个意图序列：

[ {"intent_type": "tool_call", "tool_name": "query_weather", "params": {"city": "上海", "date": "明天"}}, {"intent_type": "human", "ask_user": "确认航班出发地"} ]

第一意图进入引擎，执行天气查询，结果写入Buffer。第二意图是human意图，引擎不会去执行工具，而是暂停，把“需要确认出发地”这个信息带回给用户。用户补充“从北京出发”后，再次请求模型，模型输出第三意图：

{"intent_type": "tool_call", "tool_name": "query_flight", "params": {"date": "明天", "from": "北京", "to": "上海"}}

引擎检查依赖，发现query_flight依赖query_weather，而Buffer里已经有结果，于是执行航班查询。整个流程模型只参与了两轮推理，中间那一次天气查询结果没有经过模型，直接就进了Buffer。相比原模型循环，这里省了至少一次模型往返，而且航班查询的触发时机完全由引擎控制，与模型生成速度快慢无关。

这个例子里，模型的角色被削弱成了纯粹的“意图输出器”，真正干活的编排调度，已经牢牢握在运行时手里。

4. 落地过程中踩过的坑与排查记录

最后分享一些真实落地中踩过的坑。有些问题不深入做一遍项目根本预见不到，把它们记下来，能省下一整天的排查时间。

4.1 模型幻觉参数：运行时校验是唯一防线

模型不是数据库，它很容易把用户话里的模糊信息“脑补”成具体参数。经典场景是用户说“去广州出差”，意图解析时模型可能直接给query_flight传入日期“2025-07-01”，但这个日期用户从未提起。更可怕的是，它可能编出一个不存在的城市名。

防幻觉不能指望提示词，唯一可靠的是运行时校验。注册表里每个工具的schema，执行引擎都要在调用前做一次JSON Schema校验，类型、枚举、必填字段逐项检查。校验不通过，不调用工具，而是生成一个human意图，向用户确认真实参数。我见过最坑的一次，模型把城市名从“长沙市”写成了“长沙市岳麓区”，正常执行看着没问题，但工具内部拿这个字符串去匹配数据库，返回了空数据。有了运行时schema校验，至少能在第一步拦截明显不合理的参数。

4.2 工具抖动：同样的输入，模型经常变换工具名

模型对工具名的选择并不稳定。用户说“查价格”，模型可能调用query_price，也可能调用get_product_price，同一个意图出现两种不同的工具名。在模型循环里，这种抖动会直接导致调用失败；在PTC里，则表现为执行引擎找不到对应的注册表项。

我给的解法有两层。第一层是注册环节加别名：注册工具时声明多个别名，执行引擎在查找时忽略大小写并匹配别名列表。第二层是在意图解析前加一个预处理规则，把用户意图中明确出现的领域关键词直接映射到工具上，不依赖模型选择关键分支。例如用户说“帮你查一下机票“，预处理规则直接把工具锁定为query_flight。这层规则写多了会有点啰嗦，但针对高频场景非常有效，能大幅降低模型输出的随机性。

4.3 状态恢复与可观测性：没有日志，排查就是在赌运气

把编排搬进运行时以后，整个执行过程变成多步异步操作，一旦出问题，“当时哪一步执行了什么”就成了关键线索。我在早期版本里没重视日志，任务失败时只能看到一行异常堆栈，完全不知道是模型解析错了，还是工具依赖没满足，还是重试耗尽了。

现在的做法是：在引擎关键位置打结构化日志，每条日志包含request_id、执行节点名、当前状态、依赖是否满足、Buffer快照。这样任何一个失败任务都能完整回放。比如一条日志写着：

request_id=8f2a11, node=query_flight, status=skipped, dependency=query_weather:missing

马上就能定位是上游节点没执行，还是执行了但没写入Buffer。这个习惯在工具数量少的时候显得多余，但工具超过十个以后，它就是救命稻草。

4.4 超时、重试与幂等控制

工具执行不一定都是毫秒级返回的。有些工具内部要调第三方API，一次请求可能耗时十几秒；有些外部服务不稳定，偶发超时。传统模型循环里，工具超时是灾难性的，卡住整个循环；PTC里，超时和重试是执行引擎的基本特性。

我在引擎里给每个工具配了独立超时时间和重试策略。临时故障（网络抖动、500）用指数退避重试；参数类故障直接判死，不重试。更重要的是幂等控制。PTC引擎天然会有重试机制，如果第一次调用工具执行成功，但回调阶段网络断了，引擎重试同一工具时，可能引入重复副作用。我的做法是，在工具注册时声明该工具是否幂等，非幂等工具再加上请求级别的idempotency_key，同一个request_id下同一个节点只允许执行一次。

最后再分享一点个人体会

这套PTC改造做完之后最直观的感受是，代码里那些“一层嵌一层的if-else判断模型下一步要什么”的段落消失了，取而代之的是清晰的信任边界：我信任模型能理解意图，但不信任它能把工具调度做好；我信任注册表能描述工具能力，但不信任它自己能随机应变。于是模型的归模型，运行时的归运行时。建议刚开始尝试的朋友不要一上来就做通用Agent平台，挑一条核心工具链——比如一个查天气加订票的小场景——先跑通PTC的闭环，观察一下延迟和失败率的变化，再逐步扩大工具数量。踩过几次坑之后你会觉得，这个模式比模型循环省心太多了。