1. 从六个真实场景切入Agent 到底能干什么聊 Agent 之前先把概念说清楚。Agent 这个词现在被用得有点泛有人管它叫智能体有人管它叫代理还有人把它和 LLM、AI 模型混着用。我自己的理解是Agent 是一个能感知环境、做出决策、调用工具、执行动作并拿到反馈的闭环系统。它和单纯的 LLM 最大的区别在于LLM 是“你问它答”Agent 是“你给目标它自己想办法完成”。这个区别听起来简单但落到实际应用里差别是巨大的。你问 ChatGPT“帮我写一封邮件”它给你一段文字你还得自己复制、粘贴、发送。你给 Agent 一个目标“帮我处理今天收到的客户咨询邮件”它会自己去读邮箱、分类、起草回复、调用发送接口甚至在你设定的规则下自动发出。这就是从“对话”到“执行”的跨越。我过去一年多在几个不同项目里落地过 Agent 方案踩了不少坑也总结了一些还算靠谱的经验。这篇文章不打算泛泛而谈“Agent 前景广阔”这种废话而是直接拆解六个我亲自做过或者深度参与过的典型案例把每个场景的核心逻辑、技术选型、实操步骤、踩坑记录都摊开来讲。无论你是刚接触 Agent 开发的新手还是已经在做多 Agent 协作的老手应该都能从里面找到能直接抄作业的东西。先给一个全局的认知框架。目前 Agent 的应用场景按复杂度和自主性大致可以分成三层层级特征典型场景技术难度L1 工具调用型单轮任务调用 1-3 个工具查天气、发邮件、搜索低L2 流程编排型多步骤任务需要状态管理客服工单、数据分析中L3 自主协作型多 Agent 分工动态规划软件开发、复杂研究高下面六个案例基本覆盖了这三个层级。我会从最简单的开始逐步深入到复杂的多 Agent 协作。2. 案例一智能客服工单自动处理2.1 场景描述与核心需求这是我最开始做 Agent 落地的场景也是我认为最适合新手入门的。一家做 SaaS 的客户每天收到大概 300-500 封客户邮件内容涵盖退款申请、功能咨询、Bug 反馈、账号问题等。原来靠 3 个客服人工分类和回复平均响应时间 4 小时客户满意度一直上不去。核心需求很明确自动读取邮件、分类、根据类别调用不同的处理流程、生成回复草稿、高置信度的直接发送低置信度的转人工。这个场景的好处是任务边界清晰成功标准可量化分类准确率、响应时间、客户满意度而且有大量历史数据可以用来评估。2.2 技术选型与架构设计技术栈我选的是LangChain GPT-4 Redis。为什么选 LangChain 而不是自己从零搭因为这个场景需要快速迭代LangChain 的 Chain、Tool、Memory 抽象能省掉大量胶水代码。Redis 用来做两件事一是缓存历史对话和用户画像二是做任务队列避免邮件量突增时系统崩溃。架构上分四层接入层IMAP 协议读取邮件解析出标题、正文、发件人、历史往来决策层Agent 核心负责分类和路由执行层不同类别的处理工具比如退款工具、查询工具、转人工工具反馈层记录每次处理结果用于后续评估和微调这里有个关键设计决策分类和路由要不要分开做我试过两种方案。方案 A 是一个 Agent 同时做分类和路由方案 B 是两个独立的 Agent一个专门分类一个专门路由。实测下来方案 B 的准确率高 8 个百分点因为分类任务和路由任务的 prompt 差异很大混在一起容易互相干扰。虽然多了一次 LLM 调用成本增加约 15%但准确率提升带来的收益远大于成本。2.3 实操步骤与关键配置第一步构建分类 prompt。这里有个技巧不要只给类别名称要给每个类别配 2-3 个真实例子。比如“退款申请”这个类别我放了三个例子分别是“我要退款”、“这个功能没用退钱”、“申请取消订阅并退款”。实测下来带例子的 prompt 比只给类别名的准确率高 20% 以上。第二步设置置信度阈值。Agent 对每封邮件的分类会输出一个置信度分数我设的阈值是 0.85。高于 0.85 直接走自动流程低于 0.85 转人工。这个阈值不是拍脑袋定的而是用历史数据跑出来的在 0.85 这个点上自动处理的准确率是 96%转人工的比例是 18%综合成本最低。第三步设计工具调用接口。每个工具就是一个函数输入是结构化的邮件信息输出是处理结果。比如退款工具def process_refund(email_info: dict) - dict: # 校验订单号 order verify_order(email_info[order_id]) if not order: return {status: failed, reason: order_not_found} # 检查退款政策 if not is_refundable(order): return {status: failed, reason: not_refundable} # 执行退款 result execute_refund(order) return {status: success, refund_id: result[id]}第四步设置人工兜底。所有转人工的邮件会进入一个队列客服在后台看到的是 Agent 已经整理好的摘要、分类建议、推荐回复客服只需要确认或修改。这样客服的效率提升了 3 倍原来处理一封邮件要 5 分钟现在只要 1.5 分钟。2.4 踩坑记录与优化心得第一个坑邮件正文里的引用内容会干扰分类。很多客户回复时会带上之前的邮件全文导致正文很长Agent 容易被无关内容带偏。解决办法是在预处理阶段把引用部分截掉只保留最新回复。第二个坑多语言邮件处理。客户有用英文、日文、中文写的一开始我只用中文 prompt英文邮件的分类准确率只有 70%。后来改成“无论邮件是什么语言都用中文输出分类结果”准确率恢复到 92%。第三个坑Agent 的“幻觉”问题。有次 Agent 给一个客户回复了“您的退款已处理”但实际上退款工具调用失败了。原因是 Agent 在生成回复时没有等待工具返回结果就自己编了。解决办法是强制 Agent 在生成回复前必须拿到工具的执行结果用 LangChain 的AgentExecutor的return_intermediate_stepsTrue来检查。提示客服场景的 Agent最重要的不是多智能而是多可靠。宁可转人工也不要自动回复错误信息。3. 案例二数据分析与报表自动生成3.1 场景描述与核心需求第二个案例是一家电商公司的数据分析场景。原来分析师每天要花 2-3 小时做日报从数据库拉数据、算指标、做图表、写结论。需求是用自然语言描述分析需求Agent 自动生成 SQL、执行查询、生成图表、输出分析报告。这个场景比客服复杂的地方在于它需要 Agent 理解数据库结构、生成正确的 SQL、处理查询结果、还要用自然语言解释数据。而且数据分析对准确性要求极高SQL 写错一个字段结果就完全错了。3.2 技术选型与架构设计技术栈是LangChain SQL Agent PostgreSQL Matplotlib。LangChain 有现成的 SQL Agent但我做了大量定制。核心架构是Schema 理解层把数据库的表结构、字段含义、常用查询模式整理成 Agent 能理解的格式SQL 生成层根据自然语言生成 SQL并做语法校验执行层执行 SQL处理异常可视化层根据数据类型自动选择图表类型解释层用自然语言解释查询结果这里最关键的是 Schema 理解层。我一开始直接把CREATE TABLE语句丢给 Agent效果很差因为 Agent 不知道字段的业务含义。后来我建了一个“数据字典”每个字段都有中文描述、示例值、常见用法。比如order_status字段我标注了“订单状态1待付款2已付款3已发货4已完成5已取消”。这样 Agent 生成 SQL 的准确率从 60% 提升到 88%。3.3 实操步骤与关键配置第一步构建数据字典。这是最耗时但最值得的步骤。我用了一个 YAML 文件来描述每个表orders: description: 订单表记录所有订单信息 fields: order_id: type: bigint description: 订单唯一标识 examples: [10001, 10002] order_status: type: int description: 订单状态 enum: 1: 待付款 2: 已付款 3: 已发货 4: 已完成 5: 已取消第二步设置 SQL 校验规则。Agent 生成的 SQL 不能直接执行要先过三道校验语法校验用sqlparse库、权限校验只允许 SELECT、性能校验预估扫描行数超过阈值就拒绝。这三道校验拦住过好几次危险操作有次 Agent 生成了一个没有 WHERE 条件的全表扫描被性能校验拦下来了。第三步设计图表选择逻辑。不是所有数据都适合画图。我的规则是时间序列用折线图分类对比用柱状图占比用饼图单值用数字卡片。Agent 根据查询结果的字段类型和数量自动选择。第四步生成分析报告。报告结构是固定的核心结论 数据支撑 异常提示 建议。比如“今日 GMV 为 125 万环比增长 8%主要来自华东地区。注意退货率 3.2%高于近 7 天均值 2.1%建议关注。”3.4 踩坑记录与优化心得第一个坑Agent 会“编造”字段名。有次它生成了一个customer_age字段但数据库里根本没有这个字段。解决办法是在 prompt 里明确列出所有可用字段并加上“只能使用以下字段不得编造”。第二个坑日期处理容易出错。用户说“上周”Agent 可能理解成“过去 7 天”或“上一个自然周”。我在 prompt 里明确定义了时间词汇的映射关系比如“上周”“上一个完整自然周周一到周日”。第三个坑大结果集的处理。有次查询返回了 10 万行数据Agent 试图全部塞进 prompt 里做分析直接超 token 限制。解决办法是加一个结果集限制超过 1000 行就先做聚合或者只取前 100 行做样本分析。提示数据分析 Agent 的核心不是“能查”而是“查得对”。Schema 描述的质量直接决定 SQL 的准确率这一步不能偷懒。4. 案例三多 Agent 协作的竞品调研系统4.1 场景描述与核心需求这个案例是我做过的最复杂的 Agent 项目。需求是给定一个竞品名称自动完成信息收集、功能对比、定价分析、用户评价汇总、生成调研报告。原来一个分析师做一份竞品调研要 2-3 天现在希望压缩到 30 分钟以内。这个场景的难点在于它需要多个不同能力的 Agent 协作有的负责搜索有的负责抓取有的负责分析有的负责写作。而且这些 Agent 之间需要传递信息、协调进度、处理依赖关系。4.2 技术选型与架构设计技术栈是AutoGen Playwright GPT-4。AutoGen 是微软开源的多 Agent 框架它的GroupChat机制很适合这种需要多个 Agent 讨论协作的场景。我设计了四个 AgentResearcher Agent负责搜索和收集信息调用搜索引擎和网页抓取工具Analyst Agent负责分析收集到的信息提取关键功能和定价Critic Agent负责质疑和验证 Analyst 的结论找出逻辑漏洞Writer Agent负责整合所有信息生成最终报告架构上用的是“主管 工人”模式。Researcher 是主管负责拆解任务和分配工作。Analyst、Critic、Writer 是工人各自负责自己的领域。主管会根据任务进度动态调整比如发现某个功能信息缺失会重新派 Researcher 去补充。4.3 实操步骤与关键配置第一步定义 Agent 的角色和职责。每个 Agent 的 system prompt 要写得非常具体包括它的能力边界、输出格式、协作规则。比如 Researcher 的 prompt 里明确写了“你只负责收集信息不做分析不写报告。收集到的信息必须包含来源 URL 和抓取时间。”第二步设置协作协议。AutoGen 的 GroupChat 需要一个speaker_selection_method我选的是auto让 LLM 自己决定下一个发言的 Agent。但实测下来auto有时候会陷入两个 Agent 互相推诿的死循环。后来我改成了round_robin加人工干预在关键节点手动指定下一个 Agent。第三步设计信息传递格式。Agent 之间传递的信息必须是结构化的我用的是 JSON。比如 Researcher 传给 Analyst 的信息格式是{ competitor: 竞品名称, features: [ {name: 功能名, description: 描述, source: URL} ], pricing: [ {plan: 套餐名, price: 价格, source: URL} ], reviews: [ {platform: 平台, rating: 评分, summary: 摘要, source: URL} ] }第四步设置终止条件。多 Agent 协作最大的问题是“什么时候停”。我设了三个终止条件一是 Writer 输出了完整报告二是对话轮数超过 30 轮三是连续 3 轮没有新的有效信息。满足任一条件就终止。4.4 踩坑记录与优化心得第一个坑Agent 之间会“踢皮球”。Researcher 说“这个信息 Analyst 应该能分析出来”Analyst 说“这个信息 Researcher 没给全”来回好几轮。解决办法是给每个 Agent 明确的能力边界并在 prompt 里加上“如果信息不足直接说明缺少什么不要假设其他 Agent 会补充”。第二个坑成本失控。多 Agent 协作的 token 消耗是单 Agent 的 5-10 倍。有次一个调研任务跑了 50 轮对话花了 8 美元。后来我加了两个优化一是让 Agent 在传递信息时只传关键内容不传全文二是设置每轮对话的 token 上限。第三个坑Critic Agent 过于“杠精”。它会对每个结论都提出质疑导致进度停滞。后来我在 prompt 里加了“只对关键结论提出质疑且必须给出具体的验证方法不能只说‘我不确定’”。提示多 Agent 协作不是 Agent 越多越好。我试过 6 个 Agent效果反而不如 4 个。每个 Agent 都应该有明确的、不可替代的职责。5. 案例四代码审查与自动修复 Agent5.1 场景描述与核心需求这个案例来自一个开发团队的真实需求。他们每周有 50-80 个 Pull Request代码审查是瓶颈平均每个 PR 要等 4 小时才能得到第一轮反馈。需求是Agent 自动审查代码找出潜在 Bug、安全漏洞、代码风格问题并给出修复建议简单的直接生成修复代码。这个场景的难点在于代码审查需要深度理解代码逻辑而且不同语言、不同框架的审查规则差异很大。另外Agent 的修复建议必须准确不能引入新 Bug。5.2 技术选型与架构设计技术栈是LangChain Tree-sitter GPT-4。Tree-sitter 用来做代码解析把代码转成 AST抽象语法树这样 Agent 能理解代码结构而不是只看文本。架构分三层解析层用 Tree-sitter 解析代码提取函数、类、变量、调用关系审查层Agent 根据解析结果和审查规则找出问题修复层对简单问题直接生成修复代码复杂问题只给建议审查规则我分成了三类安全类SQL 注入、XSS、硬编码密钥、逻辑类空指针、边界条件、资源泄漏、风格类命名规范、注释缺失、函数过长。安全类和逻辑类用 Agent 审查风格类用静态分析工具如 ESLint、Pylint就够了不需要浪费 token。5.3 实操步骤与关键配置第一步构建代码解析管道。用 Tree-sitter 把代码解析成 AST然后提取关键信息函数签名、参数类型、返回值、调用的外部函数、异常处理。这些信息会作为 Agent 审查的上下文。第二步设计审查 prompt。这里的关键是给 Agent 提供足够的上下文。我试过只给 diff效果很差因为 Agent 看不到完整的函数逻辑。后来改成给完整的文件内容 diff准确率提升明显。第三步设置修复的置信度阈值。Agent 对每个问题会输出一个修复建议和置信度。置信度高于 0.9 的直接生成修复代码0.7-0.9 的只给建议低于 0.7 的只标记问题。这个阈值是用历史 PR 数据调出来的。第四步集成到 CI/CD 流程。Agent 审查作为 GitHub Action 的一个步骤PR 创建时自动触发。审查结果以评论形式贴在 PR 上开发者可以直接看到问题位置和修复建议。5.4 踩坑记录与优化心得第一个坑Agent 会“过度审查”。有次它把一个正常的try-catch标记为“异常处理过于宽泛”建议改成捕获具体异常。但实际上那个场景就是需要捕获所有异常。解决办法是在 prompt 里加上“如果代码有注释说明原因尊重开发者的选择”。第二个坑跨文件依赖问题。Agent 审查单个文件时看不到其他文件的定义容易误判。比如它看到一个函数调用但不知道这个函数在其他文件里已经做了参数校验。解决办法是把相关文件的接口定义也作为上下文传给 Agent。第三个坑修复代码引入新 Bug。有次 Agent 把一个改成但那个场景下是故意的需要类型转换。后来我加了一个规则所有修复代码必须通过单元测试才能提交。如果测试失败就只给建议不自动修复。提示代码审查 Agent 的定位应该是“辅助”而不是“替代”。它负责找出明显问题最终判断权还是在开发者手里。6. 案例五个人知识库问答 Agent6.1 场景描述与核心需求这个案例是我自己做的用来管理我的个人知识库。我有大概 2000 多篇笔记、文档、网页剪藏分散在 Obsidian、Notion、本地文件夹里。需求是用自然语言提问Agent 从知识库里找到相关内容整合成答案并标注来源。这个场景的难点在于知识库的内容是非结构化的而且数量大不可能全部塞进 prompt。需要一套高效的检索机制还要处理不同来源、不同格式的文档。6.2 技术选型与架构设计技术栈是LangChain ChromaDB GPT-4 Obsidian API。ChromaDB 用来做向量存储把文档转成 embedding 存进去查询时做相似度检索。架构分四层索引层定期扫描知识库把文档切块、生成 embedding、存入 ChromaDB检索层根据问题检索最相关的文档块重排层对检索结果做重排序把最相关的排在前面生成层Agent 根据检索结果生成答案并标注来源这里的关键设计是切块策略。我试过固定长度切块每 500 字一块效果一般因为会把一个完整的观点切断。后来改成按语义切块用 LLM 判断段落边界把相关的内容放在一起。切块质量提升后检索准确率从 65% 提升到 82%。6.3 实操步骤与关键配置第一步文档预处理。不同来源的文档格式不同需要统一转成 Markdown。Obsidian 的笔记直接读Notion 的用 API 导出网页剪藏用 Readability 提取正文。预处理还包括去除页眉页脚、广告、导航等噪音。第二步语义切块。我用了一个简单的策略先按标题切分如果某个章节超过 800 字再按段落切分。每个块保留 100 字的上下文重叠避免信息断裂。第三步生成 embedding。我用的是 OpenAI 的text-embedding-3-small性价比高。2000 篇文档大概生成了 15000 个块embedding 成本不到 1 美元。第四步检索与重排。检索时先取 top 20 个相关块然后用一个小的 LLM 做重排选出最相关的 5 个块。重排这一步很关键能把准确率提升 15% 左右。第五步生成答案。Agent 的 prompt 里明确要求“只根据提供的文档内容回答如果文档中没有相关信息直接说不知道不要编造”。答案末尾要列出引用的文档来源。6.4 踩坑记录与优化心得第一个坑检索不到“同义”内容。我问“怎么优化 Python 性能”但文档里写的是“Python 加速技巧”向量检索没匹配上。解决办法是加一层“查询扩展”先用 LLM 把问题改写成 3-5 个不同表述分别检索然后合并结果。第二个坑答案过于冗长。Agent 会把检索到的所有内容都塞进答案里导致回答很长但重点不突出。后来我在 prompt 里加了“答案控制在 300 字以内只保留最核心的信息”。第三个坑来源标注不准确。有次 Agent 标注的来源是文档 A但实际内容来自文档 B。原因是检索结果里有多个相似文档Agent 搞混了。解决办法是给每个检索结果编号Agent 引用时必须用编号最后再把编号映射回文档路径。提示个人知识库 Agent 的核心价值是“找到你忘了自己存过的东西”。检索质量比生成质量更重要。7. 案例六自动化测试用例生成 Agent7.1 场景描述与核心需求最后一个案例来自一个测试团队。他们的痛点是每次需求变更都要手动更新测试用例耗时且容易遗漏。需求是根据需求文档和代码变更Agent 自动生成或更新测试用例覆盖正常流程、边界条件、异常场景。这个场景的难点在于测试用例需要覆盖各种边界条件而 Agent 容易只生成“正常路径”的用例。另外生成的测试用例要能直接运行不能只是伪代码。7.2 技术选型与架构设计技术栈是LangChain GPT-4 Pytest。Agent 生成的测试用例直接写成 Pytest 格式可以立即运行。架构分三步需求解析Agent 读取需求文档提取功能点和验收标准代码分析Agent 分析代码变更找出受影响的函数和分支用例生成Agent 根据功能点和代码分支生成测试用例这里的关键是分支覆盖分析。Agent 需要分析代码里的所有分支if-else、try-catch、循环确保每个分支都有对应的测试用例。我用了一个简单的策略先用静态分析工具找出所有分支然后让 Agent 为每个分支生成至少一个用例。7.3 实操步骤与关键配置第一步需求解析。Agent 读取需求文档提取出功能点列表和验收标准。比如“用户登录功能”的验收标准是“正确密码登录成功、错误密码登录失败、账号锁定后无法登录”。第二步代码分支分析。用 Python 的ast模块分析代码找出所有分支点。比如一个登录函数有 5 个分支密码正确、密码错误、账号不存在、账号锁定、账号过期。第三步生成测试用例。Agent 根据功能点和分支生成 Pytest 测试用例。每个用例包含测试名称、前置条件、输入、预期输出、断言。def test_login_with_correct_password(): # 前置条件账号存在且未锁定 user create_test_user(passwordcorrect) # 执行 result login(user.username, correct) # 断言 assert result.success is True assert result.token is not None def test_login_with_wrong_password(): user create_test_user(passwordcorrect) result login(user.username, wrong) assert result.success is False assert result.error_code INVALID_PASSWORD第四步运行与验证。生成的测试用例自动运行如果失败Agent 会分析失败原因判断是测试用例写错了还是代码有 Bug。7.4 踩坑记录与优化心得第一个坑Agent 生成的测试用例“太理想”。它只生成正常路径的用例不生成边界条件。比如测试一个接受 1-100 的函数它只测 50不测 0、1、100、101。解决办法是在 prompt 里明确要求“必须包含边界值最小值、最大值、最小值-1、最大值1”。第二个坑测试数据硬编码。Agent 生成的用例里直接写了usernametest_user但数据库里没有这个用户。后来我加了一个conftest.py提供测试数据的 fixtureAgent 生成的用例必须使用 fixture。第三个坑测试用例之间互相影响。有次一个用例修改了全局状态导致后面的用例失败。解决办法是在每个用例前后加 setup 和 teardown确保测试隔离。提示测试用例生成 Agent 的价值不在于“生成”而在于“覆盖”。它应该帮你发现那些你没想到的边界条件。8. 六个案例的横向对比与选型建议把六个案例放在一起看能发现一些规律。我整理了一个对比表案例复杂度核心工具关键挑战适合团队客服工单L1-L2LangChain分类准确率有客服团队的 SaaS数据分析L2SQL AgentSchema 理解有数据团队的公司竞品调研L3AutoGen多 Agent 协作市场/战略团队代码审查L2Tree-sitter上下文理解开发团队知识库问答L1-L2ChromaDB检索质量个人/小团队测试生成L2Pytest边界覆盖测试团队选型建议很简单从 L1 开始不要一上来就做 L3。我见过太多团队一开始就想做多 Agent 协作结果连单 Agent 的工具调用都没调通。先把一个简单的场景做扎实积累经验再逐步增加复杂度。另外不要为了用 Agent 而用 Agent。有些场景用传统的规则引擎或静态分析工具就够了不需要 LLM。比如代码风格检查ESLint 比 Agent 快 100 倍还免费。Agent 应该用在那些需要“理解”和“判断”的场景。9. 实操中总结的通用避坑指南最后分享一些跨场景的通用经验这些都是我踩过坑之后总结出来的。第一prompt 里一定要有“不知道”的选项。很多 Agent 的 prompt 只告诉它“要回答”没告诉它“不知道就说不知道”。结果 Agent 遇到不会的问题就编。加上“如果信息不足直接说不知道”之后幻觉问题减少了一大半。第二工具调用要有超时和重试。Agent 调用外部工具搜索、数据库、API时网络抖动是常态。我一开始没设超时有次一个搜索请求卡了 30 秒整个 Agent 流程都堵住了。后来加了 5 秒超时和 2 次重试稳定性大幅提升。第三日志要记全。Agent 的决策过程是黑盒出问题时如果没日志根本不知道它为什么做了某个决定。我现在的做法是每次 LLM 调用都记录输入、输出、token 数、耗时每次工具调用都记录参数、结果、耗时。这些日志在排查问题时非常有用。第四成本要监控。Agent 的 token 消耗很容易失控。我见过一个团队一个 Agent 任务跑了 20 美元因为他们没设 token 上限。建议给每个任务设一个 token 预算超了就终止。第五人工兜底不能省。无论 Agent 多智能总会有它处理不了的情况。客服场景要转人工代码审查要人工确认数据分析要人工复核。Agent 是辅助不是替代。第六评估要持续做。Agent 上线不是终点而是起点。我每周都会跑一次评估集看准确率有没有下降。有次发现分类准确率从 92% 掉到 85%排查后发现是客户新增了一个产品线Agent 没见过相关邮件。补充训练数据后恢复正常。这些经验听起来简单但每一条都是真金白银换来的。希望对你做 Agent 落地有帮助。