我最早被这个项目吸引是因为名字里带着九添菜菜这种个人色彩——说实话市面上讲大模型和Agent的教程不少但能真正把一个智能体从零跑到上线、并且把过程中的坑都记下来的反而不多。这个项目就是这样一份实战记录不绕弯子直接讲怎么选模型、怎么搭框架、怎么让Agent记住该记的、忘掉该忘的以及最后怎么把它部署到能用的状态。不管是刚接触大模型的小白还是已经写过几个RAG Demo、想更进一步做Agent开发的工程师这篇文章都值得花十分钟看完。1. 立项那会儿为什么非要用Agent单跑整套流程1.1 真实业务里多轮工具协作的需求从哪来先交代一下这个项目的出发点。最开始遇到的问题很朴素知识库问答已经能回答大部分问题但一碰到需要查数据 - 算结果 - 生成结论这种多步骤操作传统RAG就完全不够用了。举个例子用户问帮我统计上个月各门店的退货率并且按品类排个序。纯RAG做法是去文档库里找退货率相关片段返回一堆语义匹配的内容然后模型凭感觉写一段摘要。这中间既没有真正的计算也没有结构化的数据操作结果经常是错的。Agent要解决的就是这个痛点它把一个大任务拆成若干步每一步调用合适的工具——查数据库、执行计算、调接口、生成报告——最后再把结果组装成用户能看懂的回答。我在项目里最初圈定的三个场景是经营数据分析从数据库读取订单表按条件聚合输出结论售后工单处理根据用户描述判断问题类型调用工单系统创建或更新记录文档归类与摘要读取多份上传文档提取关键字段归档并生成摘要这三个场景有一个共同点都需要模型在理解意图之外真正去操作系统。这正是Agent比普通问答模型强的地方。1.2 跟普通RAG问答拉开差距的地方很多人会问RAG加了工具调用不就是Agent了吗这个理解不完全对。RAG是一种检索增强生成架构核心是查资料再回答Agent则强调自主决策和多步执行。区别用一句话说RAG是一次问答Agent是一个过程。在项目里我给团队画过一张对比表后来发现这张表对定位需求特别有用能力维度普通RAG问答Agent智能体信息获取从静态文档中检索可调用数据库、API、文件系统任务处理单轮问答多轮规划、拆解、执行上下文使用仅当前对话 检索片段可维护长期记忆和任务状态决策能力弱主要靠提示词通过ReAct或Function Calling自主决策可靠性中依赖检索质量取决于工具定义和验证逻辑如果你的业务只需要根据文档回答问题那老老实实做RAG就够了没必要上Agent。但一旦出现要拿数据、要调系统、要做判断这类需求Agent才是正确打开方式。2. 模型与框架哪家模型配哪套框架这件事我踩了一大圈2.1 开源模型和商业API的选择逻辑模型选型是整个项目里争论最久、也最不该走弯路的一环。市面上的选择看似很多但真正落到能不能稳定输出工具调用参数这个指标上可选项会迅速缩水。我最初的方案是全部用商业API——效果好、省事但跑了一个月后发现成本上扛不住。尤其是Agent场景和普通问答不一样一个任务可能要来回调用十几次模型每次调用都要传完整上下文token消耗是直线上升的。后来调整为核心推理部分用API高频简单任务用本地小模型成本立刻降了一半以上。在开源模型这边我实际测试过几款Qwen系列工具调用支持成熟中文能力强适合做主力开源模型DeepSeek系列推理能力突出在复杂任务规划上表现不错GLM系列中文表现好但在Function Calling的稳定性上早期版本不如QwenLlama系列英文生态好中文能力需额外微调或配合提示词优化如果你跟我一样需要本地部署我建议优先看Qwen2.5系列或DeepSeek-R1-Distill系列。前者在工具调用稳定性和中文理解上平衡得最好后者在推理链路长的任务上更聪明但需要更多显存。注意本地部署时一定先确认显存大小再选模型不要盲目上最大参数版本。7B模型在量化后大约需要6GB显存实际测试中跑Agent任务建议保留至少1GB余量给上下文处理否则并发一高就容易OOM。2.2 框架选择LangChain、Dify还是自己写编排框架这一层我前后试过三套方案分别代表了三个思路。第一套是LangChain。生态最大组件最全但抽象层太多。我刚上手时花了很多时间在理解Chain、Agent、Tool之间的关系上而且版本更新快经常一升级代码就废了。后来我的定位是可以做学习和验证但不适合直接拿来做生产系统的地基。第二套是Dify。它对非程序员非常友好页面拖拖拽拽就能搭一个Agent出来内置了知识库、工作流、模型管理等功能开箱即用。但我很快就碰到了天花板复杂业务逻辑在可视化编排里表达很费劲而且自定义工具和回调逻辑的灵活性不够一旦涉及到特殊鉴权或者定制化处理就很憋屈。第三套是自研轻量编排。所谓自研不是说从头造轮子而是用模型提供的Function Calling能力自己写一套精简的Agent循环意图识别 - 工具选择 - 参数填充 - 执行验证 - 结果反馈。代码量不算大但每个环节都在自己的掌控中出了问题能直接定位到具体逻辑。我最终选用的是第三套方案原因有两条一是业务逻辑里的工具类型太杂需要精细控制二是Agent的调试本身就很考验可观测性自研编排可以把每一步运行的日志完整保留下来这在排错时至关重要。2.3 我最终采用的目录结构和核心配置放一个实际项目的目录结构大家感受一下这类项目的工程化长什么样agent_project/ ├── agent/ # Agent核心编排逻辑 │ ├── core.py # 主循环规划-执行-观察-反思 │ ├── tools/ # 工具注册与实现 │ │ ├── database.py # 数据库查询工具 │ │ ├── api_client.py # 外部API调用工具 │ │ └── file_op.py # 文件读写工具 │ ├── memory/ # 记忆模块 │ │ ├── short_term.py # 对话上下文管理 │ │ └── vector_store.py # 长期向量记忆 │ └── prompt/ # 提示词模板 ├── models/ # 模型接入层 │ ├── api_llm.py # 商业API封装 │ └── local_llm.py # 本地模型封装 ├── eval/ # 评测集与评测逻辑 │ ├── cases.json # 测试用例 │ └── runner.py # 评测执行脚本 └── deploy/ # 部署配置 ├── Dockerfile └── docker-compose.yml核心配置文件里我认为有三个关键参数直接影响Agent表现# 模型相关配置 LLM_CONFIG { api_model: qwen-plus, # 商业API模型用于重要推理 local_model: qwen2.5-7b-instruct, # 本地模型用于高频轻量任务 temperature: 0.1, # Agent场景尽量低减少随机性 max_tokens: 4096, timeout: 30, } # Agent运行参数 AGENT_CONFIG { max_iterations: 8, # 单次任务最多执行8步防止死循环 enable_reflection: True, # 执行后反思修正错误 tool_timeout: 10, # 单个工具执行超时 } # 记忆相关配置 MEMORY_CONFIG { short_term_window: 10, # 保留最近10轮对话 vector_top_k: 5, # 向量库检索返回top-5 memory_score_threshold: 0.75, # 低于阈值的记忆不召回 }temperature设成0.1是我反复测试后的结论。Agent场景和创作型任务完全不同它需要模型尽可能稳定地输出工具调用格式温度高了很容易出现参数乱写。max_iterations设成8也是经验值正常任务5步之内都能完成超过8步基本就是陷入了循环或逻辑混乱继续执行只会浪费token。3. 把Agent拆开看规划、记忆、工具调用一条链是怎么跑通的3.1 ReAct循环和System Prompt设计Agent的核心机制绕不开ReAct这个模式我在项目里用得非常顺手。ReAct的核心思想是让模型在**推理Reasoning和行动Acting**之间交替进行每走一步模型先输出对当前状态的思考再决定调用哪个工具观察工具返回结果后继续思考直到任务完成。实现一个精简版ReAct循环并不复杂核心代码如下def run_agent(task: str): messages build_initial_messages(task) for step in range(AGENT_CONFIG[max_iterations]): # 1. 调用模型获取意图和工具调用请求 response llm.chat(messages, toolsAVAILABLE_TOOLS) messages.append(response) if response.finish_reason stop: return response.content # 模型认为任务已完成 # 2. 模型发起了工具调用 for tool_call in response.tool_calls: tool_name tool_call.function.name tool_args json.loads(tool_call.function.arguments) # 3. 执行工具 result execute_tool(tool_name, tool_args) messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse) }) # 4. 可选反思步骤检查上一步结果是否合理 if AGENT_CONFIG[enable_reflection] and step % 2 1: messages.append(reflection_message()) return 任务执行达到最大步数已中止代码本身不复杂真正的门道在System Prompt设计上。我见过很多失败案例问题几乎都出在System Prompt写得太笼统。我最终的Prompt结构包含四个部分角色与任务边界你是谁、能做什么、不能做什么工具使用规则每个工具何时用、何时不用的判断标准输出格式要求最终回答的结构、语气、是否要附数据说明安全限制什么类型的请求要拒绝、什么操作需要二次确认举一个工具使用规则的实际写法当用户询问退货率销售额订单量等指标时你必须先调用 query_database工具获取数据禁止直接凭已有知识回答。 若查询结果为空请明确告知用户未查询到相关数据不要编造。 调用query_database工具时参数必须严格遵循 - table: 表名只能是 orders / products / stores 中的一种 - metrics: 指标列表如 [return_rate, total_sales] - group_by: 分组字段可选例如 store_id - filters: 筛选条件可选例如 {date_range: 2025-01-01~2025-01-31}这样写之后模型调用工具的准确率提升非常明显。我发现了一个规律Prompt里的规则越具体模型越不会自由发挥规则越抽象模型越容易返回一些模棱两可的格式。3.2 工具注册与Function Calling工具调用是Agent和外部世界交互的桥梁。在OpenAI兼容接口的体系里Function Calling通过JSON Schema来描述工具参数模型根据Schema生成调用请求。我在项目里把所有工具统一做成一个注册表结构TOOLS_REGISTRY [] def register_tool(name, description, parameters_schema, handler): TOOLS_REGISTRY.append({ type: function, function: { name: name, description: description, parameters: parameters_schema } }) TOOLS_HANDLERS[name] handler # 示例注册一个数据库查询工具 register_tool( namequery_database, description查询经营数据库支持按条件聚合统计订单、商品、门店数据。所有涉及退货率、销售额、订单量的问题必须使用此工具。, parameters_schema{ type: object, properties: { table: { type: string, enum: [orders, products, stores], description: 要查询的表名 }, metrics: { type: array, items: {type: string}, description: 要计算的指标列表 }, group_by: { type: string, description: 分组字段 }, filters: { type: object, description: 筛选条件 } }, required: [table, metrics] }, handlerquery_database_handler )从这几十次的实操经验里我总结出工具定义最重要的三个原则description要写何时用而非是什么。模型不会像人一样从工具名推断用途它主要读description。描述里明确当用户提到XX时必须使用此工具比单纯写查询数据库效果好得多参数用enum约束取值范围。给模型太多自由它就给你太多惊喜。能用枚举的绝不用open stringrequired字段要精简。只填最核心的必传参数其余作为可选能显著降低模型生成非法JSON的概率3.3 记忆模块短时上下文 长期向量库记忆是Agent项目里最容易翻车、也最影响体验的模块。我在项目里把记忆分成两层短时记忆指的是当前任务内或当前会话内的上下文。实现上就是一个消息队列保留最近N轮模型对话。需要注意的坑是不要把所有历史都塞进上下文。一方面token消耗巨大另一方面模型会迷失在长文本中对最近的指令反而关注度下降。项目里我把短时窗口控制在10轮超过的做摘要压缩def compress_history(messages, max_tokens2000): 把超出窗口的历史消息压缩成摘要 if estimate_tokens(messages) max_tokens: return messages old_messages messages[:-10] # 保留最近10轮 summary_prompt f请把以下对话压缩成200字以内的摘要保留关键信息\n{old_messages} summary llm.chat([{role: user, content: summary_prompt}]) return [{role: system, content: f历史对话摘要{summary}}] messages[-10:]长期记忆解决的是跨会话的知识沉淀问题。用户今天告诉Agent我是华东区的运营负责人明天再对话时Agent应该还记得。这个我用向量库实现先把关键信息拆成小块向量化存入数据库每次新对话开始时检索相关记忆注入上下文。向量库选型上如果数据量在百万条以下用轻量的Chroma或FAISS就够了不需要上ES那种重武器。真正影响效果的不是向量库本身而是拆块策略和检索阈值。记忆拆块不能简单按字数切要按语义边界切。比如我是华东区的运营负责人我们区域主要做线上渠道应该作为一条独立记忆而不是跟后面的聊天记录混在一起。4. 实战中反复翻车的四个环节及修复记录4.1 工具参数错乱模型学不会JSON Schema项目第一个星期我碰到最头疼的问题是模型偶尔会把字符串值填进integer字段或者把所有参数都挤在一个字符串里。后来检查发现问题出在参数Schema写得和模型训练数据里的格式不完全一致。例如我的Schema写了filters: {type: object}但没定义子结构模型就只能自由发挥。这时候要给它一个examplefilters: { type: object, properties: { date_range: {type: string, description: 日期范围格式YYYY-MM-DD~YYYY-MM-DD}, store_id: {type: string, description: 门店ID} }, description: 筛选条件例如{date_range: 2025-01-01~2025-01-31, store_id: S001} }在description里给出完整示例是降低模型出错率最有效的手段因为模型擅长模仿文本模式而不是理解抽象的数据类型定义。这点我后来也放入每篇工具开发的检查清单里。4.2 记忆污染把陈年对话当成了事实这个坑是在项目上线两周后暴露的。用户的业务数据会定期更新但Agent在回答上个月退货率是多少时居然从长期记忆里翻出了两个月前的旧数据。检讨之后发现问题出在两个方面第一记忆没有时间戳。向量检索只比对了语义相似度无法判断信息的新旧。修复方案是在存记忆时带上数据日期检索时优先返回时间戳较新的记录# 存储时 memory_entry { content: M01门店2月退货率8.5%, metadata: { date: 2025-03-01, # 关键记录数据产生时间 category: business_data } } # 检索时对同类记忆按时间降序只保留最新一条第二长期记忆里混入了对话中的猜测性内容。用户随口说的我觉得销量可能要降也被存进了向量库后续检索时就成了事实。修复方案是只允许保存确定性陈述我是XX、X月数据为XX所有带有推测、疑问、情绪的内容一律过滤。4.3 检索召回和重排的调优顺序向量检索的调优有个很反直觉的点召回数量不等于质量。项目初期我把top_k设成20心想多召回点总没错结果模型在信息过载中反而开始编造答案。后来我把方案调整为top_k从10降到了5并增加了一个重排步骤用一个专门的rerank模型对召回结果打分再取前3送入模型。调优后的效果对比指标top_k20无重排top_k5重排检索结果准确率62%81%回答正确率58%76%平均延迟380ms420ms多一个重排用户反馈答非所问次数明显多明显减少为了那18个百分点的准确率多花40ms延迟是非常划算的买卖。业务上对50毫秒的延迟基本无感但对AI又瞎回答的容忍度很低。4.4 并发与限流Agent一上线就超时开发环境里一切正常一上生产环境就超时。这是Agent项目的普遍尴尬开发时单用户测试Token消耗少上线后多个用户同时跑Agent任务每个任务又循环调用模型多次自然把模型服务和工具服务的压力拉满。我做的优化有三步连接池复用HTTP连接和数据库连接都改用长连接池避免每次调用重复握手任务队列削峰高并发时把Agent任务放入消息队列我用的是Redis Stream消费者按固定速率处理避免瞬时压力模型兜底降级如果本地模型负载过高自动切换到API模型如果API也超过预算降级为简单RAG模式回答这套方案实施后项目最高跑到了500人同时在线使用Agent任务平均响应时间控制在3秒以内没有再出现大规模超时事故。5. 从能跑到跑稳性能、成本、代码之外的功夫5.1 评测集怎么建说到Agent项目最容易被忽视的部分绝大多数人会投评测一票。Agent和普通模型接口不一样它每一步的决策都可能出错工具选错、参数传错、循环出不来、结果答非所问。没有一套系统的评测集你根本不知道改了一版Prompt之后是变好了还是变差了。我的做法是建了三类评测用例单步工具调用测试给定输入检查模型是否选择了正确的工具、参数是否合法多步任务完整测试模拟真实业务场景检查Agent最终给出的答案是否正确边界与异常测试包括不可回答的问题、工具返回空数据、模型陷入死循环等每类用例都写成JSON存到eval/cases.json里。每次改动Prompt或工具定义就跑一遍评测脚本对比通过率变化。这个习惯帮我抓住了好几次改好了A场景却弄坏了B场景的回归问题。5.2 成本优化的几个实际方法Model成本是Agent项目运营的命门。我做了三个有效动作第一任务分类分流。先让小模型判断任务类型需要复杂推理的走大模型API简单查询走本地小模型分类本身用一次轻量调用完成。这个网关模型的开销只占总成本的2%左右但省下了将近40%的整体开支。第二缓存常见任务的中间结果。同一类查询比如本周退货率在一小时内可能有多个用户问结果其实差不多。我加了一层基于语义的缓存命中后直接返回不再调用模型。第三结果压缩。Agent执行完任务后最后一步让模型把完整结果压缩成100字内的摘要再发给用户。这一步本身会多消耗一次调用但因为减少了输出token整体反而省钱。注意这个策略只适用于结论型任务不适用于报告型任务。5.3 上线后的监控与迭代Agent上生产之后必须有三个监控指标工具调用成功率低于90%就要查工具定义或模型版本平均迭代次数超过5步说明Agent在绕路可能是Prompt引导不够明确用户侧反馈率用户点回答有帮助和回答无帮助的比例这是最真实的信号我在项目里维护了一个专门的坏案例本每收到一个用户反馈这回答不对就把它加进评测集。这个习惯对Agent产品质量的提升效果比任何模型调参都明显。因为坏人案例会逼着你持续修正工具定义、记忆逻辑和Prompt规则而这才是Agent效果提升的真正的复利曲线。6. 一段阶段的个人经验体会最后说点项目之外的体会。做Agent开发和传统软件开发最大的不同是几乎每次修改都要通过实测验证不能靠逻辑推理。你改一行Prompt可能影响的是三十个场景中的五个你调一个工具Schema可能让另一个工具的调用成功率下降。所以我的建议是尽早建评测集哪怕刚开始只有十条用例也值得。每改一次代码就跑一遍坚持一周你对Agent的掌控力会完全不一样。另一个让我印象很深的经验是Agent项目70%的代码都在处理模型不听话的情况。解析JSON失败重试、上下文超长做压缩、工具超时做降级、结果不对劲让模型反思重来——这些防御性代码才是Agent稳定性的基石。不要指望模型百分之百按规矩出牌要假设它一定会出乱子然后把各种乱子的兜底逻辑写好。如果你准备动手做一个Agent项目我的建议是别一上来就奔着复杂框架去先用最简单的方式把模型 工具 循环这三角跑通再一步步加记忆、加评测、加监控。过程中遇到的问题大概率跟我在项目里踩过的坑一样翻了这篇记录能少走不少弯路。