Embabel状态机：把Agent决策权从LLM拿回来

1. 从一次失控的Agent任务说起去年冬天我接手了一个内部知识库问答系统的改造项目。需求听起来很朴素让Agent根据用户提问自动决定是查文档、调接口还是直接回答。我一开始用的是纯LLM驱动的方案把工具列表塞进系统提示词让模型自己选。前两周跑得挺顺第三周开始出幺蛾子——同一个问题早上问它调接口下午问它直接编答案晚上问它又跑去查文档。更离谱的是有一次它连续调了七次同一个接口把下游服务打挂了。那次事故之后我花了整整两周时间翻各种Agent框架的源码最后锁定了Embabel这个项目。它的核心主张特别对我的胃口把Agent的决策权从LLM手里拿回来。LLM只负责它擅长的事——理解语义、生成文本而下一步该做什么这个决策交给确定性的状态机来管。这篇文章就是我这段时间的学习笔记和实操总结适合正在被Agent不确定性折磨的开发者也适合想理解可控Agent设计思路的技术人。2. 为什么纯LLM决策会失控2.1 LLM作为决策器的三个结构性缺陷很多人第一次搭Agent直觉就是把工具描述写进prompt让模型输出我要调用哪个工具。这个方案在demo阶段几乎不会出问题因为demo的输入是精心挑选的。但一旦上生产三个缺陷会同时暴露。第一个是概率性输出。LLM本质是下一个token的概率分布采样同样的输入温度参数不为零时输出就会漂移。你没法保证用户问天气永远映射到调用天气接口它可能今天映射到接口A明天映射到接口B。这不是模型能力问题是架构问题。第二个是上下文污染。当对话轮次变多历史消息里混入了工具返回结果、错误信息、用户纠正模型对当前该做什么的判断会被这些噪声干扰。我实测过一个场景前一轮工具调用失败返回了错误码下一轮模型居然模仿错误码的格式来回答用户。第三个是无法审计。纯LLM决策的Agent你没法回答为什么它这一步选了工具X而不是工具Y。日志里只有模型的输出文本没有决策依据。出了问题只能靠猜这在生产环境是致命的。2.2 决策权与生成权分离的核心思想Embabel的设计哲学可以用一句话概括决策是确定性的生成是概率性的两者必须分离。打个比方。LLM像一个知识渊博但有点随性的顾问你问他这份合同该走哪个审批流程他能给你分析得头头是道但你不会让他直接去点审批按钮。真正点按钮的是一套写死的流程引擎——什么条件下走一级审批什么条件下走二级规则是明确的、可审计的、可测试的。Embabel把Agent的执行拆成两层上层是状态机定义当前处于什么状态、满足什么条件时转移到什么状态下层是LLM调用只在状态机明确需要理解语义或生成内容时才被触发。决策权归状态机生成权归LLM各司其职。这个分离带来的直接好处是你可以对状态机写单元测试可以画出完整的状态转移图可以在日志里看到每一步的决策依据。Agent从黑盒变成了白盒。2.3 什么场景适合这种架构不是所有Agent都需要Embabel。如果你的任务只有一步——用户问模型答那直接用LLM就行套状态机是过度设计。但如果你符合以下任一特征就值得考虑任务需要多步执行且步骤之间有依赖执行过程中需要调用外部工具且工具调用有副作用业务上要求可审计、可回放、可测试或者你已经被纯LLM方案的不确定性坑过。我自己的判断标准很简单如果这个Agent挂了会导致下游服务异常或者出了问题需要向别人解释为什么它这么做那就该上状态机。3. Embabel的核心概念拆解3.1 State、Transition与Guard的三件套Embabel的模型非常精简核心就三个概念。State状态表示Agent当前所处的阶段。比如等待用户输入、已解析意图、工具调用中、生成最终回答。状态是离散的、有限的你可以把所有状态画在一张图上。Transition转移表示从一个状态到另一个状态的路径。每条转移有一个触发条件条件满足就执行转移。Guard守卫是转移的触发条件。Guard可以是一个布尔表达式也可以是一次LLM调用——但注意LLM调用的返回值会被强制转换成布尔值或枚举值而不是让LLM自由发挥。这三件套组合起来Agent的行为就完全确定了给定当前状态和输入Guard评估结果决定走哪条转移到达新状态后重复这个过程。整个过程可以画成一张状态转移图任何人看了都能理解Agent会怎么走。3.2 Guard如何约束LLM的输出空间这是Embabel最巧妙的地方。很多人担心把决策权拿回来会让Agent变笨因为LLM的灵活性没了。但实际上Guard里的LLM调用不是被削弱了而是被约束了。举个例子。纯LLM方案里你让模型输出下一步动作它的输出空间是整个词表可能输出任何东西。而在Embabel里Guard里的LLM调用被要求输出一个枚举值比如INTENT_QUERY_DOC、INTENT_CALL_API、INTENT_DIRECT_ANSWER三选一。输出空间从无限压缩到三选一模型的准确率会大幅提升。我实测过同一个意图分类任务自由生成格式的准确率大概70%约束成枚举后能到95%以上。这不是模型变强了是任务变简单了。更重要的是Guard的返回值可以被校验。如果LLM输出了一个不在枚举里的值状态机可以直接拒绝走fallback分支而不是让一个非法值继续往下传。3.3 与主流Agent框架的定位差异市面上主流的Agent框架大多走的是LLM规划工具执行的路线。LLM负责生成一个计划plan然后按计划执行。Embabel不一样它不生成计划它预定义计划。这个差异决定了适用场景。如果你的任务步骤是固定的、可枚举的Embabel更合适因为它的行为完全可预测。如果你的任务步骤是开放的、需要模型临场发挥的那纯LLM规划可能更合适。但我的经验是生产环境里90%的Agent任务步骤都是可枚举的。真正需要模型临场发挥的场景往往是因为需求没想清楚而不是任务本身开放。4. 手把手搭建第一个Embabel Agent4.1 环境准备与依赖安装我用的环境是Python 3.11Embabel对3.10以上都支持。依赖安装很干净没有一堆传递依赖。pip install embabel-core如果你要用它内置的LLM适配器再装对应的包。我用的是OpenAI兼容接口装的是pip install embabel-openai装完之后先跑一个最小示例验证环境。Embabel自带了一个echo agent的示例跑通它说明环境没问题。注意Embabel的版本迭代比较快我写这篇文章时用的是0.4.x。如果你装的是0.3.x部分API可能有差异建议先看对应版本的文档。4.2 定义状态与转移的完整代码下面是我写的一个最小可用的Agent功能是接收用户问题判断是查文档还是直接回答查文档的话调用一个模拟的检索函数最后生成回答。先定义状态枚举from enum import Enum class State(Enum): START start CLASSIFYING classifying RETRIEVING retrieving GENERATING generating DONE done然后定义Agent类注册状态和转移from embabel import Agent, transition, guard class QAAgent(Agent): initial_state State.START transition(from_stateState.START, to_stateState.CLASSIFYING) def start_classify(self, ctx): return True transition(from_stateState.CLASSIFYING, to_stateState.RETRIEVING) guard(lambda ctx: ctx.intent QUERY_DOC) def go_retrieve(self, ctx): ctx.doc retrieve_docs(ctx.question) return True transition(from_stateState.CLASSIFYING, to_stateState.GENERATING) guard(lambda ctx: ctx.intent DIRECT_ANSWER) def go_generate(self, ctx): return True transition(from_stateState.RETRIEVING, to_stateState.GENERATING) def after_retrieve(self, ctx): return True transition(from_stateState.GENERATING, to_stateState.DONE) def finish(self, ctx): ctx.answer generate_answer(ctx) return True这段代码里ctx是上下文对象贯穿整个执行过程。intent字段是在CLASSIFYING状态里通过LLM调用填充的但填充之后走哪条转移完全由Guard的布尔表达式决定LLM不再参与。4.3 在Guard中调用LLM的正确姿势CLASSIFYING状态需要调用LLM来判断意图。这里的关键是LLM的输出必须被约束成枚举。INTENT_PROMPT 判断用户问题的意图只输出以下三个词之一 QUERY_DOC - 需要查文档 DIRECT_ANSWER - 可以直接回答 UNCLEAR - 无法判断 用户问题{question} def classify_intent(ctx): raw llm.complete(INTENT_PROMPT.format(questionctx.question)) raw raw.strip().upper() if raw not in (QUERY_DOC, DIRECT_ANSWER, UNCLEAR): return UNCLEAR return raw注意最后那个校验如果LLM输出了枚举外的值直接归到UNCLEAR走fallback分支。这个校验看起来简单但它堵住了LLM不确定性的最后一道口子。实操心得prompt里一定要明确只输出以下三个词之一并且给出每个词的含义。我试过只写判断意图模型会输出一整段解释解析起来很麻烦。4.4 运行与调试的实操记录跑起来之后Embabel会输出完整的状态转移日志。这是我实测的一段[START] - [CLASSIFYING] intentQUERY_DOC [CLASSIFYING] - [RETRIEVING] guard passed [RETRIEVING] doc retrieved, length1204 [RETRIEVING] - [GENERATING] [GENERATING] answer generated, length356 [GENERATING] - [DONE]这个日志的价值在于任何一步出问题你都能精确定位到是哪个状态、哪条转移、哪个Guard。纯LLM方案里你只能看到模型的输入输出中间过程是黑盒。调试的时候我习惯在Guard里加一行日志记录Guard的评估结果。这样当Agent走了非预期分支时能立刻看出是Guard判断错了还是LLM分类错了。5. 把决策权拿回来之后的收益与代价5.1 可测试性带来的开发效率提升这是最直接的收益。状态机是可以写单元测试的。我可以构造一个上下文把intent设成QUERY_DOC断言Agent会走RETRIEVING分支。这种测试跑起来是毫秒级的不需要调用LLM。我现在的做法是状态转移逻辑用单元测试覆盖LLM调用部分用mock替换。这样CI里跑几百个测试用例也就几秒钟。纯LLM方案做不到这一点因为每次测试都要真实调用模型成本高、速度慢、结果还不稳定。5.2 可观测性每一步决策都有据可查生产环境出问题时Embabel的日志能直接告诉你Agent在CLASSIFYING状态把意图判成了DIRECT_ANSWER所以没走检索分支。你可以拿着这条日志去分析是prompt写得不好还是用户问题本身有歧义。我遇到过一个问题用户问这个功能怎么用Agent直接回答了没查文档。看日志发现意图被判成了DIRECT_ANSWER。分析prompt后发现怎么用这个表述在训练数据里经常对应通用知识问答模型倾向于直接回答。后来我在prompt里加了一条规则涉及本系统具体功能的问题一律判为QUERY_DOC问题就解决了。这种问题在纯LLM方案里也能修但你不知道要修哪里只能反复试prompt。Embabel让你知道问题出在哪个环节。5.3 灵活性下降的应对策略代价也很明显状态机是写死的遇到没预定义的情况就抓瞎。我的应对策略是保留一个兜底状态。所有Guard都不满足时走FALLBACK状态在这个状态里调用LLM做自由决策。这样既保证了主流程的确定性又保留了处理边缘情况的灵活性。另一个策略是状态机分层。主状态机管大流程子状态机管细节。比如RETRIEVING状态内部可以再套一个小子状态机处理检索失败重试、多路检索合并这些细节。这样主状态机保持简洁细节逻辑封装在子状态机里。6. 踩过的坑与排查实录6.1 Guard循环依赖导致的死锁我遇到过一次Agent卡死。日志停在某个状态不动了。排查后发现是两条转移的Guard互相依赖A转移的Guard需要B转移执行后设置的字段B转移的Guard又需要A转移执行后设置的字段。结果两条都不满足Agent就卡住了。排查方法Embabel有超时机制卡住超过阈值会抛异常。看到超时异常后检查当前状态的所有出边Guard看是否有循环依赖。修复方法把互相依赖的字段拆开或者引入一个中间状态打破循环。我现在设计状态机时会刻意避免Guard依赖未来才会设置的字段。6.2 LLM输出格式漂移的兜底方案即使prompt里写了只输出枚举值模型偶尔还是会输出带解释的文本比如QUERY_DOC因为用户问的是具体功能。我的兜底方案是正则提取import re def extract_enum(raw, valid_values): for v in valid_values: if re.search(r\b v r\b, raw.upper()): return v return UNCLEAR先尝试精确匹配失败再用正则提取再失败归到UNCLEAR。三层兜底下来实测漂移率降到千分之一以下。6.3 状态爆炸的预防经验状态机设计最容易犯的错是状态爆炸。每加一个条件就加一个状态最后状态图变成一团乱麻。我的经验是状态数量控制在7个以内。超过7个人脑就很难在脑子里维护这张图了。如果确实需要更多状态考虑拆成多个子状态机。另一个经验是状态命名用动词ing形式比如CLASSIFYING、RETRIEVING、GENERATING。这样一眼就能看出这个状态在做什么比用名词命名清晰得多。6.4 常见问题速查表问题现象可能原因排查方向解决方案Agent卡死不动Guard循环依赖检查当前状态出边Guard打破循环或加中间状态走了非预期分支Guard判断错误看Guard评估日志修正Guard表达式或LLM promptLLM输出无法解析格式漂移看原始输出加正则提取兜底状态图过于复杂状态爆炸数状态数量拆分子状态机测试跑得慢真实调用LLM看测试是否mock用mock替换LLM调用7. 从单Agent到多Agent协作的扩展思路单个Agent跑通之后自然会想扩展到多Agent。Embabel的多Agent协作模型很直接每个Agent是一个独立的状态机Agent之间通过消息传递通信。我做过一个实验一个路由Agent负责判断问题类型然后分发给文档Agent或数据Agent。路由Agent的状态机很简单只有CLASSIFY和DISPATCH两个状态。文档Agent和数据Agent各自有完整的状态机。这种架构的好处是职责清晰。每个Agent的状态机都很小容易维护。坏处是调试变复杂一个问题可能跨越多个Agent日志要串起来看。我的建议是先从单Agent做起把单Agent的状态机跑稳再考虑拆分。很多场景其实单Agent就够了拆多Agent反而增加复杂度。8. 我个人的一些使用体会Embabel不是银弹。它解决的是决策不确定性这一个问题不解决LLM本身能力不足的问题。如果你的任务需要模型做复杂推理Embabel帮不上忙该调模型还是得调。但如果你被Agent的不确定性折磨过Embabel值得一试。它最大的价值不是技术多先进而是把Agent的设计从调prompt变成了画状态图。这个思维转变比任何框架都重要。我现在设计Agent的流程是先在纸上画状态图标出每个状态的进入条件、退出条件、Guard表达式。图画清楚了代码就是翻译。图画不清楚说明需求还没想明白这时候写代码就是浪费。最后分享一个小技巧Embabel的状态转移日志可以导出成图。我习惯在每次状态机改动后导出图看一眼确认没有意外的转移路径。这个习惯帮我提前发现过好几次设计缺陷。