“AI能帮我干活了吗”这两年被问得最多的问题大概就是这一句。作为一个常年跟大模型应用打交道的开发者我可以很负责任地说能但前提是别把它当成一个聊天窗口而要当成一个需要认真设计的软件系统来做。AI智能体AI Agent的开发方案本质上就是在解决一件事——怎么让模型在真实业务环境里“自己动起来”。它跟普通问答机器人的区别很直接问答机器人你问一句它答一句答完就完了智能体则需要自己理解目标、拆解步骤、调用工具、核对结果甚至在出错时自己调整路径。这篇内容不是教科书是我自己从零搭建智能体时沉淀下来的一套可落地方案包括整体架构怎么搭、核心模块怎么选、代码怎么写、上线之后哪些坑最值得提前躲开。不管你是刚接触智能体的新手还是已经在做原型验证的开发者我都尽量用“能直接抄作业”的方式来讲清楚。1. 为什么现在做AI智能体以及它到底在解决什么问题1.1 从“会说话”到“会办事”的本质变化先把概念拉回到一个非常朴素的场景。你在对话框里问模型“帮我查一下这个月的销售数据”模型能做的只是告诉你“你可以去后台看报表”因为聊天模型本身没有权限接触你的业务系统。但如果给模型加一个“查询销售数据”的函数入口它就可以自己去调用接口、拉取数据、再基于结果做分析甚至接着帮你写一封给团队的摘要邮件。这个“加一个函数入口”的动作就是智能体开发的核心骨架。所以我对智能体的定义一直很简单一个能够自主完成多步骤任务的系统它由大模型提供决策能力由代码提供执行能力。大模型负责“想”代码负责“做”。这个定义决定了你在设计时要想清楚哪些事情该让模型想哪些事情该用代码兜底。1.2 哪些业务场景适合先用智能体结合我经手过的几个模拟项目智能体最适合用在“流程长、规则多、需要频繁查数据”的场景比如客服工单自动处理、数据分析问答、文档合同初审、运维告警初筛。这些场景有一个共同特征以前的自动化脚本写不出灵活判断人工处理又太重复而智能体恰好能在这两者之间找到一个平衡点。但也要提醒一句不要为了智能体而智能体。如果某件事一个普通函数就能搞定就老老实实写普通函数。智能体的优势在于“需要根据中间结果动态决定下一步”如果流程完全固定传统工作流反而更稳定、更省钱。1.3 开发前必须明确的三大边界智能体的决策范围要提前划清楚。比如让它能查数据、能生成报告但不能直接下订单、不能删数据除非有人工审批环节。大模型会产生幻觉所以输出必须经过格式校验和逻辑校验不能直接落库。上下文长度是硬约束长任务必须做记忆压缩或分阶段处理不能把所有历史一股脑塞给模型。这些边界如果在一开始不定义清楚后面每个环节都会返工。我见过不少团队把智能体做成一个“能聊但不敢用”的玩具问题几乎都出在这三条边界上。2. 智能体整体架构与方案选型2.1 单智能体还是多智能体我建议怎么选关于这个问题网上争论很多。多智能体听起来很炫每个角色各司其职像一个虚拟团队但实际工程化的成本非常高。通信协议、状态同步、错误传播任何一个环节没设计好整个系统就会变成一堆模型互相甩锅。我的建议很务实优先做单智能体把核心流程跑通之后再考虑拆分。一个单智能体可以包含多个“角色模块”比如一个函数负责规划、一个函数负责执行但决策主体始终只有一个。真的遇到需要多人协作的任务时更稳妥的折中方案是“编排者多个专用子Agent”模式由编排者负责调度不搞完全对等的多Agent协商。2.2 核心模块拆解规划、记忆、工具、行动智能体不是“一个模型”而是一套流水线。我习惯把它分成四层规划层接收目标拆解为步骤决定调用哪些工具。这是模型的强项也是幻觉最容易被放大的地方。记忆层保存当前任务状态和历史关键信息。分为短期记忆当前对话上下文和长期记忆跨会话的用户偏好、业务规则库。工具层把外部系统包装成模型可调用的函数这是连接真实世界的桥。行动层真正执行工具调用拿到结果后回填给模型继续下一轮决策。四层之间最容易被忽略的是“行动结果回填”这一步。很多新手只让模型输出一段计划然后代码直接按计划执行执行完也不把结果告诉模型相当于模型只管开头不管结尾。正确的做法是每执行完一步把结果做成结构化数据送回给模型让它判断下一步要不要调整。我对规划层的原则模型的规划能力很强但完全自由发挥不可控。所以我会用“半自动规划”模型先给一个粗略方案代码用规则做一些约束校验比如“步骤不能超过五步”“核心业务字段必须齐全”再放行。这样既能保留灵活性又不会让模型跑偏到离谱的方向。2.3 编排框架选型与自研取舍市面上有不少智能体编排框架有些偏底层、有些偏应用。我的观点是框架可以用但要清楚框架帮你解决了什么、没解决什么。框架主要解决三件事把“模型调用、工具注册、对话循环”串起来省去重复造轮子的时间提供常用工具如搜索、HTTP请求的标准封装内置一些记忆和上下文的处理策略。但框架没有解决业务正确性、安全审计、性能调优、评测体系这些问题这些还是要自己搭。我自己经手的项目分两类情况推荐如果是快速原型验证直接用轻量框架投入小见效快如果是生产级系统我更倾向于“轻框架自研控制层”用框架管理对话循环和工具解析但把任务状态机、权限校验、日志审计完全剥出来自己做。用框架最怕的是业务逻辑和框架深度耦合一旦框架升级或需要替换项目就寸步难行。就像装修时先想清楚哪些是承重墙别等住进去才发现砸不了。3. 从零实现一个可用的智能体3.1 环境准备与通信层设计先说通信也就是模型从哪里来。我不打算绑定任何特定厂商就用最通用的HTTP协议调大模型接口。你需要准备三个配置接口地址、密钥、模型名称。这三个值建议全部放到环境变量或配置中心不要硬编码在代码里否则每次切换模型供应商都要改代码非常被动。# config.yaml llm: api_base: https://your-llm-service.example.com/v1 api_key: ${LLM_API_KEY} model_name: default-chat-model max_tokens: 2048 temperature: 0.2注意temperature这个参数。智能体任务要求稳定输出尽量控制在0到0.3之间我给规划类任务通常设0.1给创意生成类任务才放到0.7以上。温度太高模型会频繁改主意导致工具调用路径不稳定。3.2 核心循环让模型驱动工具调用智能体的核心是一个循环组装消息、请求模型、判断是否需要调用工具、执行工具、返回结果、再次请求模型。我把代码写成一个简化的单轮处理流程方便你理解骨架def agent_run(user_task, tools, config, max_iterations5): messages [{role: system, content: build_system_prompt()}] messages.append({role: user, content: user_task}) for step in range(max_iterations): response call_llm(messages, config) content response[content] tool_calls response.get(tool_calls, []) if not tool_calls: return content messages.append({ role: assistant, content: content, tool_calls: tool_calls }) for call in tool_calls: result execute_tool(call[name], call[arguments]) messages.append({ role: tool, tool_call_id: call[id], content: json.dumps(result, ensure_asciiFalse) }) raise RuntimeError(超过最大迭代次数任务中止)这个循环虽然短但包含几个关键点。第一必须有max_iterations上限防止模型陷入无限循环这是我的保命底线。第二每轮请求会带上之前所有的中间结果所以messages列表会不断变长这也是为什么我后面要讨论上下文压缩。第三工具返回的结果我用JSON字符串回填这样模型能精确读到结构化数据。3.3 工具注册与描述设计工具是智能体的“手脚”工具描述的好坏直接决定模型会不会用它。模型看不到函数实现只能看到你给它的JSON Schema描述。如果描述写得太含混模型就可能瞎猜参数或者干脆不调用这个工具。一个标准的工具描述包含名称、用途说明、参数列表、必填字段、返回值结构。我给一个实际案例模拟一个“查询订单状态”的工具{ name: query_order_status, description: 根据订单号查询最新物流状态和签收信息适用于用户问‘我的货到哪了’的场景, parameters: { type: object, properties: { order_id: { type: string, description: 用户提供的订单编号通常是字母和数字组合 } }, required: [order_id] } }这里有三个细节值琢磨。第一个描述里要带“适用于什么场景”这能有效提高模型命中率。第二个参数描述要说明格式比如订单号“通常是什么组合”模型会据此从用户说话里提取。第三个返回值结构也要在描述里写清楚最好让工具返回字段稳定模型才好做后续判断。3.4 执行层的容错设计工具执行不是无脑调用就行。我在行动层加了三道防护超时控制每个工具单独设置超时时间比如HTTP查询类工具5秒超时重试一次。模型等待太久会导致整个任务卡死。结果裁剪工具返回条数过多时先做截断保留最重要的字段。比如查询订单列表最多返回最近20条每条只保留核心字段避免把几十KB文本灌进上下文。异常兜底工具抛出异常时不要直接让系统崩溃而是把错误信息转成一句结构化反馈比如{error: 订单号不存在}再送回给模型。模型会依据这个信息尝试换个订单号或者如实告诉用户查不到。我踩过一次坑查询函数里数据库超时了代码直接抛出异常整个智能体对话中断用户只能看到“系统繁忙”。后来我把所有工具调用都包了一层try-except把异常转成自然语言反馈。从那以后即使后端的接口挂了智能体也能用“查询服务暂时不可用请稍后再试”优雅地回复用户。这个改动很不起眼但对体验的提升是决定性的。3.5 记忆压缩与上下文管理智能体跑任务多轮之后上下文一定会膨胀。我见过一个数据查询任务模型跟工具来回对话20轮最后一轮的上下文里塞了2万多个token其中一半是过时的中间结果。这不仅费用高还会稀释模型对最新任务的注意力。我的方案是分层处理。短期记忆保留最近三轮完整对话更早的内容用摘要代替我在每轮结束时让模型用自己的话说一遍“目前已完成哪些步骤、还差哪些信息”存成一段紧凑的进度摘要。当前业务的原始结果不存历史只存各自总结后的要点。长期记忆单独放向量库或数据库按会话ID读取不进主循环。这个分层方案实测下来很稳上下文体积能压缩到原来的三分之一左右而且因为模型始终能看到“当前进度摘要”它反而更能把握任务全貌。如果用的模型接口本身就支持上下文压缩你也可以让平台自动压缩但我还是建议业务方自己对关键状态做持久化至少重启会话后用户问“刚才那个单查好了吗”系统还能回答上来。4. 常见问题与排查技巧实录4.1 模型反复调用同一个工具陷入死循环我在实验阶段遇到最烦的问题模型查了一次库存发现缺货然后它竟然又去查了一次库存缺货再查一次……循环了五次直接被我这边的最大迭代上限拦停。原因有两个一是工具返回里没有足够的信息让它“下台阶”二是缺少对重复动作的抑制。解法分两步。第一步控制工具返回内容缺货的情况下直接在结果里带上“该商品目前缺货建议提示用户选择替代品”给模型指明下一步。第二步在代码里记录工具调用序列如果检测到“同一工具、相同参数”连续出现两次就主动中断循环转而向模型抛出提示请基于已有结果直接回答用户。这个规则成本极低但能省下大量无谓的模型调用开销。4.2 模型输出不是合法JSON工具参数解析失败工具调用依赖模型输出结构化参数但模型偶尔会输出残缺JSON比如多一个逗号、引号没闭合。这是大模型应用里最经典的坑。我给自己的工具箱常备一个小的修复环节先尝试直接解析解析失败则做轻量清洗比如去掉多余包装文本、补齐缺失的后引号还不行就把原始内容发给模型让它“仅输出修复后的JSON”。这个方法批量处理下来成功率能到98%以上。更治本的做法是在给模型的系统提示里增加一段工具调用的few-shot示例并用明确的格式约束词比如“参数必须输出合法JSON不要包含Markdown代码块标记”。4.3 上下文被工具结果撑爆费用飙升前面讲了摘要压缩我再补充一个更立竿见影的优化给每个工具定义输出字段的白名单无关字段直接在工具侧删除不要进入上下文。比如查询用户信息返回里有几百个字段但模型只需要手机号和用户等级那就在返回前过滤掉其他字段。另外我建议做成本监控。按会话维度记录每次请求的输入token数、输出token数和耗时拉成曲线。智能体的成本通常是一个慢性增长的过程等你肉眼看出来账单不对劲的时候往往已经超支不少了。我现在接项目都会在第一天就把token日志打上排查时能精确看到是哪一轮请求吃掉了大部分预算。4.4 智能体“行动正确但回答跑偏”有时候工具调用完全正确数据也拿到了但模型在总结时自己加了点臆测把没有的数据说成有。这个问题必须在最后出口做校验。我的做法是加一个“答案校验层”用规则引擎检查模型最终回答里是否包含指标性数字如果回答中的关键数字无法对回到工具返回结果就打回重写。另外加上一句系统约束“回答必须严格基于工具返回的数据范围超出数据范围的内容一律不得输出。”对于金融、医疗这类高合规场景我甚至建议直接把回答限制成“编辑工具返回结果做格式化输出”禁止模型自行扩写。4.5 多用户并发下的状态隔离智能体如果做成服务一定会碰到并发问题。多个用户同时使用如果记忆存在一个全局的变量里A用户的任务状态就会被B用户覆盖。这个错误我在早期犯过一次有个查询任务里我自信地用了全局字典存对话历史结果上线半小时就有用户串了上下文差点闹出事故。正确做法是给每个会话单独分配一个上下文容器最好用带租约的存储例如按会话ID作为key的Redis存储缓存一个小时自动过期。每个用户的工具执行要保持无状态所有可变状态都随着请求传进去。如果任务之间有共享资源比如都要写同一个文件务必加锁或者改成按用户分目录。智能体开发到现在技术框架已经相当成熟了真正拉开差距的其实是工程细节工具描述写得好不好异常兜底密不密上下文管理松不松评测体系实不实。我个人的体会是每上一条新功能就先问自己三个问题——模型失控了系统会不会挂用户乱输入会不会出安全事故中间状态丢了能不能恢复。三个问题都过了这个功能才敢放上线。最后再分享一个小技巧给智能体加一条“我不确定就直说”的指令。现实场景里模型最怕的就是硬撑着给出一个看起来很笃定但其实错得离谱的答案。培养智能体主动承认“查不到”的习惯比训练它变得更聪明反而更能提升用户的信任感。希望这篇方案能帮你少走几步弯路也欢迎你在实践之后再回来聊聊踩过的坑。
