1. 为什么要把决策权从LLM手里拿回来第一次接触Embabel这个框架的时候我正在做一个多步骤任务编排的小工具。当时用的方案很直接把任务描述丢给大模型让它自己决定下一步调什么工具、传什么参数、什么时候结束。刚开始跑demo确实惊艳模型能自己规划路径看起来像那么回事。但一上真实场景就露馅了——同样的输入今天跑和明天跑结果不一样稍微复杂一点的任务模型会在某个环节开始“自由发挥”调用不存在的工具或者把参数格式搞错最要命的是你没法跟产品经理解释为什么这次走了A路径而不是B路径因为决策过程完全是个黑盒。Embabel这个框架的核心思路就是把这部分决策权从LLM手里收回来交给确定性的代码逻辑去控制。LLM只负责它擅长的事情——理解语义、生成内容、做模糊判断而流程走向、工具选择、状态流转这些需要稳定可复现的环节由开发者用显式的规则来定义。这个思路其实不新鲜工作流引擎、状态机、规则引擎都是干这个的但Embabel把这件事和Agent场景结合得比较自然用起来不别扭。这篇文章适合谁看如果你正在做Agent相关的应用被LLM的不确定性折磨过或者你正准备从“纯Prompt驱动”转向“混合编排”的方案那这篇笔记里的经验应该能帮你少走一些弯路。我会从整体设计思路讲到具体实现细节包括我踩过的坑和最后跑通的方案尽量把每个决策背后的原因说清楚。2. 核心设计思路拆解2.1 决策权分离的基本模型Embabel的设计哲学可以用一句话概括LLM做它该做的事代码做它必须做的事。具体来说它把Agent的执行过程拆成了三层规划层由开发者定义任务的可能路径和状态转移条件这部分是确定性的不依赖LLM执行层每个具体步骤的实际操作可能是调用LLM生成内容也可能是调用外部API、查数据库、做计算决策层在关键分叉点决定走哪条路。Embabel允许你在这里选择用规则判断还是用LLM判断但默认推荐规则优先这个分层的关键在于决策层和执行层是解耦的。LLM可以在执行层里自由发挥但它的输出会被约束在决策层定义的框架内。举个例子一个客服Agent需要判断用户意图是“查订单”还是“退换货”传统做法是让LLM直接输出意图标签然后路由。Embabel的做法是先让LLM输出结构化的意图描述然后用规则引擎去匹配这个描述匹配不上的再走LLM兜底判断。这样大部分常见情况都是确定性的只有边缘case才依赖模型。2.2 为什么不用纯Prompt方案我试过纯Prompt的方案就是在一个大System Prompt里把所有工具定义、决策规则、输出格式都写进去让模型自己按规则走。这个方案在简单场景下能跑但有几个绕不过去的问题上下文长度限制。当工具数量超过20个决策规则超过50条的时候Prompt会变得非常长模型对中间部分的注意力会下降经常忽略一些关键约束。Embabel把规则从Prompt里抽出来用代码管理Prompt只保留当前步骤需要的信息上下文压力小很多。调试困难。纯Prompt方案出问题时你只能看到输入和输出中间决策过程是黑盒。Embabel的每一步决策都有日志记录哪个规则匹配了、哪个条件没满足、LLM在哪个环节被调用了都能追溯。版本管理混乱。Prompt的修改没有类型检查改了一个词可能影响完全不相干的场景。Embabel的规则用代码写有类型系统兜底改错了编译期就能发现。2.3 状态管理的设计考量Embabel的状态管理是我觉得设计得比较巧妙的地方。它没有用传统的全局状态机而是采用了分层状态局部上下文的模式。每个执行步骤有自己的局部状态步骤之间通过明确定义的接口传递数据。这样做的好处是单个步骤的状态变化不会影响其他步骤降低了耦合每个步骤可以独立测试不需要构造完整的全局状态状态传递是显式的不会出现“某个隐藏状态被意外修改”的情况我实际用下来这个设计在任务步骤超过10个的时候优势特别明显。传统全局状态机到后面会变成一团乱麻谁改了哪个字段根本查不出来。Embabel这种局部状态的方式每个步骤的输入输出都很清晰排查问题的时候直接看对应步骤的日志就行。3. 核心细节解析与实操要点3.1 规则定义的关键参数Embabel的规则定义有几个核心参数需要特别注意我一个个说优先级priority当多条规则同时匹配时优先级高的先执行。这个参数看起来简单但实际用的时候很容易踩坑。我的经验是兜底规则的优先级要设成最低比如用LLM做模糊判断的那条规则优先级设成0或者负数确保所有确定性规则都匹配失败后才走它。匹配条件conditionEmbabel支持多种条件类型包括字段相等、范围判断、正则匹配、自定义函数等。这里有个细节条件判断的顺序会影响性能。把计算成本低的条件放前面比如字段相等判断把需要调用外部服务的条件放后面。我有个项目里把数据库查询条件放在了第一位结果每次规则匹配都要查一次库后来调整顺序后性能提升了将近三倍。执行动作action规则匹配后执行的操作。Embabel允许action返回一个状态码用来指示下一步走向。这里要注意的是action应该是幂等的因为框架在某些异常情况下可能会重试。如果你的action有副作用比如发邮件、扣款一定要做好去重处理。3.2 LLM调用的边界控制虽然Embabel把决策权收回来了但LLM调用仍然是核心环节。怎么控制LLM的调用边界我总结了几个要点输入约束给LLM的输入要尽可能结构化。Embabel提供了模板机制你可以定义输入模板只把当前步骤需要的字段传给LLM。我见过有人把整个上下文都塞给LLM结果模型被无关信息干扰输出质量很差。输出约束LLM的输出必须符合预定义的结构。Embabel支持JSON Schema校验如果模型输出不符合schema会自动重试或者走降级逻辑。这个机制非常关键没有输出校验的LLM调用就是在裸奔。超时和重试LLM调用可能超时Embabel允许你配置超时时间和重试策略。我的建议是超时时间设成正常响应时间的2-3倍重试次数不超过2次超过就降级到规则兜底。3.3 状态传递的实操细节状态传递这块我踩过不少坑说几个关键点数据类型要明确。Embabel是强类型的状态字段的类型必须明确定义。我一开始图省事用了泛型Map结果运行时各种类型转换错误。后来改成显式的数据类编译期就能发现大部分问题。状态字段要精简。不要把所有中间结果都塞进状态里只保留下一步需要的数据。状态字段太多会导致序列化开销大而且容易混淆。状态版本要管理。当你的流程需要修改时旧版本的状态数据可能和新代码不兼容。Embabel支持状态版本号建议在项目初期就加上这个机制后面改流程的时候会省很多事。4. 实操过程与核心环节实现4.1 环境准备与基础配置先说一下我的环境Python 3.10Embabel用的是当时最新的稳定版。安装过程没什么特别的pip装完就行。但配置环节有几个地方需要注意# 基础配置示例 from embabel import Agent, Rule, State # 定义状态结构 class OrderState(State): user_id: str order_id: str None intent: str None confidence: float 0.0 retry_count: int 0 # 初始化Agent agent Agent( nameorder_assistant, state_classOrderState, max_steps20, # 最大执行步数防止死循环 timeout30.0 # 全局超时单位秒 )max_steps这个参数很重要我建议一定要设。没有这个限制的话如果规则设计有环Agent会一直跑下去。我设成20是基于经验大部分任务在10步内能完成20步还没完成的基本就是出问题了。4.2 规则链的编写与调试规则链是Embabel的核心我拿一个实际场景来演示。假设我们要处理用户的订单相关请求流程是这样的# 规则1意图识别 agent.rule(priority100) def identify_intent(state: OrderState): 用LLM识别用户意图 prompt f分析以下用户输入判断意图类别{state.user_input} result llm.invoke(prompt, output_schema{ intent: str, confidence: float }) state.intent result[intent] state.confidence result[confidence] return intent_identified # 规则2高置信度直接路由 agent.rule(priority90, conditionstate.confidence 0.8) def route_by_intent(state: OrderState): 置信度高时直接按意图路由 routes { query_order: handle_query, return_order: handle_return, cancel_order: handle_cancel } return routes.get(state.intent, handle_unknown) # 规则3低置信度走澄清流程 agent.rule(priority80, conditionstate.confidence 0.8) def ask_clarification(state: OrderState): 置信度低时向用户澄清 state.clarification_needed True return wait_for_clarification调试的时候Embabel提供了trace功能可以看到每一步匹配了哪条规则、状态怎么变化的。我一般会在开发环境把trace级别调到DEBUG生产环境调到WARN。4.3 参数计算与选择过程在规则条件里经常需要做一些计算比如根据用户等级决定处理优先级。这里有个细节计算逻辑要尽量简单复杂的计算应该抽成独立的函数在规则里只做结果判断。def calculate_priority(user_level: str, order_amount: float) - int: 计算处理优先级 base {vip: 100, normal: 50, new: 10}.get(user_level, 10) if order_amount 1000: base 20 elif order_amount 500: base 10 return base agent.rule(priority70) def set_priority(state: OrderState): state.priority calculate_priority(state.user_level, state.order_amount) return priority_set这个计算函数我单独写了单元测试确保各种边界情况都覆盖到。规则里只调用函数拿结果不写复杂逻辑这样规则本身很清晰计算逻辑也能独立验证。4.4 完整流程串联把上面的规则串起来一个完整的订单处理流程大概是这样的用户输入进来初始化状态规则1执行LLM识别意图写入状态规则2或规则3根据置信度分流高置信度走具体处理规则低置信度走澄清流程处理完成后规则链结束返回结果整个流程中LLM只在第2步被调用了一次其他步骤都是确定性的规则判断。这就是Embabel的核心价值——把LLM的使用限制在真正需要它的环节。5. 常见问题与排查技巧实录5.1 规则不匹配怎么办这是最常见的问题。Agent跑完发现没有规则匹配直接结束了。排查思路先看trace日志确认当前状态是什么检查规则的condition是否覆盖了当前状态特别注意类型问题比如状态里是字符串100规则里写的是数字100这种不匹配很隐蔽我一般会加一条兜底规则优先级设成-1condition永远为Trueaction里记录一条警告日志。这样至少能知道哪些状态没被覆盖。5.2 LLM输出格式错误LLM输出不符合schema是高频问题。Embabel有自动重试机制但重试也可能失败。我的处理策略是错误类型处理方式重试次数JSON解析失败重新调用附加格式说明2字段缺失重新调用强调必填字段1类型错误尝试类型转换失败则重试1值超出范围截断到合法范围0超过重试次数后走降级逻辑用默认值或者跳过该步骤。5.3 状态传递丢失有时候发现某个字段在后续步骤里是None但明明前面步骤赋值了。原因通常是状态类定义时字段名拼写错误步骤之间用了不同的状态实例序列化/反序列化过程中字段丢失我的经验是每个步骤开始和结束时都打印一次关键状态字段这样能快速定位是哪一步丢的。5.4 性能问题排查规则链长了之后性能会下降。我遇到过规则匹配耗时超过500ms的情况排查后发现是某个condition里做了数据库查询。解决办法是把查询结果缓存到状态里condition只做内存判断。另一个性能问题是LLM调用太频繁。Embabel允许在规则里调用LLM但不要每个规则都调。我的原则是一个流程里LLM调用不超过3次超过的话就要考虑是不是设计有问题。6. 一些个人体会Embabel这套方案我用下来最大的感受是确定性带来的安心感。以前用纯Prompt方案每次上线新版本都提心吊胆不知道模型会出什么幺蛾子。现在核心流程是代码控制的LLM只在有限范围内发挥作用出问题的概率小了很多即使出了问题也能快速定位。当然也不是没有代价。规则链写起来比Prompt麻烦需要提前想清楚所有分支和状态。但我觉得这个投入是值得的尤其是当你的Agent要处理真实业务的时候稳定性和可解释性比开发速度重要得多。还有一个体会是不要试图用规则覆盖所有情况。我一开始想把所有可能的用户输入都枚举出来写了几百条规则结果维护成本极高。后来改成“规则处理常见情况LLM兜底边缘情况”的模式规则数量控制在50条以内效果好很多。最后分享一个小技巧Embabel的规则可以用装饰器组合把一些通用的条件判断抽成可复用的装饰器。比如require_auth、rate_limit这些写一次到处用规则本身会简洁很多。这个模式我是从Web框架的中间件设计里借鉴过来的在Embabel里同样适用。 
长河君 · 2026/10/18 9:28:00 · 阅读 1.2k Embabel框架实战：如何把决策权从LLM手中拿回来
1. 为什么要把决策权从LLM手里拿回来第一次接触Embabel这个框架的时候我正在做一个多步骤任务编排的小工具。当时用的方案很直接把任务描述丢给大模型让它自己决定下一步调什么工具、传什么参数、什么时候结束。刚开始跑demo确实惊艳模型能自己规划路径看起来像那么回事。但一上真实场景就露馅了——同样的输入今天跑和明天跑结果不一样稍微复杂一点的任务模型会在某个环节开始“自由发挥”调用不存在的工具或者把参数格式搞错最要命的是你没法跟产品经理解释为什么这次走了A路径而不是B路径因为决策过程完全是个黑盒。Embabel这个框架的核心思路就是把这部分决策权从LLM手里收回来交给确定性的代码逻辑去控制。LLM只负责它擅长的事情——理解语义、生成内容、做模糊判断而流程走向、工具选择、状态流转这些需要稳定可复现的环节由开发者用显式的规则来定义。这个思路其实不新鲜工作流引擎、状态机、规则引擎都是干这个的但Embabel把这件事和Agent场景结合得比较自然用起来不别扭。这篇文章适合谁看如果你正在做Agent相关的应用被LLM的不确定性折磨过或者你正准备从“纯Prompt驱动”转向“混合编排”的方案那这篇笔记里的经验应该能帮你少走一些弯路。我会从整体设计思路讲到具体实现细节包括我踩过的坑和最后跑通的方案尽量把每个决策背后的原因说清楚。2. 核心设计思路拆解2.1 决策权分离的基本模型Embabel的设计哲学可以用一句话概括LLM做它该做的事代码做它必须做的事。具体来说它把Agent的执行过程拆成了三层规划层由开发者定义任务的可能路径和状态转移条件这部分是确定性的不依赖LLM执行层每个具体步骤的实际操作可能是调用LLM生成内容也可能是调用外部API、查数据库、做计算决策层在关键分叉点决定走哪条路。Embabel允许你在这里选择用规则判断还是用LLM判断但默认推荐规则优先这个分层的关键在于决策层和执行层是解耦的。LLM可以在执行层里自由发挥但它的输出会被约束在决策层定义的框架内。举个例子一个客服Agent需要判断用户意图是“查订单”还是“退换货”传统做法是让LLM直接输出意图标签然后路由。Embabel的做法是先让LLM输出结构化的意图描述然后用规则引擎去匹配这个描述匹配不上的再走LLM兜底判断。这样大部分常见情况都是确定性的只有边缘case才依赖模型。2.2 为什么不用纯Prompt方案我试过纯Prompt的方案就是在一个大System Prompt里把所有工具定义、决策规则、输出格式都写进去让模型自己按规则走。这个方案在简单场景下能跑但有几个绕不过去的问题上下文长度限制。当工具数量超过20个决策规则超过50条的时候Prompt会变得非常长模型对中间部分的注意力会下降经常忽略一些关键约束。Embabel把规则从Prompt里抽出来用代码管理Prompt只保留当前步骤需要的信息上下文压力小很多。调试困难。纯Prompt方案出问题时你只能看到输入和输出中间决策过程是黑盒。Embabel的每一步决策都有日志记录哪个规则匹配了、哪个条件没满足、LLM在哪个环节被调用了都能追溯。版本管理混乱。Prompt的修改没有类型检查改了一个词可能影响完全不相干的场景。Embabel的规则用代码写有类型系统兜底改错了编译期就能发现。2.3 状态管理的设计考量Embabel的状态管理是我觉得设计得比较巧妙的地方。它没有用传统的全局状态机而是采用了分层状态局部上下文的模式。每个执行步骤有自己的局部状态步骤之间通过明确定义的接口传递数据。这样做的好处是单个步骤的状态变化不会影响其他步骤降低了耦合每个步骤可以独立测试不需要构造完整的全局状态状态传递是显式的不会出现“某个隐藏状态被意外修改”的情况我实际用下来这个设计在任务步骤超过10个的时候优势特别明显。传统全局状态机到后面会变成一团乱麻谁改了哪个字段根本查不出来。Embabel这种局部状态的方式每个步骤的输入输出都很清晰排查问题的时候直接看对应步骤的日志就行。3. 核心细节解析与实操要点3.1 规则定义的关键参数Embabel的规则定义有几个核心参数需要特别注意我一个个说优先级priority当多条规则同时匹配时优先级高的先执行。这个参数看起来简单但实际用的时候很容易踩坑。我的经验是兜底规则的优先级要设成最低比如用LLM做模糊判断的那条规则优先级设成0或者负数确保所有确定性规则都匹配失败后才走它。匹配条件conditionEmbabel支持多种条件类型包括字段相等、范围判断、正则匹配、自定义函数等。这里有个细节条件判断的顺序会影响性能。把计算成本低的条件放前面比如字段相等判断把需要调用外部服务的条件放后面。我有个项目里把数据库查询条件放在了第一位结果每次规则匹配都要查一次库后来调整顺序后性能提升了将近三倍。执行动作action规则匹配后执行的操作。Embabel允许action返回一个状态码用来指示下一步走向。这里要注意的是action应该是幂等的因为框架在某些异常情况下可能会重试。如果你的action有副作用比如发邮件、扣款一定要做好去重处理。3.2 LLM调用的边界控制虽然Embabel把决策权收回来了但LLM调用仍然是核心环节。怎么控制LLM的调用边界我总结了几个要点输入约束给LLM的输入要尽可能结构化。Embabel提供了模板机制你可以定义输入模板只把当前步骤需要的字段传给LLM。我见过有人把整个上下文都塞给LLM结果模型被无关信息干扰输出质量很差。输出约束LLM的输出必须符合预定义的结构。Embabel支持JSON Schema校验如果模型输出不符合schema会自动重试或者走降级逻辑。这个机制非常关键没有输出校验的LLM调用就是在裸奔。超时和重试LLM调用可能超时Embabel允许你配置超时时间和重试策略。我的建议是超时时间设成正常响应时间的2-3倍重试次数不超过2次超过就降级到规则兜底。3.3 状态传递的实操细节状态传递这块我踩过不少坑说几个关键点数据类型要明确。Embabel是强类型的状态字段的类型必须明确定义。我一开始图省事用了泛型Map结果运行时各种类型转换错误。后来改成显式的数据类编译期就能发现大部分问题。状态字段要精简。不要把所有中间结果都塞进状态里只保留下一步需要的数据。状态字段太多会导致序列化开销大而且容易混淆。状态版本要管理。当你的流程需要修改时旧版本的状态数据可能和新代码不兼容。Embabel支持状态版本号建议在项目初期就加上这个机制后面改流程的时候会省很多事。4. 实操过程与核心环节实现4.1 环境准备与基础配置先说一下我的环境Python 3.10Embabel用的是当时最新的稳定版。安装过程没什么特别的pip装完就行。但配置环节有几个地方需要注意# 基础配置示例 from embabel import Agent, Rule, State # 定义状态结构 class OrderState(State): user_id: str order_id: str None intent: str None confidence: float 0.0 retry_count: int 0 # 初始化Agent agent Agent( nameorder_assistant, state_classOrderState, max_steps20, # 最大执行步数防止死循环 timeout30.0 # 全局超时单位秒 )max_steps这个参数很重要我建议一定要设。没有这个限制的话如果规则设计有环Agent会一直跑下去。我设成20是基于经验大部分任务在10步内能完成20步还没完成的基本就是出问题了。4.2 规则链的编写与调试规则链是Embabel的核心我拿一个实际场景来演示。假设我们要处理用户的订单相关请求流程是这样的# 规则1意图识别 agent.rule(priority100) def identify_intent(state: OrderState): 用LLM识别用户意图 prompt f分析以下用户输入判断意图类别{state.user_input} result llm.invoke(prompt, output_schema{ intent: str, confidence: float }) state.intent result[intent] state.confidence result[confidence] return intent_identified # 规则2高置信度直接路由 agent.rule(priority90, conditionstate.confidence 0.8) def route_by_intent(state: OrderState): 置信度高时直接按意图路由 routes { query_order: handle_query, return_order: handle_return, cancel_order: handle_cancel } return routes.get(state.intent, handle_unknown) # 规则3低置信度走澄清流程 agent.rule(priority80, conditionstate.confidence 0.8) def ask_clarification(state: OrderState): 置信度低时向用户澄清 state.clarification_needed True return wait_for_clarification调试的时候Embabel提供了trace功能可以看到每一步匹配了哪条规则、状态怎么变化的。我一般会在开发环境把trace级别调到DEBUG生产环境调到WARN。4.3 参数计算与选择过程在规则条件里经常需要做一些计算比如根据用户等级决定处理优先级。这里有个细节计算逻辑要尽量简单复杂的计算应该抽成独立的函数在规则里只做结果判断。def calculate_priority(user_level: str, order_amount: float) - int: 计算处理优先级 base {vip: 100, normal: 50, new: 10}.get(user_level, 10) if order_amount 1000: base 20 elif order_amount 500: base 10 return base agent.rule(priority70) def set_priority(state: OrderState): state.priority calculate_priority(state.user_level, state.order_amount) return priority_set这个计算函数我单独写了单元测试确保各种边界情况都覆盖到。规则里只调用函数拿结果不写复杂逻辑这样规则本身很清晰计算逻辑也能独立验证。4.4 完整流程串联把上面的规则串起来一个完整的订单处理流程大概是这样的用户输入进来初始化状态规则1执行LLM识别意图写入状态规则2或规则3根据置信度分流高置信度走具体处理规则低置信度走澄清流程处理完成后规则链结束返回结果整个流程中LLM只在第2步被调用了一次其他步骤都是确定性的规则判断。这就是Embabel的核心价值——把LLM的使用限制在真正需要它的环节。5. 常见问题与排查技巧实录5.1 规则不匹配怎么办这是最常见的问题。Agent跑完发现没有规则匹配直接结束了。排查思路先看trace日志确认当前状态是什么检查规则的condition是否覆盖了当前状态特别注意类型问题比如状态里是字符串100规则里写的是数字100这种不匹配很隐蔽我一般会加一条兜底规则优先级设成-1condition永远为Trueaction里记录一条警告日志。这样至少能知道哪些状态没被覆盖。5.2 LLM输出格式错误LLM输出不符合schema是高频问题。Embabel有自动重试机制但重试也可能失败。我的处理策略是错误类型处理方式重试次数JSON解析失败重新调用附加格式说明2字段缺失重新调用强调必填字段1类型错误尝试类型转换失败则重试1值超出范围截断到合法范围0超过重试次数后走降级逻辑用默认值或者跳过该步骤。5.3 状态传递丢失有时候发现某个字段在后续步骤里是None但明明前面步骤赋值了。原因通常是状态类定义时字段名拼写错误步骤之间用了不同的状态实例序列化/反序列化过程中字段丢失我的经验是每个步骤开始和结束时都打印一次关键状态字段这样能快速定位是哪一步丢的。5.4 性能问题排查规则链长了之后性能会下降。我遇到过规则匹配耗时超过500ms的情况排查后发现是某个condition里做了数据库查询。解决办法是把查询结果缓存到状态里condition只做内存判断。另一个性能问题是LLM调用太频繁。Embabel允许在规则里调用LLM但不要每个规则都调。我的原则是一个流程里LLM调用不超过3次超过的话就要考虑是不是设计有问题。6. 一些个人体会Embabel这套方案我用下来最大的感受是确定性带来的安心感。以前用纯Prompt方案每次上线新版本都提心吊胆不知道模型会出什么幺蛾子。现在核心流程是代码控制的LLM只在有限范围内发挥作用出问题的概率小了很多即使出了问题也能快速定位。当然也不是没有代价。规则链写起来比Prompt麻烦需要提前想清楚所有分支和状态。但我觉得这个投入是值得的尤其是当你的Agent要处理真实业务的时候稳定性和可解释性比开发速度重要得多。还有一个体会是不要试图用规则覆盖所有情况。我一开始想把所有可能的用户输入都枚举出来写了几百条规则结果维护成本极高。后来改成“规则处理常见情况LLM兜底边缘情况”的模式规则数量控制在50条以内效果好很多。最后分享一个小技巧Embabel的规则可以用装饰器组合把一些通用的条件判断抽成可复用的装饰器。比如require_auth、rate_limit这些写一次到处用规则本身会简洁很多。这个模式我是从Web框架的中间件设计里借鉴过来的在Embabel里同样适用。