我做了两年多的企业级应用研发，最近带团队把一个研发助手性质的 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 项目，我的建议很简单：先花两周把需求、边界和评测体系想清楚，再谈架构和技术方案，这个时间绝对花得值。
