企业官网建设流程全解析

把一个 Agent 从 Demo 推到生产环境，中间隔着的往往不是模型能力，而是三个工程问题：场景抽象是否清晰、任务拆解是否合理、验证方法是否匹配。

Demo 阶段验证的是“Agent 能不能回答一个问题”。真实业务要问的是“Agent 能不能在一个有边界、有状态、有异常处理的场景里稳定完成任务”。这两件事之间的距离，远比想象中大。

一个典型的内部知识助手项目，前端 Next.js，后端 FastAPI，LangGraph 做编排，向量库选 pgvector。Demo 阶段一切顺利——用户问“年假政策是什么”，Agent 能准确检索文档并给出带引用的回答。上线第一周，问题开始冒出来：有人问“我这种情况能不能休年假”，Agent 把政策原文丢了过来，没做任何条件判断；有人追问“那我呢”，Agent 完全不知道“我”指的是谁，上下文丢了；最离谱的一次，用户输入了跟公司政策完全无关的行业法规问题，Agent 也硬着头皮答了，还编了一条引用。

这类问题并非个例。它们指向同一个结论：Agent 项目的落地瓶颈，很少在模型本身，而在场景、拆解与验证这三个工程环节。

一、业务场景抽象：先划边界，再谈能力
1.1 窄而深，是 Agent 落地的第一条铁律
在 Agent 落地的早期阶段，窄而深永远比广而浅更安全。某电商公司部署客服 Agent 时，最初让它同时处理退货、物流查询、商品推荐和投诉处理四类任务，前两周正确率不到 60%，用户投诉量反而比人工客服期间更高。后来把任务范围收缩到“仅处理物流查询”这一件事，正确率飙升到 92%。

这个案例的启示很直接：场景抽象的第一步不是“Agent 能做什么”，而是“Agent 不能做什么”。企业级 Agent 设计方法论中有一个适用性评估矩阵，从任务复杂度和不确定性两个维度来判断场景是否适合 Agent：高复杂度、高不确定性的任务是最佳场景，而低复杂度、低不确定性的任务用传统规则引擎或 RPA 就够了。

1.2 用“输入→处理→输出→验收”定义场景闭环
在写第一行 Agent 代码之前，一个有效的做法是先填完一套场景抽象模板：

输入：用户会以什么形式、什么频率、在什么上下文里提出请求？

处理：Agent 需要做几步推理？涉及哪些工具调用？哪些步骤必须人工确认？

输出：交付物是什么格式？是文本回答、结构化数据、还是文件操作？

验收：怎么判断这次任务成功了？验收标准由谁来定？

这套模板的核心是把模糊的需求变成可验证的链路。比如“政策查询”场景可以被定义为：输入是自然语言问题，处理是“意图分类→文档检索→条件判断→回答生成”，输出是带引用来源的文本，验收标准是“回答内容必须来自政策文档原文且包含引用，超出范围的必须转接人工”。

1.3 Agentic Automation Canvas：一个值得参考的结构化框架
在场景抽象的方法论层面，Agentic Automation Canvas（AAC）提供了比通用模板更系统的框架。AAC 借鉴了商业模式画布的思路，用六个维度来结构化地定义一个 Agent 自动化项目：定义与范围、用户期望与量化收益指标、开发者可行性评估、治理分级、数据访问与敏感性、预期成果。

AAC 的核心创新在于把“用户期望”和“开发者可行性”放在同一张画布上对比，从而在项目启动前就暴露期望落差。很多 Agent 项目失败不是因为技术做不出来，而是因为用户期望和实际能力之间的差距没有被提前对齐。业务方最初期望 Agent“像人一样理解所有问题”，但实际能做到的是“在明确边界内准确回答”。这个落差如果在项目启动时没有说清楚，后面所有的迭代都会围绕错误的期望打转。

二、任务拆解：从静态流水线到动态规划
2.1 静态拆解的适用边界
项目初期，任务拆解方式往往是静态的：用户问政策问题 → 检索文档 → 生成回答。三步固定，Prompt Chain 直连。

这种方法在请求模式可预测时工作得很好。企业级 Agent 设计指南中也建议，在任务确定性较高时使用“Plan-Execute”模式或无规划模式，减少不必要的协调开销。

但很快问题会暴露。有些问题只需要查一个文档就能回答，有些需要跨多个文档综合判断，有些需要先做条件匹配（比如“我入职不满一年，能不能休年假”）再查对应条款。一套固定的三步流水线，面对简单问题会过度工程化，面对复杂问题又覆盖不了。

2.2 动态分解：让元代理先分析再执行
微软 Agent Framework 中有一个值得借鉴的设计：元代理规划器（Meta-Agent Planner）。它是一个专门用于分析的 Agent，接收完整任务描述后输出结构化的分解计划，但它自己不执行任务。

静态分解和动态分解的适用场景有明确区分：

分解类型 适用场景 优势 局限
静态 任务模式统一、流程明确 性能可预测、易调试 不灵活，无法适应任务差异
动态 复杂度多变、需求持续演进 适应实际需求，处理边缘情况 协调成本高，可预测性降低
一种务实的混合方案是：大部分常规查询走静态三步流程，但当元代理检测到任务复杂度超过阈值时，切换到动态分解模式，由规划器先生成执行计划再逐步执行。

2.3 拆解粒度：平衡协调开销与执行精度
任务拆解到什么粒度合适？有研究对比了两种方案：在 30 个多步数据科学任务的实时压力测试中，将工具按专家阶段分区（每阶段不超过 15 个工具）的架构实现了 93%-100% 的端到端完成率，而扁平化的单一工具目录只有 47%-77%。

但粒度过细也有代价。拆成太多子任务会增加 Agent 之间的协调开销，每个交接点都可能丢失上下文。一个常见的坑是：把政策查询拆成了“分类→检索→条件匹配→格式化→引用检查”五个独立 Agent 步骤，结果响应延迟从 3 秒涨到了 12 秒，而且中间步骤的状态传递经常出问题。后来合并为三步后，延迟和稳定性都明显改善。

一个实用的判断标准是：如果一个子任务的失败不会影响后续子任务的语义正确性，就可以拆开；如果后续任务必须依赖前一步的完整上下文，就保持在一起。

2.4 工具接口设计：让概率系统接上确定性接口
Agent 调用工具，本质上是在把一个概率系统的输出接到一个确定性接口上。检索工具最初可能只返回一个字符串——匹配到的文档内容。但实际运行中，模型需要区分五种情况：检索到了正确内容、检索结果为空、查询参数不标准、接口超时、用户没有权限访问该文档。

只返回字符串，模型分不清这五种情况，只能靠猜。更好的做法是把工具返回结构改为带 Status、data、message、retryable、nextAction 五个字段的结构体，并强制在工具层做参数校验和权限检查。

这里有一条糙理但很准的原则：不要指望 Prompt 保证安全，接口必须能挡住错误。 工具调用流程应当钉死为：先权限检查，再参数校验，再执行查询，最后处理空结果和异常。这套流程由代码强制执行，不依赖模型的自觉。

三、验证思路：别用测确定性软件的方法测 Agent
3.1 单元测试的范式陷阱
最初的直觉做法是：写单元测试，断言 Agent 的输出里包含预期关键词。上线后才发现，测试覆盖率 82%、所有 case 绿灯，但 Agent 在实际使用中会在多轮对话里陷入逻辑死循环——而没有任何一条测试在验证这件事。

传统软件测试的底层假设是“相同输入得到相同输出”。这个假设在 Agent 身上完全不成立：LLM 输出有随机性，外部工具状态随时变化，执行路径由 Agent 自主决定。断言脚本充其量只是在验证“这个输出里有没有某个字符串”，根本碰不到 Agent 真正的行为边界。

3.2 从验证输出转向评估行为链
评估体系重建的核心思路是：把“任务成功”拆成三个层次：

第一层，能完成任务——Agent 是否在有限步骤内得出了正确答案？
第二层，没搞坏其他流程——Agent 是否在调用工具时引入了副作用？是否触碰了不该触碰的资源？
第三层，边界情况下行为合理——当信息不足时，Agent 是主动澄清还是编造？当超出能力范围时，是转人工还是硬答？

基于这三层标准，可以建立一套行为回归集，专门记录历史上出现过的异常行为模式：死循环、无限追问、跨轮遗忘、工具调用错误累积。每次修改 Prompt 或切换模型后，全套回归跑一遍，不到 4 小时就能完成验证。

3.3 LLM-as-Judge 的正确用法：加一道人工校准门
评估体系可以引入 LLM-as-Judge 来做自动化评分，但需要加一道关键的人工校准门。LLM 评分器有一个致命偏向：它倾向于给长输出打高分，跟实际质量相关性很弱。如果不校准，Agent 会“学会”写更长的回答来提高评分，但长回答未必更准确。

校准方法是：每两周抽 100 条评估结果，人工重新打一遍分，跟 LLM 评分做 diff。一旦偏差超过 15%，就重新对齐评分标准。这道校准门的成本不高（两周 100 条），但它是保证评分可信度的底线。

更前沿的方向是 Agent-as-a-Judge——让评审本身也成为一个能调用工具、多轮调查的 Agent。实验表明，Agent-as-a-Judge 与人类专家评估的一致率约为 90%，显著优于 LLM-as-a-Judge 约 70% 的一致率。

3.4 评估数据集的冷启动策略
评估数据集从哪来？一个可复用的策略分三步：

第一步，从场景定义直接生成。每个业务场景的“输入→处理→输出→验收”定义本身就对应一组测试用例。比如“政策查询”场景下，围绕“员工有多少病假”这样的典型问题，写好预期响应和接受标准。

第二步，从生产环境回流。上线后用户实际提出的问题、触发的失败案例，自动进入评估数据集。小红书在 AgentOps 实践中也采用了类似机制，从线上 Good/Bad Case 自动回流到评测数据集，形成迭代与验证的正循环。

第三步，用合成数据补边界。使用 LLaDAR 等工具从知识源文档生成对比性测试数据集，专门覆盖边界情况——比如模糊表述、否定式提问、多条件组合。

四、全栈工程中容易被忽视的三件事
4.1 上下文不是聊天记录，是运行时状态
最早的上下文设计往往是简单地把所有历史消息塞进 Prompt。短期有效，但很快会出现三个问题：状态丢失（关键信息在历史里不在当前输入里）、状态冲突（系统限制查最近 30 天的数据，历史里却躺着去年的）、重点稀释（工具返回、检索片段、执行日志全塞进去，模型反而找不到那条关键约束）。

正确做法是维护一个明确的查询状态对象，类似 Java 里的领域对象。用户说“那杭州呢”，系统只更新城市这一个字段，不重建整个对象，也不让模型随意覆盖所有字段。一句话总结：程序维护状态，模型解析意图。

4.2 成本控制：Token 消耗需要专门设计
上线第一个月的账单可能超预算数倍。排查后往往发现，最大的 Token 消耗不在模型推理，而在上下文重复传输。每轮对话都把全部历史消息塞进请求，而其中大量内容与当前问题无关。

参考 Uber 的 Agent 降本方法论，有两个关键策略：分层路由（规划用大模型，执行用小模型）和工具菜单修剪（根据当前用户意图动态精简可用工具列表）。工具声明本身也是 Token 成本，一个长工具菜单不仅贵，还会降低模型选择的准确率。实施后千次请求成本可降低约 30%。

4.3 可观测性不是可选项
89% 的受访者已经为 Agent 实施了可观测性方案，但评估的采用率仅为 52%。这意味着大量团队能看到 Agent“做了什么”，但不知道“做得对不对”。

可观测性体系应聚焦两个维度：指标（延迟、Token 消耗、工具调用次数、错误率）和追踪（从用户输入到最终输出的完整执行链路）。在追踪层面，可以使用 agent-xray 和 agent-failure-debugger 等工具来重建 Agent 在每个决策点“看到了什么”，这比单纯看日志有效得多——因为很多行为失败根本不产生错误日志。

写在最后
Agent 项目从 Demo 到上线，最大的教训不在技术细节上，而在两个认知层面的转变。

第一个转变是：从“Agent 能做什么”转向“Agent 在什么边界内做什么”。 场景抽象的本质不是描述能力，而是定义边界。窄场景能跑通闭环建立信心，比广场景但处处出错有价值得多。

第二个转变是：验证的目标不是“结果可接受”，而是“行为可理解”。 一个至今仍在争论的问题是：Agent 测试的终极目标，是保证行为可预测，还是保证结果可接受？如果是前者，测试成本会是传统软件的 5 到 10 倍；如果是后者，“可接受”由谁来定义？更务实的倾向是后者，但需要把“可接受”的粒度定义得足够细，细到每次行为回归的偏差都能被归因到具体的组件。

Agent 项目落地的本质是一个管理问题，其次才是一个技术问题。那些效果好的项目，不是因为用了更先进的框架或模型，而是因为把场景定义清楚了、把边界划明确了、把验证标准量化了。技术是手段，这些才是底座。