我做了两年多的企业级应用研发最近带团队把一个研发助手性质的 Agent 从概念验证做到了内部大规模使用前后踩了无数坑。这个项目最有意思的地方在于它从需求收集阶段就极其容易跑偏到架构设计时又面临“单 Agent 还是多 Agent”“要不要上编排框架”的反复纠结。这篇文章就把我从需求到架构的完整设计过程、关键决策逻辑、以及实际落地中的经验教训梳理一遍希望能给正在做类似企业研发 Agent 的朋友一些参考。先说清楚这个项目是干什么的。我们要做的不是又一个聊天机器人而是嵌入到企业研发流程里的智能体它能接收产品经理和研发人员用自然语言描述的需求把需求拆成结构化任务辅助生成设计文档、代码变更单、评审意见甚至能主动去调用内部的代码仓库、知识库、工作流系统。它的本质是把“需求”这个模糊的东西通过 Agent 的感知、规划、行动能力变成研发流程里可执行、可追踪、可质量把关的产物。这篇文章适合谁看正在规划企业级 Agent 的架构师和技术负责人被业务方一句话“搞个智能体帮我们提效”砸到头上的人以及准备从 Demo 走向生产环境、想少走弯路的 Agent 开发者。我会把需求分析、架构选型、核心链路、落地排坑这几部分完整展开。1. 先理清需求企业研发 Agent 到底要解决什么问题1.1 别急着写代码需求侧先埋着三个大坑企业里聊 Agent最容易听到的一句话是“这个需求很明确给我搞个智能助手”。但只要你追问五分钟通常会发现对方自己都没想明白要解决什么。我遇到过最典型的情况是有人拿了一个非常具象的诉求过来比如“给「小小工作台」加上 PWA 能力manifest 加 service worker”看起来需求非常清晰但往深层一问真实业务目标其实是“让用户在弱网环境下也能顺畅打开工作台、减少重复下载安装成本”。这两个层面差的不是一星半点——前者是方案后者才是问题。所以我在项目启动时给需求侧定了三条硬规矩第一条区分“现象需求”和“真实需求”。现象需求是用户原话真实需求是要解决的业务问题。就拿 PWA 那个例子来说如果一开始就照着“加 manifest 和 service worker”去做做完了发现用户核心痛点是“每次发布后缓存不更新导致看到旧页面”那就白做了。Agent 的需求分析同样如此业务方说要“自动写代码”真实需求大概率是“减少重复性 CRUD 代码的编写时间”两者对应的 Agent 能力完全不同。第二条研发流程不是一句话就能自动化的。研发过程中有评审、有审批、有跨系统数据流转、有验收标准Agent 想切入必须知道自己在哪个环节、能调用什么系统、哪些动作需要人工确认。很多项目死在“Agent 什么都能干但哪个环节都不敢让它真的干”。第三条效果度量难。写代码的速度可以用行数或工时估算但 Agent 辅助设计、辅助评审的效果很难用单一指标衡量。我们必须从需求阶段就设计好评价方式否则后面做评测时完全无法判断“这版 Agent 是变强了还是变弱了”。1.2 用户画像与目标能力边界需求澄清之后我拉了一个用户清单给不同角色画了画像一线研发最需要的是“少切屏、少查文档、少写重复代码”他们希望 Agent 能帮自己快速理解历史代码、生成单元测试、辅助 Code Review。技术负责人关注“需求拆解后能不能覆盖到技术风险”“代码质量能不能有统一把关”他们更希望 Agent 给出分析结果而不是替代决策。项目经理核心诉求是“需求到任务的追踪”“风险预警”“文档自动沉淀”他们要的是流程提效而不是技术深度。基于用户画像我们把目标能力定了优先级第一梯队是“需求拆解、文档生成、代码辅助、评审辅助”第二梯队才是“自动修复缺陷、自动生成测试用例、CI/CD 联动”。同时非目标范围也在需求阶段确认下来了Agent 不直接合并代码、不自动上线、不绕过审批做任何敏感操作。这个边界必须写在需求文档里因为架构设计时很多决策都依赖这条边界。曾经我们纠结要不要让 Agent 直接改代码并提交 MR后来想明白在企业环境里“提交 MR”这个动作本身就是权限敏感操作Agent 可以做准备动作但最后的触发一定要有人工环节。2. 架构选型单 Agent、编排引擎、还是自研系统2.1 单 Agent 看着简单但企业场景根本撑不住项目刚启动时团队里有人觉得不需要复杂架构直接用一个 LangChain 框架把所有功能堆在一个 ReAct Agent 里就行。我让他先搭一个原型跑了两周就发现问题了第一上下文失控。企业研发任务通常要跨越多个步骤理解需求 → 搜索代码 → 生成方案 → 输出文档 → 调用接口。所有历史信息堆在同一个上下文窗口里token 消耗飞速上涨而且经常出现 Agent 忘记最开始的需求约束、自己前面说了什么的情况。第二工具调用混乱。研发场景要接的工具很多GitLab、Confluence、内部 Wiki、JIRA、日志平台、代码搜索服务。一个 Agent 如果同时掌握几十个工具LLM 在“选择哪个工具”这一步的准确率会明显下降经常用错工具或者传错参数。第三不可控。单 Agent 的思考过程是个黑盒你不知道它下一步要干什么。企业环境里不可控等于不可用。流程中某些环节明明需要人工审批单 Agent 一溜烟全跑完了出了责任事故没人敢兜底。2.2 为什么最终选了“编排引擎 可插拔工具”的架构后来我重新做架构选型对比了三个方向纯 LangChain 链式调用、LangGraph 图编排、自研状态机。纯链式调用的问题在于研发流程不是直线。一个需求进来可能拆出三个子任务并行也可能中途要等人工确认确认之后还要回到原流程继续。链式结构表达不了这种分叉和回环。LangGraph 这类图编排框架的特点是把流程定义成一张有向图节点是 Agent 或普通函数边是流转条件并且内置了检查点、状态管理和人工中断机制。这正好匹配研发流程的天然形态。自研状态机最灵活但成本也最高。我们当时盘了一下人力觉得与其从零写图执行引擎不如站在 LangGraph 肩膀上把精力花在业务节点和工具层的设计上。这就确定了整体方向核心编排用 LangGraph外接一层我们自研的工具注册、权限校验和审计模块。架构分层大概是这样的表现层统一入口Web 端对话界面 企业内部 IM 机器人。编排层LangGraph 定义流程模板比如“需求拆解流程”“代码评审流程”“文档生成流程”每个流程是一张子图。模型层封装了多个 LLM 供应商接口和自研私有化模型接口通过路由策略选择当前任务用哪个模型。工具层所有对外部系统的调用都以“工具”的形式注册每个工具都有名字、描述、入参 JSON Schema、权限标签。数据层向量数据库、关系型数据库、对象存储分别存知识库、业务数据和过程日志。这个架构最大的好处是“流程与能力解耦”。要加一个新场景比如“漏洞修复建议”只需要画一条新图把已有工具节点串起来要接一个新系统写一个工具插件注册进去就行不用改编排逻辑。2.3 模型层、工具层、权限层的边界怎么划这块是我觉得整个架构里最值得讲的部分因为很多 Agent 项目失败就是边界没划清楚。模型层只负责“理解和生成”。LLM 的输入是用户需求 相关上下文 可用的工具清单输出是“下一步动作的结构化表达”调用什么工具、传什么参数或者直接生成一段文本。模型层不直接接触任何外部系统不知道 token 怎么配、权限怎么验。工具层是唯一的“手”。任何外部副作用查代码、写文档、建任务、发通知都必须通过工具函数完成。工具函数内部统一做参数校验、权限校验、调用审计。哪怕 Agent 在幻觉状态下输出一个疑似要删库的工具调用工具层也能用权限标签挡住。权限层独立出来不让 Agent 逻辑里散布权限判断。每个工具定义时就声明需要的权限类型比如“只读”“写入”“审批敏感”。执行时权限引擎根据当前用户身份、Agent 会话上下文、工具权限标签做裁决。这一点让我很放心因为审计需求特别容易追溯这个用户通过这个会话让 Agent 调用了哪个工具传了什么参数返回了什么结果全部有日志。有段时间我们热议一个话题为什么企业级 Agent 搭起来不难、用好却难。我的体会就是边界问题——不是模型不够聪明而是工程上没把“决定权”和“执行权”分开。模型再聪明该有的权限管控、审计追踪、人工确认环节还是省不了。3. 核心链路设计与关键实现3.1 需求输入与清洗从自然语言到结构化任务第 1 章提到业务方常把“方案”当“需求”抛过来所以 Agent 的第一道工序是需求清洗。我设计的第一个节点是“需求解析器”输入是用户原话输出是结构化的 JSON包含以下字段业务目标、约束条件、验收标准、风险点、建议执行路径。为了让 LLM 稳定输出 JSON我定义了一套严格的 Prompt 模板给模型少样本示例。比如用户说“给「小小工作台」加上 PWA 能力”解析器输出的目标写成“提升工作台在弱网和离线场景下的可用性”约束条件里带上“不支持 HTTPS 的环境无法使用 Service Worker需要评估内网访问方式”验收标准是“安装后可离线打开更新后能主动刷新缓存”。这些字段都被后续流程使用尤其是“验收标准”会直接传到最后的验收检查 Agent 那里。这里有个很重要的经验需求清洗环节的输出不能直接进执行链路必须弹出一个确认卡片让用户确认。因为机器理解需求再准也会出错而需求阶段的一字之差到执行阶段就会被无限放大。早期我们省掉确认环节结果 Agent 把“给工作台加离线能力”理解成“做一个独立桌面应用”白折腾了一周后来就把确认环节设置为不可跳过。清洗环节我们额外做了“相关需求联想”。输入“给小小工作台加 PWA”时Agent 会去知识库检索有没有历史方案、有没有同事已经做过类似技术调研、有没有已存在的 Service Worker 公共组件可以复用。这个联想机制很实用企业里大量技术问题其实是重复的只是大家不知道彼此做过。3.2 上下文工程企业知识库怎么接进来才不会被骂研发 Agent 的价值很大程度上取决于它能不能理解企业内部的知识体系。我们做了一个 RAG 检索模块向量数据库存储的是内部技术文档、历史设计文档、代码注释、Wiki 页面、过往的故障复盘报告。第一版我们把所有文档都切片塞进向量库效果很糟。后来总结出三个关键教训切片大小要按文档类型区分。代码文档按函数或类切片长篇幅的设计文档按章节切片不要一刀切固定 500 字。检索要与重排结合。第一轮用向量召回 Top 50再用重排模型选出 Top 5 送进上下文。直接拿 Top 5 很容易漏掉关键信息。企业内部知识的权限问题不是简单过滤关键词而是要在元数据层处理。文档入库时就标记可见范围比如“仅前端组可见”“仅管理员可见”检索时把当前用户身份带进过滤条件。这个不做Agent 就会变成越权通道。上下文拼接也有讲究。我把给 LLM 的上下文分成三块核心需求、检索到的知识片段、执行过程中产生的中间结果。三块用不同的系统标记包裹避免模型混淆来源。曾经遇到过 Agent 把检索到的历史文档里的旧方案当成当前需求来执行就是因为没做来源隔离后来加了提示词和结构标记解决了。另外企业场景还要注意上下文窗口的预算管理。一个复杂需求拆解任务需求原文、检索片段、历史记录加起来很容易超过 2 万 token。我设计了上下文压缩策略对话历史超过阈值时用 LLM 把旧的内容总结成摘要只保留最近几轮完整内容摘要再作为新上下文的背景。这样既保留了关键信息又不会无限膨胀。3.3 工具调用与生成动作的规范设计工具是 Agent 接触真实世界的桥梁设计得好不好直接影响可靠性和安全性。我们内部定义了一套工具规范每个工具必须包含名称动词 对象如search_code、create_document、send_review_message描述告诉 LLM 这个工具什么时候用、能干什么、不能干什么入参 JSON Schema字段名、类型、是否必填、枚举值、示例权限标签只读/写入/敏感超时时间和失败策略我给团队的要求是工具描述宁可啰嗦也不要含糊。比如搜索代码的工具描述我会写清楚“支持按文件名、仓库路径、语言类型过滤不支持语义化关键词搜索请先拆解关键词再调用”。因为 LLM 不能“试”工具只能靠描述判断。描述含糊它大概率会用错参数。以“自动生成代码评审意见”这个场景为例实际链路是用户提交 MR 链接Agent 的评审流程被触发。编排图进入第一个节点调用fetch_mr_diff工具拿到变更内容。进入第二个节点调用search_code检索关联的历史代码方便判断本次变更是否破坏了既有逻辑。进入第三个节点把 MR 描述、diff、历史代码三部分送进模型生成评审意见。评审意见以结构化表格输出每条意见包含风险等级、相关文件/行号、问题描述、修改建议。最后进入人工确认节点由拥有评审权限的人来确认意见是否写入 MR 评论。这个流程里第 6 步的人工确认是我坚持留下的。因为“代码评审意见”这种内容哪怕准确率做到 90%剩下 10% 的错误意见如果直接发出去影响的不只是开发者心情还有团队对 Agent 的信任度。机器提供建议人做最终判断这是企业环境里最稳妥的模式。工具调用的失败兜底也非常重要。有一次 Agent 调用知识库搜索服务超时编排流程直接终止用户得到一句“出错啦”。这种体验太业余。后来我给所有工具的失败策略分了级可重试的临时网络超时自动重试 2 次不可重试的参数错误、权限不足进入兜底节点由另一个 Agent 根据失败原因生成一个友好、可操作的错误提示。4. 落地踩坑实录从 Demo 到生产环境要迈过哪些坎4.1 “效果不错”不等于“可靠”评测体系必须前置Demo 阶段大家经常听到“哇它居然能给出这么详细的设计文档”——这种评价在 POC 阶段让人开心但在生产环境毫无意义。真正要回答的问题是给定 100 条真实需求Agent 有多少条能一次跑通并给出可验收的结果有多少条需要人工介入修正有多少条直接跑偏我从第 3 周就开始搭评测集。做法是从历史 JIRA 需求里挑出 20 个任务作为种子用例覆盖需求拆解、代码搜索、文档生成、评审辅助等场景。每个用例必须包含原始输入、期望输出要点、验收标准。之后每次迭代都拿这 20 条用例回归再加每周新增的典型失败用例。评测结果不只算正确率也分三个层级完全正确Agent 的输出可以直接使用、部分正确方向对但细节要改、失败结论错误或流程中断。实际跑下来前期完全正确的比例大约只有四成部分正确占三成失败占三成。迭代两个月后完全正确到了七成以上失败降到一成以内。很多团队不做评测靠“感觉”判断 Agent 又进步了这是非常危险的。LLM 的能力波动很大同一个 Prompt 这周效果好下周换了模型版本效果可能大幅回落。有评测基线在你才能理性判断每一次改动到底值不值得上线。4.2 性能与成本token 消耗算不清预算就失控Agent 项目比传统 API 项目烧钱的地方在于一个任务往往会多次调用 LLM。以“自动生成变更单 代码评审意见”为例拆解需求要调一次检索代码可能要调一次做关键词优化生成评审意见又要调一次单任务 token 可能轻松上万。我建了一个简单的成本模型来估算假设一个知识点文档生成任务要消耗 8000 token 输入、2000 token 输出按当时的模型价格算单任务成本大概是 X 元。公司如果有 1000 个人每天用 5 次这个数字就不是小钱了。控制成本的措施包括对相同或相似请求加缓存。比如同一份 MR 重复请求评审直接返回上一份结果等待期间也不重复计算。能用小模型解决的任务不用大模型。需求意图分类、关键词提取这类轻量任务用一个 7B 级别的私有化模型就够了只有最终内容生成才调用千亿级大模型。长任务拆分让每一步的输入输出尽量精简。我之前遇到过一个离谱情况Agent 把检索出的 20 个文档片段全部塞进上下文一次任务消费了 5 万 token。加上重排和筛选机制后降到 1 万以内。4.3 可观测性与审计让业务方敢用的关键企业内部系统最怕黑盒Agent 尤甚。业务方不敢用一个大模型在内部系统里“乱搞”除非它能证明每一步都是可控、可追溯的。我们的做法是每一次 Agent 执行任务都会生成一份完整的执行轨迹包含以下字段会话 ID、用户、时间戳命中的编排流程版本、模型版本、Prompt 版本每一步工具的调用参数、返回值、耗时中间生成内容摘要人工确认节点的操作记录最终结果链接这套日志不只是为了排查问题还用来做“信任建设”。我们做了一次内部展示把一份 Agent 生成的设计文档的执行轨迹完整摊开给业务负责人看对方看完之后的态度转变很明显从“这个靠谱吗”变成“哦每一步都是能追溯的那可以试试”。可观测性还帮我定位了很多问题比如某个流程总是慢一查是某工具响应经常超时某个模型输出质量波动一查是供应商那边对不同型号模型做了调整。没有日志这些问题根本无从下手。4.4 组织落地别指望一步到位灰度永远比革命稳技术层面的坑容易踩组织层面的坑更隐蔽。我们早期想直接让 Agent 面向全公司开放结果收到的反馈两极分化愿意尝鲜的人惊叹效率提升保守派的人完全不用还有一小部分人担心“这玩意是不是在监视我”。后来调整了策略先对敏感度低的场景开放比如文档生成、需求拆解辅助这类任务不直接产生代码变更风险低用户也容易接受。代码评审辅助和自动生成变更单则只开放给种子用户——每个研发小组选一两个技术骨干试用让他们成为内部倡导者。种子用户的反馈极其宝贵很多真实场景里才发现的问题都是他们提的。还有一点特别重要给 Agent 加一个“采纳率”统计。用户在对话里点“采纳”还是“忽略”每天统计一次。一开始我们看到“忽略”率很高会焦虑但数据反映出来的问题才是有价值的要么结果质量不行要么结果形式不符合用户习惯。把这两件事分开分析再针对性迭代比闭门造车好用得多。我个人最大的感受是企业研发 Agent 不是单纯的技术项目更像是一个“组织学习”的过程。团队要学会定义问题架构师要习惯画流程图业务方要学会提需求而 Agent 本身只是把所有环节串起来的载体。这个过程中我踩过的最大的坑就是一开始太执着于“把 Agent 做好”而忽略了“把需求问清楚”。如果你现在也准备启动一个企业级研发 Agent 项目我的建议很简单先花两周把需求、边界和评测体系想清楚再谈架构和技术方案这个时间绝对花得值。
