1. 为什么需要一个提示流编排器

做 AI Agent 开发的人，大概率都经历过这样的场景：凌晨两点，手机突然弹出一条信用卡消费提醒，金额不大，但频率极高——每几秒就有一笔。你迷迷糊糊打开后台一看，某个 Agent 卡在了一个循环里，反复调用付费 API，一晚上烧掉了几百块。这不是段子，这是很多 Agent 开发者真实踩过的坑。

我自己第一次做 ReAct 模式的 Agent 时，就遇到过类似的问题。当时设计的是一个自动查资料、总结、再查资料的流程，逻辑上看起来没问题，但实际跑起来之后，模型有时候会陷入“思考→行动→观察→再思考”的死循环，每一步都在调用外部接口，每一步都在产生费用。更麻烦的是，这种循环不是每次都发生，而是偶发性的，你很难在测试阶段完全覆盖。

所以，从 0 到 1 打造一个 AI 提示流编排器，核心要解决的不只是“让 Agent 能跑起来”，而是“让 Agent 在可控的边界内跑”。这个边界包括：调用次数上限、费用上限、时间上限、循环检测、异常熔断。说白了，就是给 Agent 装一个看门狗和熔断器，别让它失控。

这篇文章适合谁看？如果你正在做 Agent 开发，或者准备做一个多步骤的 AI 工作流编排系统，又或者你已经在用 ReAct 模式构建智能体但还没考虑过运行时安全问题，那这篇内容应该能帮你省下不少冤枉钱。我会从整体设计思路讲起，然后拆解看门狗和熔断器的核心实现，最后分享一些实操中踩过的坑和排查技巧。

2. 整体架构设计与核心思路拆解

2.1 提示流编排器到底在编排什么

先把这个概念说清楚。所谓“提示流编排器”，本质上是一个调度层，它负责管理多个提示节点之间的执行顺序、数据传递和状态流转。一个典型的 Agent 工作流可能包含这些节点：用户输入解析、意图识别、工具选择、工具调用、结果观察、再推理、最终输出。每个节点可能是一次 LLM 调用，也可能是一次外部 API 调用，还可能是一次本地计算。

编排器的职责就是把这些节点串起来，按照预定义的逻辑或者动态决策来推进流程。ReAct 模式是其中一种典型的编排方式：Reason（推理）和 Act（行动）交替进行，模型先思考下一步该做什么，然后执行一个动作，观察结果后再继续思考。这种模式灵活性强，但恰恰因为灵活，才容易失控。

我选择自己实现编排器而不是直接用现成框架，主要原因是可控性。现成的 Agent 框架往往把执行循环封装得很深，你想在中间插入一个检查点或者熔断逻辑，需要改很多地方。而自己写编排器，虽然前期工作量大一点，但每一个环节都是透明的，你想在哪里加看门狗就在哪里加。

2.2 看门狗和熔断器的分工

看门狗和熔断器是两个不同层次的安全机制，很多人会把它们混在一起谈，但实际设计中它们的职责是有区别的。

看门狗更像是一个“心跳监测器”。它关注的是：Agent 还在正常推进吗？每一步是否在合理时间内完成？如果某一步卡住了，看门狗会触发超时处理，强制中断当前步骤，避免整个流程无限等待。在硬件领域，看门狗电路的作用就是定期检查系统是否还在正常运行，如果发现异常就复位。软件层面的看门狗也是类似的思路。

熔断器则更像是一个“累计风险控制器”。它关注的是：Agent 已经消耗了多少资源？调用次数是否超过阈值？费用是否接近上限？是否检测到重复模式？一旦触发熔断条件，整个流程会被强制终止，而不是仅仅中断当前步骤。

两者配合使用：看门狗负责单步级别的超时和异常检测，熔断器负责全局级别的资源控制和循环检测。下面这张表可以更清晰地对比它们的差异：

2.3 为什么选择 ReAct 作为主要编排模式

ReAct 模式的核心优势在于它的动态性。传统的链式调用（Chain）是线性的，你预先定义好步骤一、步骤二、步骤三，然后按顺序执行。但很多实际场景下，你无法预先知道需要几步才能完成任务。比如用户问“帮我对比一下这三款产品的性价比”，Agent 可能需要先搜索产品信息，然后发现某个产品信息不全，再补充搜索，然后进行计算和对比。这个步数是不确定的。

ReAct 通过让模型自己决定下一步行动，解决了步数不确定的问题。但这也带来了新的风险：模型可能永远不决定停止。所以，ReAct 模式必须配合严格的运行时约束才能在生产环境使用。

我在设计编排器时，把 ReAct 循环放在了一个受控的容器里。容器负责维护状态、检查约束、记录日志，而 ReAct 逻辑本身只负责决策。这样做的好处是，约束逻辑和业务逻辑解耦，后续调整阈值或者增加新的检查项时，不需要改动 ReAct 的核心代码。

3. 看门狗的核心实现细节

3.1 单步超时机制的设计与参数选择

看门狗最基础的功能是单步超时检测。每一次 LLM 调用或者工具调用，都应该有一个最大允许执行时间。超过这个时间，就认为该步骤异常，触发中断。

参数选择上，我的经验是这样的：LLM 调用的超时时间一般设置在 30 到 60 秒之间。具体取决于你使用的模型和网络环境。如果是流式输出，超时判断要更细致一些，不能简单地从请求发出开始计时，而是要看两次数据块之间的间隔。我通常设置两个阈值：首字节超时 15 秒，块间超时 10 秒。如果 15 秒内没有收到第一个 token，或者两个 token 之间间隔超过 10 秒，就判定为超时。

工具调用的超时时间则取决于工具本身的性质。查询数据库可能只需要几秒，但调用一个外部爬虫服务可能需要几十秒。我一般会给每个工具单独配置超时时间，而不是用一个全局值。配置方式如下：

TOOL_TIMEOUTS = { "web_search": 20, "database_query": 5, "code_executor": 30, "file_reader": 3, "default": 15 }

实现上，我使用了一个独立的监控线程来检查每个步骤的执行时间。主线程在执行步骤时，会向监控线程注册一个任务 ID 和超时时间。监控线程定期扫描所有活跃任务，如果发现某个任务超时，就设置一个中断标志。主线程在关键检查点读取这个标志，如果发现被中断，就抛出超时异常。

注意：Python 中强制中断一个正在执行的线程是不安全的，所以不要试图直接 kill 线程。正确的做法是设置协作式中断标志，让被监控的代码主动检查并退出。

3.2 心跳检测与假死识别

有些情况下，步骤并没有超时，但实际上已经“假死”了。比如 LLM 返回了一个空响应，或者工具调用返回了一个格式错误的结果，导致后续解析逻辑卡住。这种情况下，单纯依靠超时机制可能无法及时发现。

我的做法是在编排器的主循环中加入心跳检测。每完成一个步骤，就更新一次心跳时间戳。如果连续多个步骤的心跳间隔异常，或者某个步骤的输入输出不符合预期格式，就触发假死告警。

具体实现上，我定义了一个HealthChecker类，它维护以下状态：

• last_heartbeat：上一次成功完成步骤的时间
• consecutive_empty_responses：连续空响应次数
• consecutive_parse_errors：连续解析错误次数
• step_durations：最近 N 步的执行时间列表

当consecutive_empty_responses超过 3 次，或者consecutive_parse_errors超过 2 次，就判定为假死状态，触发熔断。这个阈值的设定需要根据实际业务调整，太高了会漏报，太低了会误报。我一般建议从保守值开始，观察一段时间后再调整。

3.3 看门狗的日志记录与告警

看门狗不仅要能发现问题，还要能记录问题。每一次超时、每一次假死告警，都应该有详细的日志。日志内容至少包括：时间戳、步骤 ID、步骤类型、已执行时间、超时阈值、当前状态快照。

我在实际项目中发现，光有日志还不够，还需要实时告警。因为很多问题发生在半夜，等你第二天看日志的时候，费用已经产生了。所以我在看门狗中集成了一个简单的告警模块，支持邮件和 webhook 两种方式。当触发熔断时，立即发送告警通知。

告警内容要简洁明了，包含关键信息：哪个 Agent、哪个流程、触发了什么条件、当前已消耗资源、建议处理方式。不要发一大堆日志内容，那样反而会被忽略。

4. 死循环熔断器的实现方案

4.1 循环检测的三种策略

死循环是 Agent 开发中最常见也最危险的问题。我总结下来，循环检测有三种基本策略，可以组合使用。

第一种是步数上限。这是最简单粗暴的方式，设定一个最大步数，比如 20 步或者 30 步，超过就强制终止。这种方式的好处是实现简单，缺点是阈值不好定。设太小了，复杂任务跑不完；设太大了，费用还是可能超。

第二种是重复模式检测。通过比较最近几步的输入输出，判断是否出现了重复。比如连续三次调用了同一个工具，传入了相同的参数，那大概率是循环了。实现上可以用哈希或者相似度计算。我一般用简单的字符串哈希，如果连续三步的（工具名+参数）哈希值相同，就触发熔断。

第三种是状态空间检测。这种方式更复杂一些，它维护一个已访问状态的集合，每次执行步骤前检查当前状态是否已经出现过。如果出现，说明进入了循环。状态的定义可以包括：当前对话历史、当前工具调用结果、当前内部状态变量等。这种方式最准确，但计算开销也最大。

实际使用中，我通常组合使用第一种和第二种。步数上限作为兜底，重复模式检测作为主要手段。状态空间检测只在特定场景下启用，比如流程特别复杂、费用特别高的情况。

4.2 费用追踪与预算控制

费用控制是熔断器的另一个核心功能。每一次 LLM 调用和工具调用都应该被记录费用，并累计到当前流程的总费用中。当总费用接近预算上限时，触发熔断。

费用追踪的实现要点在于：每个模型和每个工具的单价要预先配置好，调用时根据实际用量计算费用。对于 LLM，用量包括输入 token 数和输出 token 数；对于工具，可能是调用次数或者执行时间。

PRICING = { "gpt-4": {"input": 0.00003, "output": 0.00006}, "gpt-3.5-turbo": {"input": 0.0000015, "output": 0.000002}, "web_search": {"per_call": 0.001}, "code_executor": {"per_second": 0.0001} }

预算控制我建议设置两级阈值：预警阈值和熔断阈值。预警阈值设在预算的 70% 到 80%，触发时发送告警但继续执行；熔断阈值设在预算的 95% 到 100%，触发时立即终止。这样既给了缓冲空间，又不会超支太多。

提示：预算上限不要设得太紧。我见过有人把预算设成刚好够跑完一次流程，结果因为模型输出长度波动，正常流程也被熔断了。建议预留 20% 到 30% 的余量。

4.3 熔断后的状态保存与恢复

熔断发生后，流程被终止，但状态不能丢。用户可能希望知道流程执行到了哪一步，已经产生了什么结果，是否可以从中断处恢复。

我的做法是在每次步骤完成后，将当前状态序列化保存到持久化存储中。状态包括：对话历史、已执行步骤列表、累计费用、当前变量值等。熔断发生时，这些状态已经保存好了，可以直接读取。

恢复方面，我提供了两种模式：完全重跑和断点续跑。完全重跑就是从头开始，适合流程较短、费用较低的场景。断点续跑则是从中断的步骤继续，适合流程较长、已经产生了有价值中间结果的场景。断点续跑需要确保步骤的幂等性，否则可能出现重复调用的问题。

5. 实操过程与核心环节实现

5.1 编排器主循环的代码结构

编排器的主循环是整个系统的核心。我把它设计成一个状态机，每个循环周期包含以下阶段：检查熔断条件、选择下一步行动、执行行动、记录结果、更新状态。

class Orchestrator: def __init__(self, config): self.config = config self.state = InitialState() self.watchdog = Watchdog(config.timeouts) self.circuit_breaker = CircuitBreaker(config.limits) self.cost_tracker = CostTracker(config.pricing) self.logger = StepLogger() def run(self, user_input): self.state.set_input(user_input) while not self.state.is_terminal(): if self.circuit_breaker.should_trip(self.state): self.logger.log_trip(self.state) return self.state.get_error_result() action = self.decide_next_action() try: result = self.watchdog.execute_with_timeout( action, timeout=self.get_timeout(action) ) self.state.update(action, result) self.cost_tracker.record(action, result) self.logger.log_step(action, result) except TimeoutError: self.state.mark_step_timeout(action) if self.state.consecutive_timeouts > 2: self.circuit_breaker.trip("consecutive_timeouts") return self.state.get_error_result() return self.state.get_final_result()

这个结构看起来简单，但每个环节都有细节需要注意。比如decide_next_action方法，它需要根据当前状态和 ReAct 逻辑来决定下一步是继续推理、调用工具、还是输出最终结果。这个决策过程本身也可能出错，所以也需要被看门狗保护。

5.2 看门狗与熔断器的集成方式

看门狗和熔断器虽然职责不同，但它们需要共享状态信息。看门狗记录的超时次数、假死次数，应该作为熔断器的输入条件之一。熔断器记录的累计费用、总步数，也应该反馈给看门狗用于调整监控策略。

我采用的方式是让它们共享一个ExecutionState对象。看门狗和熔断器都持有这个对象的引用，读取和写入相关字段。这样避免了数据不一致的问题，也简化了集成逻辑。

集成时需要注意线程安全问题。如果看门狗在独立线程中运行，而熔断器在主线程中检查状态，就需要加锁保护共享状态。我一般用简单的互斥锁就够了，因为状态更新的频率并不高。

5.3 配置管理与动态调整

看门狗和熔断器的参数不应该硬编码在代码里，而应该通过配置文件管理。这样不同环境、不同任务可以使用不同的参数，也方便动态调整。

我的配置文件结构大概是这样的：

watchdog: llm_first_byte_timeout: 15 llm_inter_chunk_timeout: 10 tool_timeouts: web_search: 20 database_query: 5 max_consecutive_timeouts: 2 max_consecutive_empty: 3 circuit_breaker: max_steps: 30 max_cost: 1.0 cost_warning_ratio: 0.8 repeat_detection_window: 3 repeat_similarity_threshold: 0.95

动态调整方面，我提供了一个管理接口，可以在运行时修改这些参数。比如发现某个任务类型经常触发熔断，可以临时调高阈值，观察一段时间后再决定是否永久修改。

6. 常见问题与排查技巧实录

6.1 超时误报与漏报的平衡

超时误报是指步骤实际上还在正常执行，但被看门狗误判为超时。漏报则相反，步骤已经卡死了，但看门狗没有及时发现。

误报的常见原因是超时阈值设得太紧。比如 LLM 在高峰期响应变慢，原本 10 秒能返回的结果现在需要 20 秒，如果阈值还是 15 秒，就会误报。解决方法是根据历史数据动态调整阈值，或者设置一个宽限期，第一次超时只告警不中断，连续超时才中断。

漏报的常见原因是监控粒度太粗。比如只监控了整个步骤的总时间，没有监控中间的心跳。如果步骤内部卡在了某个子环节，总时间可能还没超，但实际上已经卡死了。解决方法是在关键子环节也加入心跳检测。

6.2 循环检测的误判处理

循环检测的误判是指 Agent 实际上没有进入死循环，但被熔断器误判为循环。这种情况通常发生在 Agent 需要重复执行相似操作但参数略有不同的场景。比如批量处理多个文件，每次都是读取文件、处理、写入，工具名相同，参数只有文件名不同。

如果循环检测只看工具名，就会误判。所以我在实现时，会把参数也纳入比较范围，并且使用相似度而不是完全相等来判断。相似度阈值设在 0.95 以上，只有高度相似才判定为循环。

另外，我还会检查步骤之间的时间间隔。如果两次相似调用的间隔很短，更可能是循环；如果间隔较长，可能是正常的重复操作。

6.3 熔断后如何优雅降级

熔断发生后，直接返回错误给用户体验很差。更好的做法是优雅降级：返回已经完成的部分结果，并说明哪些部分未能完成。

比如一个研究型 Agent，已经完成了资料搜集和初步分析，但在生成最终报告时触发了熔断。这时可以返回已搜集的资料和分析结果，并提示用户“报告生成未完成，以下是已获取的信息”。这样用户至少拿到了一些有价值的内容，而不是一个冷冰冰的错误。

实现上，我让每个步骤都标记自己的输出是否“可部分交付”。在熔断时，编排器收集所有可部分交付的输出，组装成一个降级结果返回。

6.4 常见问题速查表

6.5 几个容易被忽略的细节

第一个细节是时钟同步。如果看门狗和主循环在不同的机器上运行，时钟不同步会导致超时判断出错。我建议使用单调时钟而不是系统时钟来计算时间间隔，避免系统时间调整带来的影响。

第二个细节是异常传播。看门狗抛出的超时异常，需要被主循环正确捕获和处理。如果异常在传播过程中被其他中间件吞掉了，熔断逻辑就不会触发。我一般会在主循环的异常处理中显式检查超时异常类型。

第三个细节是资源清理。熔断发生后，可能有一些后台任务还在运行，比如异步的 API 调用或者文件写入。需要在熔断处理中显式取消这些任务，避免资源泄漏。

7. 一些实操后的个人体会

这套看门狗和熔断器的设计，我在几个项目中实际使用下来，最明显的感受是：约束不是限制能力，而是让能力可持续。没有约束的 Agent 就像没有刹车的车，短距离可能跑得快，但迟早会出事。

参数调优方面，我的建议是不要追求一次到位。先设一个保守的值，跑一段时间，收集数据，再逐步调整。我通常会记录每次熔断和超时的详细上下文，定期回顾，看看哪些是真正的异常，哪些是误报，然后针对性地调整。

还有一个体会是，日志和告警的质量比数量重要。早期我设置了非常详细的日志，结果排查问题时反而被淹没在信息里。后来我改成结构化日志，关键信息用固定字段，非关键信息用附加字段，排查效率高了很多。

最后分享一个小技巧：在开发阶段，可以把熔断阈值设得很低，比如最大步数设为 5，最大费用设为 0.01，这样能快速暴露循环和费用问题。等流程稳定后，再逐步放宽到生产值。这个做法帮我省了不少调试时间。