做了三四个Agent项目之后你应该也会有这种感觉每次新项目上手前面一两周都花在搭基础结构上后面又要花一堆时间跟模型的“不稳定发挥”搏斗。换个新模型之前调好的Prompt全部崩盘加一个新工具总在某个循环里跑偏。越做越累累的不是写代码本身而是每个项目都在重复造一个粗糙的轮子然后被这个轮子扎一次脚。问题真不是模型不够强而是你没有一套可复用的产品骨架。我说的“产品骨架”不是LangChain或者某个现成的Agent框架而是你自己项目里那一层恒定的运行时架构——它把“理解意图、规划步骤、调用工具、处理结果、生成回复”这件事固定下来让不同业务的差异全部收敛在配置和工具注册里。有了这个骨架新项目就不再是一堆手写逻辑的堆积而是一次“插拔式”的组装。这篇文章我会把这套骨架的核心抽象、模块设计、落地代码和踩坑排查经验全盘整理出来给正在被Agent项目折磨的开发者一个可以参照的答案。1. 为什么AI Agent项目越做越累——先搞清楚累在哪1.1 三层疲劳模型层、代码层、业务层先说最直接的感受。很多团队在Agent项目推进过程中疲劳感是分三个层面叠加上来的模型层的疲劳是总觉得当前模型“不够聪明”。多轮对话记不住关键信息工具调用偶尔抽风格式输出不稳定。于是下意识想换一个大参数模型或者更强的新版本。但换模型不是改一行配置你之前精心设计的Prompt、Few-shot示例、工具描述在另一个模型上可能完全失灵。每一个模型都像一位脾气不同的新同事你得重新跟它磨合一遍。代码层的疲劳是业务逻辑和模型交互搅在一起。我一个做数据分析Agent的项目里面既有直接处理DataFrame的代码又有调用模型解析用户意图的Prompt还有偷偷拼接的工具返回结果。这些代码高度耦合改一个需求牵动一大片。更糟的是这些代码几乎不可复用换个业务场景就像一堆废铁。业务层的疲劳是需求方永远不会按你预想的剧本提需求。今天做个客服问答明天做个工单分类后天又来个报告自动生成。表面看每个都是新领域、新逻辑但往细了想底层都要拆解用户请求、决定要不要调用工具、判断什么时候该结束回答。如果每次都用“硬编码条件裸Prompt一次性函数”去实现等于同一个坑反复掉进去。1.2 误区别把“更强模型”当万能药我有一段印象特别深的经历项目里有个多工具协作的Agent总是调用错工具有时还把参数拼错。当时我的第一反应是“这模型能力不行得换更聪明的”。结果换了个规模更大的模型问题确实少了但新的Bug冒出来了——它开始自己脑补工具返回值编造一些根本不存在的字段。后来又花了三天调Prompt和约束才勉强压住。这件事让我意识到模型是概率生成器它的能力再强也只是输出一堆token。真正决定Agent是否稳定可控的是围绕它构建的那套流程你怎么喂上下文、怎么约束输出格式、怎么解析调用意图、怎么处理异常结果、怎么终止循环。这就像一辆车模型是发动机而骨架是底盘、变速箱、悬架。发动机换得再好底盘松散跑起来照样散架。反过来说很多“效果不行”并不是模型不行而是你的产品结构太脆弱。没有把不确定性关进笼子里模型的一个随机波动就能让整个流程崩溃。可复用的产品骨架本质就是那个笼子它把Agent的行为约束在业务可接受的范围内并且让这套约束能平滑迁移到下一个项目里。2. 可复用产品骨架的整体设计——站在产品层思考2.1 骨架的核心抽象Agent循环无论你做什么领域的Agent它的核心循环几乎不会变可以用一句话概括接收请求 → 理解意图 → 规划步骤 → 调用工具 → 获取结果 → 生成回复 → 如有必要继续循环。这个循环就是Agent产品的最小稳定内核。不管是售前客服、代码生成、报表分析还是智能创作都跑在这一条链路上。差别只在于你给Agent准备了哪些工具系统Prompt里写了什么规则上下文记忆里放了多少历史信息。换句话说业务流程会变但循环不会变。所以一个可复用的产品骨架本质上就是把这个循环封装成一个运行时的“壳”。在这个壳上预留四个扩展点意图识别器负责把用户输入解析成结构化任务判断是需要调用工具还是直接回答。规划器决定下一步执行动作是提出澄清问题、调用某个工具还是输出最终答案。工具集注册给Agent使用的具体能力每个工具都有名称、描述、参数Schema和执行函数。记忆存储保存会话内外的状态让Agent能记住关键信息和历史步骤。设计原则很简单凡是跨项目不变的东西下沉到运行时里凡是跟具体业务相关的东西全部外置成配置。这样你做的每一个新Agent都只是给同一个运行时换上不同的“皮肤”和“器官”。2.2 配置驱动新项目 一份配置 若干工具一开始做Agent项目时我会把系统Prompt、工具列表、循环次数、模型名字全部写死在代码里。后来发现每一次业务调整都要动代码风险高又麻烦。后来我把这个思路整个推翻改成“配置驱动”。所谓配置驱动就是用一个结构化的配置文件我常用YAML或JSON描述一个Agent项目的全部元信息。举几个关键的配置项系统提示词的基础角色和规则任务特定指令片段工具清单及其描述和参数Schema最大循环次数和超时时间默认模型及温度等生成参数。这样一个新项目的落地过程就变成写一份新的配置文件再补充几个业务工具函数剩下的运行时逻辑完全复用。你不需要重新设计多轮对话的管理方式也不需要处理工具调用结果的解析细节这些已经被骨架消化掉了。当然配置驱动不是让你把所有东西都做成配置文件那样反而会变得笨重。我的经验是只把“在不同项目之间会变化”的部分做成配置稳定的部分留在代码里。比如工具的执行函数本身当然是代码但工具的描述、参数Schema、是否启用可以放进配置。掌握了这个平衡配置驱动才会有真正的灵活性。2.3 边界划分业务逻辑与模型能力解耦可复用骨架最大的价值是它制造了一道清晰的边界。一边是业务相关的Prompt、工具、校验规则另一边是模型调用、循环控制、状态管理。两者解耦之后有两个非常直接的好处。第一当你在一个项目中积累了某个领域的Prompt写法或者某个工具调用的最佳实践这些东西是可以被复用的。比如一套优化的“时间解析工具描述”在日程管理Agent和订单查询Agent里都能用。因为你已经把它模块化了而不是散落在某段自由代码里。第二当你对运行时本身做了改进比如优化了工具结果截断策略或者新增了超时重试机制所有基于这个骨架的项目会同时受益。我做了一个“工具结果摘要模块”之后只花了一个晚上接入骨架所有的Agent项目上下文长度问题都缓解了。这种杠杆效应是骨架化之前完全无法想象的。3. 核心模块拆解与实操要点3.1 Prompt模板管理把提示词当成一等公民很多刚开始做Agent的朋友习惯把Prompt直接写在代码字符串里写完就忘。等过两天要改的时候在代码里翻半天还容易误改别的逻辑。我的建议是把Prompt当作真正的代码资产来管理。具体做法是使用模板语言Jinja2是最常见的选择组织Prompt。一个Agent的Prompt不要只有一个大字符串而是拆成几个组成部分基础系统提示词定义角色和通用规则跨项目复用。任务特定指令当前领域的具体要求比如数据分析项目要规定“只能使用注册工具中的search_orders”。示例对话3到5组高质量的Few-shot教模型理解工具调用场景。输出格式约束定义最终的输出结构尤其是需要结构化结果时。拼接顺序和内容需要针对不同模型做微调。每个模板保存成一个独立的文本文件或配置项配上版本号。只要你改了某个Prompt就一定要跑一遍回归用例集。我给每个Prompt建了一个简单的回归文件夹里面放十来个典型的输入输出对改动后自动跑一遍能省下大量人工测试时间。这里有一个实操中容易踩的坑生成参数temperature。用来做工具调用和结构化输出时我会把temperature调到0.1到0.3之间否则格式很容易漂移。用来做创意内容生成时才调到0.7以上。很多人一套参数走天下结果Agent行为忽好忽坏还以为模型抽风了。3.2 工具注册与调用让Agent学会“用正确的工具”工具调用是Agent骨架里最核心、也最容易出问题的模块。很多Agent项目走样都是工具调用环节出了问题该调的工具没调不该调的工具乱调参数传错返回值过大撑爆上下文。要解决这些问题工具注册信息比工具函数本身更重要。每个工具都要提供三样东西名称简短且语义清晰比如“查询用户订单信息”就不要叫“func_2”。描述说明该工具在什么情况下使用什么情况下不要使用。比如“当用户问自己买了什么时使用当用户问库存信息时不要使用”。这个描述是模型做工具选择的依据直接影响命中率。参数Schema用JSON Schema描述每个参数的名称、类型、必填性、取值范围和说明。Schema越严格模型越容易生成合法的调用。我在工具执行层做了几个封装超时控制、重试机制、统一返回结构。工具执行后一定不要返回一段自由文本而要带一个状态码和结构化结果。比如查询成功返回success查询不到数据返回empty接口异常返回error。Agent拿到这个结构化结果后才能做出正确的下一步判断。如果直接抛一个Python异常给模型模型根本不知道发生了什么只能瞎猜。另外工具结果要限制大小。一些查询工具一次能返回几百条记录直接塞进上下文token消耗巨大还会稀释重点。我的做法是让每个工具返回最多20条核心记录并在描述中说明“如需更多结果可分段查询”。这样既控制了上下文长度又给了Agent继续调用工具的线索。3.3 记忆与状态管理不要让Agent“失忆”Agent跟单轮问答最大的不同就是它需要一股“连贯的劲”。但在实际实现里记忆管理往往被简化成“把历史消息全部塞进去”。这样做短时间内没问题但随着对话变长token爆炸、关键信息被淹没、模型开始出现幻觉。骨架里需要明确区分两种记忆。短期记忆指当前会话内最近几轮对话。我会用一种“滑动窗口摘要”的方式维护保留最近三到五轮的完整对话更早的内容让模型生成一段摘要存下来。这个过程本身也可以异步化不让用户等。实际操作时我在状态对象里存了三个字段recent_messages最近消息、conversation_summary历史摘要、active_goal当前任务目标。每次调用模型前把这三块拼进Prompt。长期记忆则指跨会话存储的用户偏好或事实。比如用户是数据分析师他习惯看柱状图而不是饼图这个偏好应该被记下来下次对话直接用。长期记忆的存储可以选择向量数据库或普通数据库按用户ID和实体类型做检索。我的骨架里给长期记忆做了一个非常轻的接口save_memory(key, value) 和 get_relevant_memories(query)。接入具体存储时再换成向量检索或关键词检索。状态管理方面骨架必须保证每个Agent循环都有一个可序列化的状态对象。这个对象记录了当前步骤数、已完成步骤、待处理队列、最后几轮的工具调用记录。我习惯把每一步的action动作、observation观察、thought思考全部塞进一个日志文件。这样当Agent跑偏时你可以精确看到它是在哪一步开始偏的。3.4 评估与回归测试给Agent装一个仪表盘说到“累”很大一部分来源于不安全感改了一个Prompt不知道会不会影响其他环节换了一个模型不知道整体效果是变好还是变差。没有评估体系你永远只能靠人工聊天试来试去而且试完未必能发现那个藏在角落的回归问题。我建议每个Agent项目都准备一套“黄金案例集”。这个案例集不需要很大20到50个典型场景就够但必须覆盖核心功能路径和常见边界情况。每个案例包含三个部分用户输入、期望行为路径比如“应该先调用查询工具再判断是否有售后记录最后给出解决方案”、期望最终回答类型直接回答还是澄清问题。有了案例集就可以写一个轻量的评估脚本。每次改动Prompt、工具描述或模型版本后统一跑一遍记录两个核心指标行为路径匹配率Agent实际执行的步骤序列与期望路径的匹配比例。最终结果通过率最终输出的答案是否满足预设的通过条件比如包含关键字段、格式正确、语气合理。指标不能只看最终通过率还要关注路径匹配。有时候Agent虽然答对了但绕了很多弯路或者幻觉调用了一堆无用工具。路径匹配能帮你发现这类隐性问题。我见过一个项目最终回答看起来没毛病但数据来源完全是编造的就是因为路径匹配测试没覆盖到。4. 从零构建一套可落地的骨架实操记录4.1 环境与选型不要一开始就陷入“选哪个框架”的纠结。我的建议是骨架的运行时核心完全可以自研规模不大但边界清晰。模型接入层可以用现成的SDK但要统一封装成自己的接口避免业务代码跟具体模型绑定。语言方面Python依然是Agent开发最顺手的选择。生态里有大量的工具、SDK和调试方案。模型网关层我用一个简单的函数封装所有模型调用def chat_completion(messages, model, temperature0.2): # 内部根据model参数选择调用不同提供方的API # 统一返回 {content: ..., tool_calls: [...] } 结构 ...这样做的好处是项目里没有一个地方写着“某模型官方SDK”将来切换模型时只需要改这个网关内部的映射。网关还可以顺带实现超时、重试、token统计等功能。4.2 核心接口定义骨架的运行时我建议用这几个核心类来组织class AgentRuntime: def __init__(self, config, tools, memory): self.config config self.tools tools self.memory memory def run(self, user_input): state self.memory.init_state(user_input) for step in range(self.config.max_steps): response self._call_model(state) if response.type final: state.add_final_answer(response.content) return state elif response.type tool_call: result self.tools.execute(response.tool_name, response.args) state.add_observation(response.tool_name, result) else: # clarification or other state.add_message(response.content) return state这段代码是高度简化的但已经能说明骨架的核心逻辑循环、模型调用、工具执行、状态更新。实际实现里_call_model需要处理工具调用的输出格式解析。如果模型原生支持function calling就让模型直接返回结构化的tool_call对象如果不支持则需要自己解析模型输出的JSON字符串而且要做容错处理。tools.execute要负责查注册表、校验参数、调用执行函数、捕获异常并返回统一结果。一个工具注册器可以长这样class ToolRegistry: def __init__(self): self.tools {} def register(self, tool): self.tools[tool.name] tool def execute(self, name, args): if name not in self.tools: return {status: error, message: ftool {name} not found} try: return {status: success, data: self.tools[name].function(**args)} except Exception as e: return {status: error, message: str(e)}工具函数本身就是一段普通Python函数骨架对它们唯一的约束就是必须接受kwargs参数且返回值可以被json.dumps序列化。这个约束虽简单但能保证整个链路的数据流通顺畅。4.3 关键实现细节让工具调用更稳在实现工具调用时我踩过最大的坑是“让模型自由输出JSON”。早期我靠Prompt让模型输出一个包含tool_name和args的JSON再用正则去提取。这种方式极不稳定只要模型中间多一行解释性的文字解析就会失败。后来我改成了优先使用模型的function calling原生能力。所谓function calling就是你在请求里附上工具的定义列表模型在需要调用工具时会直接返回一个结构化的“调用请求”而不是生成一段JSON文本。这样解析工作基本由模型提供方完成稳定性高得多。如果你用的模型不支持function calling也别慌可以用一个更简单的方案让模型输出的第一行固定是“TOOL_CALL: {tool_name} | {json_args}”然后用严格解析器去读取并加上重试机制。另外一个提高稳定性的技巧是在系统Prompt里给出工具选择的“决策树”。比如你注册了三个工具可以在Prompt中写明“如果用户意图是A使用工具1如果是B使用工具2否则直接回答”。这个小动作能显著减少模型在工具间跳来跳去的情况。4.4 一份配置多项目复用骨架落地后我拿着一个“工单分析Agent”作为试验田。它的配置长这样system_prompt: | 你是工单分析助手。请根据用户提供的工单信息结合订单工具和历史记录工具给出分析结论。 不要凭空编造数据所有数据必须来自工具返回结果。 tools: - name: query_order description: 根据订单号查询订单详情。用户提到订单号时才使用。 schema: type: object properties: order_id: type: string description: 订单号例如2024-001 required: [order_id] - name: query_customer description: 根据用户ID查询客户历史工单。 schema: type: object properties: customer_id: type: string required: [customer_id] max_steps: 6 model: medium temperature: 0.2配套的工具函数只有一个query_order和query_customer。整个Agent代码只有几十行。最让我觉得爽的是后来做一个“竞品价格监测Agent”我几乎没动运行时只是新增了一个fetch_price工具把系统的Prompt从“工单分析”改成了“价格对比策略”再用一天时间配了几个规则就顺利上线了。这也对应了我总结的经验当骨架稳定后80%的新业务工作集中在“写Prompt”和“注册工具”上剩下20%是微调配置。相比之前的推倒重来效率提升是数量级的。5. 常见问题与排查技巧实录5.1 模型总是调用错误工具怎么办这是Agent开发里最经典的问题。我遇到过好几次用户问“我的退款到账了吗”模型不去查退款记录反而去调用了订单查询。排查思路是这样的第一步检查工具描述是否足够区分。如果你的“订单查询工具”描述写的是“查询订单信息”而“退款查询工具”写的是“查询退款信息”模型很容易把“退款到账”这个意图匹配到“订单”上。应该把每个工具的描述写成“在用户关心资金流向时使用退款查询工具在用户关心商品状态时使用订单查询工具”。第二步看模型是否真正读到了工具描述。有些模型对超长描述不敏感一下子塞了五六个工具它容易混淆。可以考虑把工具列表控制在五个以内并把最常用的工具排在描述前面。第三步就是借助Few-shot示例。在Prompt里加入一两组“输入-应该调用哪个工具”的示例比反复强调规则更管用。5.2 Agent陷入无限循环怎么办无限循环通常出现在“工具返回状态失败但模型无法正确认识状态”的时候。比如工具返回了一个空列表模型解读为“可能是查询方式不对”于是反复尝试同样工具同样参数轴在原地。解决方案很直接在工具返回里把“空结果”和“系统异常”区分开。空结果返回{status: empty, message: 未查询到记录请确认条件}异常返回{status: error, message: 系统繁忙请稍后重试}。同时在骨架层设置一个最大循环数通常5到8步。一旦超限强制Agent输出一个“目前无法完成可能需要更多信息”的兜底回答并结束循环。不要指望模型自己“醒悟”靠护栏兜底才靠谱。5.3 上下文太长导致效果变差Agent项目随着对话进行历史记录越堆越多。然后你会发现模型开始遗忘最初的目标或者被中间某个冗长工具结果带偏。我的处理办法是“三层收纳”对话历史只要最新的23轮更早的内容全部做摘要。工具结果每个工具的原始结果只保留刚执行的那个上一个工具结果只保留提炼过的关键信息字段。系统Prompt保持在1K token以内不给模型加载负担。另外工具返回的关键信息可以直接转成状态变量而不必一直钉在上下文里。比如查询订单之后把订单状态“已发货”存到state字段后续推理引用state字段而不是重复粘贴整个订单详情。5.4 换模型后效果明显变差这种情况很常见因为不同模型的指令跟随能力和格式偏好差异很大。骨架化之后这个问题处理起来会轻松很多。我会为每个模型准备一份“模型适配配置”里面有输出格式示例告诉模型最终回答或工具调用应该长什么样。系统Prompt微调有的模型喜欢“你是一个助手”这类更直接的角色设定有的模型则对角色描述很敏感。温度建议值新模型可能需要更低或更高的温度才能达到类似效果。同时换模型前一定跑一次黄金案例集。不要只看两三个手工测试就拍板有些细微差别只有跑完整套案例才能暴露。5.5 调试跟踪技巧给Agent做回放Agent跑偏时最怕的就是“黑盒”。我给自己加了一套全链路日志记录每次调用的完整数据输入到模型的消息序列含Prompt模板渲染结果模型原始输出包括思考过程、工具调用请求工具执行结果和耗时最终返回给用户的内容。日志写到SQLite或JSONL文件里配上时间戳和会话ID。排查问题时直接按会话ID调出整个Agent的执行轨迹可以一眼看出是哪一步出了问题——是Prompt拼错还是工具参数传歪还是模型给出了幻觉输出。有了这个能力排查效率完全是另一个量级。6. 把骨架用起来的额外心得最后聊一点跟技术无关但很重要的东西。骨架化最大的收益不只是代码复用而是让团队的思维方式从“每次都是新项目”转变成“每次都是新配置”。这个心态转变会直接影响你和需求方的沟通方式。当需求方提出一个新Agent想法时我不会再直接说“这个要从零搭了”而是会说“我们先梳理一下核心流程看要接哪几个工具再把Prompt定出来。”这种表达不仅给出确定性也能让合作方意识到Agent项目的核心工作在于业务定义而不在于“堆模型能力”。反而很多之前觉得高不可攀的Agent想法拆解成配置和工具之后落地难度瞬间降低。也要提醒一句不是所有需求都值得套骨架。如果你只是临时写个脚本调一次API或者做一个只有三五个case的教学Demo硬套骨架反而是过度工程。我建议在第三个Agent项目开始时再正式重构骨架。前两个项目先摸清边界积累好该沉淀的抽象然后一鼓作气把骨架立起来。这个节奏最舒服。我自己在把第一个硬编码项目重构成骨架时最大的感觉是代码量没少多少但维护时的焦虑感明显下降了。以前改一个工具调用逻辑就可能触发一连串不可预期的问题现在改完跑一遍案例集就心里有数。这个骨架会随着项目数量增长而不断进化你积累的每个Prompt技巧、每个工具封装经验都会沉淀下来成为你自己的产品能力底座。如果你正在被Agent项目反复摩擦不妨停下来花一到两周做一次抽象设计。定义一个最小的Agent运行时把工具注册、状态记忆、评估体系这四件事做扎实。这个时间花得很值因为你省下的是未来每一个项目里反复纠偏的日子。
