★ FEATURED ARTICLE AI Agent开发教程写到这里我先把丑话说在前面前面几篇把单个Agent的组件、Prompt技巧、工具调用讲完之后不少读者反馈“跑通一个Demo很容易一接真实任务就散架”。这一篇“Agent框架下”重点就要解决这个“散架”问题。我会把编排模式、记忆管理、状态控制、多代理协作、可观测性这些框架层的机制掰开揉碎讲清楚。适合谁看已经能用API调通一个简单Agent、但想让它在生产环境稳定处理多步骤任务的开发者。看完你应该能回答三个问题Agent框架到底管什么、选型时重点看哪些维度、自己动手搭的时候最容易在哪里翻车。1. 为什么单个Agent撑不起真实任务1.1 从Demo到“能用”之间隔着的是执行结构现在网上大量教程教你的是同一个套路写一段System Prompt把工具列表塞进去然后循环调用模型。这套流程在“查天气”“写个摘要”“翻译一段话”这类单轮任务上确实够用可一旦任务变成“整理一个月的客户反馈按部门派发工单再生成周报”问题就全冒出来了。我列几个实际踩过的表现System Prompt越写越长模型开始记不清前面工具返回过什么工具调用失败一次之后模型不会主动恢复而是在原地打转或者自己编一个结果多步骤任务没有断点概念跑到第三步崩了整个任务作废还得从头来一遍。这些问题有一个共同点它们都不是模型能力问题而是“执行过程”本身的问题。Prompt写得再好也只能优化一次调用内的表现跨步骤的协调、恢复、记录必须要有一个执行层来承担。这也是为什么“Agent框架”这个概念的含金量比“Agent库”高。框架改变的不是给你多几个工具函数而是把“模型自由发挥”变成“结构化的可见过程”。你可以理解为一条流水线每个环节有明确的输入、输出、验收标准哪一环出了问题你能立刻说清是“哪一步”“为什么”“怎么恢复”。1.2 Agent框架到底在管哪三件事我在实际项目里对团队讲框架的价值从来不讲“封装得好不好”而是讲它必须管住三类问题。第一类是执行流程。任务怎么拆、步骤怎么排、失败怎么重试、超时怎么处理。没有这一层Agent的逻辑全藏在模型的输出里是不可验证的。第二类是上下文与状态。每一轮对话、每一次工具返回哪些信息要保留、放在哪里、何时清理、服务重启之后怎么恢复。这一层管不好Agent就是“金鱼记忆”多轮一点就翻车。第三类是可观测与可控。每次调用花了多少token、调用了哪个工具、为什么做了某个决策以及人类在哪个节点可以插手干预。这三件事在Demo阶段完全不需要因为它们都是“上了线才会被用户和运维追着打”的问题。我在好几个项目里都经历过Demo演示时全场鼓掌上线第二天群里就有人问“这个结果是怎么得出来的”“能不能让它别乱发消息”。框架存在的意义就是把这些问题在架构层面解决掉而不是靠人肉盯着每次输出。2. 核心执行模式与编排思路2.1 计划-执行模式把大任务拆成可验收的工序我在生产环境里最常用、也最推荐先掌握的一种结构是Planner-Executor模式。一句话解释负责“想”的和负责“做”的分开。Planner先把用户的需求拆解成一个个可执行的小任务Executor再逐个执行并把结果回填最后由Planner判断是否验收通过。这里我习惯用一个装修的类比。业主说“我要翻新这套房子”包工头不会让一个工人从头干到尾而是拆成水电、木工、油漆多道工序每道工序做完要验收不合格就返工。Planner-Executor模式就是那个包工头。为什么不直接让模型一次做完因为模型的一次性输出步骤越多每一步的完成质量越差。拆成多个独立小任务之后每一步单独走一遍调用上下文更聚焦出错也更易定位。比如“写一篇行业分析报告”这种任务拆成查资料、列提纲、写初稿、写摘要、做图表你在“做图表”这一步发现服务超时只需要重跑这一步不需要把前面全重来。但这个模式里有一个容易被忽略的坑Planner本身也是模型调用它拆出来的计划同样可能不合理。所以框架设计上计划不能只是一段文本最好是带编号、依赖关系、验收条件的结构化清单。Executor执行完一个子任务后把结果以结构化方式回填给PlannerPlanner判断“继续下一步”还是“调整计划”。这样的设计把一次性计划升级成了反馈闭环是整个编排稳定性提升的关键。2.2 增强的“感知-思考-行动”循环在框架层怎么落地上一篇文章里我详细讲过ReAct循环这里只讲它在框架层的落实方式。核心思想是模型每一次“思考”和“行动”都要被结构化记录而不是简单拼成一坨文本。很多初学的实现方式是把模型输出整体存到一个字符串里下一次当上下文全部塞回去。这个做法在对话少于5轮时勉强能用任务一长上下文里堆满历史噪声模型开始“忘事”。框架层面的做法是用一个运行记录对象来存储不同类别的信息推理记录、工具调用记录、工具结果。在送入模型之前再按需把这些记录组装成Prompt片段。工具结果这一项即使很长也可以单独做截断、摘要或者优先级降权。这样做最大的收益是可回溯。线上出问题的时候你打开运行日志能看到模型在哪个环节做了错误判断是下一步行动选错了工具还是工具返回的结果理解错了。有了结构化轨迹你甚至可以回放整个决策过程。我常说运行记录的价值比最终回复高得多因为它是Agent的“黑匣子”。2.3 多代理协作的两种常见路线与通信协议设计Multi-Agent是近来很热的概念但很多人一上来就踩坑。我把常见的协作形态归成两类。第一种是“主管-工人”模式。一个主管Agent接收需求、分析意图把子任务派发给专门的工人Agent。比如一个内容生产系统主管收到“做一期周报”的指令后分别派发给文案Agent、图表Agent、校对Agent。第二种是“流水线”模式多个Agent按固定顺序依次处理前一个的输出是后一个的输入。比如客户反馈系统分类Agent先过滤情感Agent再标记工单Agent最后组装。多代理真正难的不是给每个Agent写Prompt而是它们之间的通信协议。如果只是把上一层的输出文本拼进下一层的Prompt那就是假协作。信息格式稍一变链路就断。我的经验是Agent之间传递的消息要有固定字段至少包含来源、目标、类型、数据内容、请求标识。数据内容里的字段根据类型做校验。两个Agent之间再共享一个“任务上下文对象”谁都可以读但只有被授权的Agent能写特定字段。这里必须泼一盆冷水不是所有任务都需要多Agent。任务如果在二十行代码里能完成硬拆成多个Agent只会增加延迟和成本。多Agent是手段不是目的。我见过最典型的反面案例是一个明明单个Agent就能处理的表单填写任务被拆成了四个Agent互相传消息最后在调试消息格式上花了两周。正确顺序是先单Agent跑通再根据真实瓶颈决定是否拆协作。3. 选型与自建的关键维度3.1 选框架之前先把自己的需求分成三层很多人问我“应该用哪个Agent框架”我的回答通常是反问你的需求在第几层第一层需求只需要一个能跑的工具调用循环那不要上框架自己写一百行循环就够用。第二层需求需要计划、重试、记忆管理、人工审核这些流程控制能力这时候框架的价值才体现出来。第三层需求需要大规模并发、完整可观测性、状态持久化、对外提供接口这已经是平台化的诉求必须考虑框架的扩展能力。这几年我见过太多项目栽在同一件事上需求明明在第一层提前上了第三层的架构然后被配置复杂度拖死光调通框架本身的时间就超过了写业务逻辑的时间。所以我现在的建议是从最简单的方案开始让框架来证明自己值得被用而不是看了几篇宣传就全盘上重架构。3.2 确定性、可观测性与可移植性怎么权衡选型或者自建时我会围绕三个维度做评估这三个维度几乎决定了一个框架在真实环境里是否好用。第一个维度是确定性。同一个输入框架给出的执行轨迹是否稳定这是最容易被忽视的。工作流类系统里有一种做法对于一个请求系统先生成一个执行计划计划在运行过程中不随模型自由变动只有遇到明确异常才允许重新规划。这种思路牺牲了一点灵活性但换来了可复现、可测试。特别适合发布、支付、质检这类需要留痕和审计的任务。如果你做的Agent是“陪聊型”确定性要求可以低一点但这不意味着可以完全随机只是侧重点不同。第二个维度是可观测性。工具调用、步骤耗时、token成本能不能实时看到决策过程能不能回放。我不建议选任何“看不见内部状态”的框架因为线上问题你只能靠日志定位黑盒框架会让你抓瞎。第三个维度是可移植性。换模型、换工具需要改多少处代码。很多框架把模型和工具写死换一个模型服务商就要改一遍业务代码这在多模型切换的时代里非常痛苦。好的框架应该把模型做成可配置项业务代码不感知底层模型是谁。3.3 工具注册中心与状态管理是自建时最花时间的两个模块自己搭一套轻量Agent框架时时间主要花在工具注册中心和状态管理上这里我把它们单独拿出来说。工具注册中心解决的是“模型怎么知道有哪些工具、怎么调用”这件事。我给每个工具维护一个结构化描述包含工具名称、用途说明、参数JSON Schema、返回值规范、失败错误码。模型看到的不是Python函数而是这些结构化描述。运行时有一个校验层在模型给出调用参数后先做schema校验再真正执行。这一步能拦截掉绝大多数参数幻觉问题比如模型把日期格式传错、把必填字段漏掉。状态管理我更建议做成显式状态机。每个任务实例有明确状态等待规划、执行中、等待用户输入、审核中、已完成、失败。状态之间的转换必须有明确的触发条件。很多难题例如任务被重复执行、用户中断后无法恢复根源都是状态隐藏在上轮对话里是隐式的。改成显式状态机之后你会顺手获得两个重要能力超时回滚即某个步骤超时时回退到上一个稳定状态幂等重试即同一个步骤可以被安全地重跑多次不会产生重复副作用。4. 实操落地用框架做一个多平台内容发布助手4.1 需求拆解与模块设计讲完理论用一个实际例子把框架串起来。我设计的模拟项目是一个“多平台内容发布助手”。功能很简单用户丢一篇Markdown草稿进来助手把它改写成适配三个不同平台风格的版本生成配图建议最后在预览通过后执行发布。这个任务非常适合展示框架的编排能力因为它的链条足够长也带外部副作用动作。我把模块拆成五个部分入口Agent负责接收草稿和指令规划器负责拆解任务执行器负责调用各个内容工具审核闸门是一个人工确认节点状态存储器负责记录每个任务的进度。在动手写代码之前我先明确了一条设计原则一切带外部副作用的动作比如实际发布内容Agent默认都只能做“预演”把结果整理成预览等人类点击确认后才真正执行。这个原则要从架构上保证而不是靠提示词叮嘱。4.2 核心代码骨架这里给一份参考骨架我用Python写但核心思想不受语言限制。from dataclasses import dataclass, field from enum import Enum from typing import Any, Optional class TaskStatus(str, Enum): PLANNING planning EXECUTING executing WAITING_REVIEW waiting_review COMPLETED completed FAILED failed dataclass class PlanStep: step_id: str description: str tool: Optional[str] None deps: list field(default_factorylist) status: str pending result: Any None dataclass class TaskContext: task_id: str status: TaskStatus TaskStatus.PLANNING plan: list field(default_factorylist) current_step: int 0 memory: dict field(default_factorydict) trace: list field(default_factorylist) # 工具注册中心 class ToolRegistry: def __init__(self): self._tools {} def register(self, tool): self._tools[tool.name] tool def get_schemas(self): return [t.schema for t in self._tools.values()] def execute(self, name, params): tool self._tools.get(name) if not tool: raise ValueError(funknown tool: {name}) # 先跑参数校验再执行 validated tool.validate(params) return tool.run(validated)规划器的职责是生成PlanStep列表它调用一次模型但要求模型严格按JSON返回步骤数组并声明依赖关系。执行器则是一个循环逐一处理状态为pending且依赖已满足的步骤。while True: next_steps [s for s in ctx.plan if s.status pending and all(d.status completed for d in dep_map[s.step_id])] if not next_steps: break step next_steps[0] step.status executing try: step.result registry.execute(step.tool, step.params) step.status completed except Exception as e: step.status failed # 标准错误码用于反馈给Planner step.result {error_code: TOOL_FAILED, detail: str(e)} break这段代码暴露了框架的骨架执行不是一次大模型调用而是一个循环。每步结果都回写到TaskContext并且记入trace列表。审核闸门放在执行器之后此时任务进入WAITING_REVIEW状态等待人类的“确认发布”信号。4.3 关键节点与人工审核闸门的设计细节在发布助手里审核闸门不是简单地在界面上放一个“确认”按钮它背后有一套逻辑。当执行器完成所有预览步骤后系统把所有平台内容、配图建议、发布计划整理成一份结构化的审核单推送给用户。用户一旦确认才触发真正的发布工具。这条链路里发布工具的调用是一次独立的、编码在工具层的动作它只接受一个已确认的审核单ID作为参数。这样设计的好处是用户可以核对每一步而Agent的“回滚”也简单了——只要发布动作没触发就把状态从WAITING_REVIEW回退到EXECUTING重新修改后再次提交审核。这个机制是从架构上把“人机协作”变成现实而不只是同一个Prompt里写一句“请确认后再执行”。另外我在入口Agent和执行器里各设了一次成本预算检查。每次调用都会把累计token数写入状态存储器超过预算时下一步自动挂起等待用户决定是否继续。你可能会觉得这个设计多余但在真实生产环境里多个任务并发时token成本最容易失控预算检查算是Agent系统的熔断器。5. 常见问题与生产化避坑实录5.1 状态丢失与服务重启恢复很多团队上线Agent服务之后遇到的第一个事故就是服务重启后所有任务原地消失。典型场景是一个长任务跑了一半运维发版重启进程用户重新打开页面发现“助手失忆了”。排查方向其实很明确任务状态有没有持久化。如果Agent的状态只存在于进程内存里那重启必然丢。我建议每完成一个步骤就把TaskContext写入数据库写入的字段包括任务状态、计划清单、每一步的结果、当前步骤索引。这样下次启动时能从存储里恢复出完整的TaskContext继续执行而不是从头再来。这件事在Demo阶段看不出差异但在真实环境里属于基础设施级需求。5.2 上下文失控与记忆膨胀随着任务持续推进运行记录会越来越长。如果不加控制总有一天会把模型Context塞满。表现就是前面几轮的指令全都“看不见了”模型开始答非所问甚至复读工具结果。我的解法是给运行记录做分层记忆。短期记忆只保留最近两到三轮的完整交互工作记忆保持当前步骤的关键数据比如当前子任务的输入输出长期记忆把已经完成的步骤做摘要化存成压缩信息。模型真正看到的上下文是这三层记忆按策略组装的而不是直接把原始日志全量塞入。实践中这一步对任务稳定性提升最明显。5.3 工具失败、幻觉决策与成本失控这一节讲三个高频问题的处理思路。工具失败。模型调工具经常遇到服务超时、参数错误、数据不存在。如果工具返回的是混乱文本模型很容易误解。我的做法是给工具定义标准错误码运行时捕获所有异常统一转成结构化错误对象告诉模型“这次调用失败了错误码是什么是否允许重试”。把失败从自由文本变成机器可读信息之后模型的恢复策略一下子变得可预期了。幻觉决策。模型在拿不到可靠数据时偶尔会自己“编”一个工具结果继续跑。这是最危险的行为尤其是有外部副作用的场景。框架层面的防线是人工审核闸门加结果校验。涉及金额、发布、删除、通知这些操作一律要求先预览后执行工具结果如果不符合Schema宁可终止任务也不要让Agent脑补。成本失控。Planner每次执行都调用一次性能较高的模型token消耗经常是单轮调用的几倍。我的控制方式有三板斧控制Planner输出长度要求它只输出精简的计划清单控制工具结果长度超长文本先摘要再送进下一步分层模型配置规划、总结类任务用性能更好的模型工具结果整理用轻量模型。这三板斧组合下来成本通常能压掉一半以上。5.4 问题排查速查表症状可能原因排查思路建议处理方案服务重启后任务丢失状态只存在内存里检查是否有状态持久化逻辑每个步骤完成后同步写入数据库多轮后模型忽略指令上下文塞满历史记录查看实际送进模型的Prompt长度运行记录分层历史步骤做摘要工具调用反复失败模型传入参数不符合Schema打开工具调用轨迹看具体参数运行时加参数校验失败转结构化错误码结果幻觉编造工具返回值未做结果校验检查是否允许模型跳过工具结果强制Schema校验失败必须终止任务并发任务互相干扰多个任务共享了同一份上下文检查上下文隔离粒度每个任务独立TaskContext禁止共享变量成本异常飙升Planner调用频繁工具结果过长按步骤核对token消耗分层模型配置工具结果先摘要再传递我在实际使用中最深的体会是Agent框架做到最后复杂不是目的可控才是。前面讲的所有内容——状态机、工具注册、分层记忆、人工审核闸门、可观测性——单独拿出来都不算惊艳组合在一起你才真正拥有一个可以交给别人放心使用的Agent系统。如果只记住一件事那就是永远让Agent的每一步决策都留痕永远给关键操作留一道人工确认的闸门。
阅读完成 · 觉得有帮助？
