企业官网建设流程全解析

1. 剥开迷雾：为什么现在必须重新审视 AI Agents

过去大半年，几乎每一场技术分享、每一篇行业分析都在谈 AI Agents。但如果你真正动手搭过几个能跑通业务闭环的 Agent 系统，就会发现一个尴尬的事实：演示视频里那些行云流水的多步推理、工具调用、自主决策，到了真实生产环境里，往往连一个简单的跨系统数据同步都搞不定。问题出在哪？不是模型不够强，而是大多数人对 Agent 的理解还停留在“给大模型加几个工具函数”的层面，忽略了它本质上是一套分布式任务编排系统。

我所在的团队从去年下半年开始，陆续在客服工单自动分类、内部知识库问答、运维告警根因分析三个场景里落地了 Agent 方案。踩过的坑包括但不限于：工具调用超时导致整个任务链崩溃、多轮对话中上下文窗口爆炸、不同模型对同一份工具描述的理解偏差超过 40%、以及最致命的——当业务方问“这个决策为什么这么下”时，我们拿不出可追溯的推理链路。这些经历让我意识到，市面上大量关于 Agent 的讨论，要么在讲科幻式的通用智能，要么在堆砌框架名词，真正从工程落地视角拆解架构选型、状态管理、错误恢复的内容少得可怜。

这篇文章就是想把过去一年在真实项目里积累的架构决策逻辑、参数调优经验、以及那些文档里不会写的避坑技巧，系统地梳理一遍。我不会教你“三行代码实现一个 Agent”这种标题党内容，而是聚焦于：当你需要让 Agent 在生产环境里稳定处理有状态、多步骤、跨系统的任务时，工作流引擎该怎么设计、工具层怎么抽象、状态怎么持久化、失败怎么恢复。适合已经有基础大模型调用经验，正准备把 Agent 从 Demo 推向生产的工程师阅读。如果你还在纠结用哪个框架写第一个 Hello World，这篇文章的部分内容可能偏深，但架构思路依然有参考价值。

2. 核心架构选型：为什么我最终放弃了纯 ReAct 模式

2.1 ReAct 的诱惑与生产环境的残酷现实

刚开始接触 Agent 时，几乎所有人都会被 ReAct（Reasoning + Acting）模式的简洁优雅所吸引。它的核心逻辑非常直观：让模型先输出思考过程，再决定调用哪个工具，拿到结果后继续思考，循环直到任务完成。用 LangChain 或类似框架，几十行代码就能跑通一个能查天气、算数学、搜网页的 Agent。我在内部技术分享会上第一次演示这个模式时，同事们的反应都是“这东西要火”。

但当我们把同样的模式套用到“自动处理客户退款申请”这个真实业务流时，问题立刻暴露了。这个任务需要：读取工单系统里的订单号、调用订单服务验证购买时间、查询退款政策库判断是否符合条件、计算退款金额、调用支付网关发起退款、最后更新工单状态并通知客户。在 ReAct 模式下，模型每一步都要重新阅读完整的对话历史，包括之前所有工具调用的原始返回结果。当处理到第五步时，上下文里已经塞满了 JSON 格式的订单详情、政策文本、支付网关的响应报文，Token 消耗呈指数级增长。更糟糕的是，模型开始“遗忘”早期的关键约束，比如“该订单已超过 30 天退款窗口”这个在第二步就查到的信息，到第五步时被模型忽略了，导致错误地发起了退款。

注意：ReAct 模式在任务步骤超过 5 步、或单步返回数据超过 2000 Token 时，推理准确率会断崖式下跌。这不是模型能力问题，而是注意力机制在长上下文中的固有缺陷。

2.2 工作流引擎的引入：把“思考”和“执行”解耦

痛定思痛后，我们决定把架构从“模型自主循环”改为“工作流引擎驱动”。核心思路是：用确定性的代码逻辑控制任务流转，只在需要语义理解和决策的节点调用模型。具体来说，我们把退款处理流程拆解成一个有向无环图（DAG），每个节点是一个独立的任务单元，节点之间的边定义了流转条件。

这样做的好处立竿见影。首先，上下文管理变得可控。每个节点只接收它需要的输入数据，而不是整个对话历史。比如“计算退款金额”节点只需要订单金额、退款比例、手续费规则三个参数，Token 消耗从原来的 8000+ 降到了 300 左右。其次，错误处理有了明确的边界。如果“调用支付网关”节点失败，工作流引擎可以自动重试三次，或者跳转到“人工审核”节点，而不是让模型在无限循环里反复尝试。最重要的是，整个执行路径变得可追溯、可审计。每一步的输入、输出、耗时、状态都记录在数据库里，业务方随时可以查询“这笔退款为什么被拒绝”，我们只需要把对应节点的执行日志拉出来即可。

2.3 状态机 vs. 事件驱动：两种工作流模型的取舍

在具体实现工作流引擎时，我们面临一个关键选择：用状态机模型还是事件驱动模型。状态机模型把每个任务定义为一个状态，状态之间的转移由明确的规则触发。比如“待验证”状态收到“验证通过”事件后转移到“待计算”状态。这种模型的优势是逻辑清晰、易于调试，特别适合业务流程固定、步骤顺序明确的场景。我们最初的退款流程就是用状态机实现的，用 Python 的transitions库，不到 200 行代码就搞定了核心逻辑。

但很快遇到了瓶颈。当业务方提出“如果客户是 VIP，跳过政策校验直接进入金额计算”这种需求时，状态机的转移矩阵变得异常复杂。更麻烦的是，有些任务需要并行执行，比如同时查询订单详情和用户画像，状态机处理并发分支的能力很弱。于是我们转向了事件驱动模型，用消息队列（RabbitMQ）作为中枢，每个任务单元订阅自己关心的事件，处理完后发布新事件。这种架构的扩展性极强，新增一个“风控校验”节点只需要让它订阅“退款申请创建”事件即可，完全不影响现有流程。

但事件驱动也带来了新的问题：调试困难。一个退款请求可能在队列里流转了七八个节点，每个节点都有自己的日志，排查问题时需要跨多个服务追踪事件链路。我们的解决方案是引入一个全局的trace_id，在每个事件的消息头里携带，所有节点的日志都按这个 ID 聚合。同时用 Jaeger 做分布式追踪，把整个事件流可视化出来。这套组合拳打下来，虽然初期搭建成本比状态机高，但后期维护和扩展的收益远超投入。

3. 工具层设计：Agent 与外部系统交互的工程化实践

3.1 工具描述的质量决定 Agent 的上限

很多人把工具调用失败归咎于模型能力不足，但根据我们的统计，超过 60% 的工具调用错误源于工具描述本身有歧义。举个例子，我们有一个“查询订单状态”的工具，最初的描述是“根据订单号获取订单当前状态”。模型经常把“订单号”和“用户 ID”搞混，因为描述里没有明确说明参数格式。后来我们把描述改成：“根据 18 位数字订单号查询订单状态，返回状态码和状态描述。订单号格式示例：202401150000123456。注意：不要传入用户 ID 或手机号。”错误率立刻从 23% 降到了 4%。

这个经验告诉我们，工具描述不是写给人看的文档，而是写给模型看的提示词。它需要包含：参数的确切格式和示例、返回值的结构说明、以及常见的误用警告。我们内部甚至制定了一个工具描述规范，要求每个工具必须包含“功能一句话概括”、“参数表（名称、类型、格式、示例、是否必填）”、“返回值示例”、“常见错误提示”四个部分。虽然写起来麻烦，但一次投入换来的是后续调用成功率的显著提升。

3.2 工具调用的超时、重试与熔断机制

生产环境里，外部 API 的响应时间是不确定的。我们遇到过支付网关在高峰期响应超过 30 秒的情况，而模型默认的超时设置往往只有 10 秒。如果不做处理，模型会认为工具调用失败，然后尝试重新调用，陷入死循环。我们的解决方案是在工具层统一封装超时和重试逻辑。

具体参数设置上，我们根据工具的重要性和外部系统的 SLA 来定。查询类工具（如查订单、查政策）超时设为 5 秒，重试 2 次，采用指数退避策略（第一次等 1 秒，第二次等 2 秒）。写入类工具（如发起退款、更新工单）超时设为 10 秒，重试 1 次，因为重复写入可能造成数据不一致。如果重试后仍然失败，工具层会返回一个结构化的错误信息，包含错误码、错误描述、以及建议的下一步操作（如“请稍后重试”或“转人工处理”），而不是直接抛异常。

实操心得：重试策略一定要配合幂等性设计。我们在支付网关的调用上加了唯一的request_id，确保即使重试也不会重复扣款。这个细节在 Demo 阶段很容易被忽略，但生产环境里一旦出事就是资损。

3.3 工具返回结果的标准化处理

模型对工具返回结果的解析能力，很大程度上取决于返回数据的结构。我们最初让工具直接返回外部 API 的原始 JSON，结果模型经常被嵌套的字段搞晕。比如订单服务返回的{“data”: {“order_info”: {“status”: 1}}}, 模型需要理解status: 1代表“已支付”。后来我们在工具层加了一个适配器，把原始响应转换成扁平化的、带语义标签的结构：{“order_status”: “已支付”, “order_id”: “202401150000123456”}。这个改动让模型的理解准确率提升了将近 30%。

适配器的另一个作用是裁剪冗余信息。外部 API 经常返回几十个字段，但 Agent 只需要其中三五个。我们把不需要的字段过滤掉，既节省了 Token，也减少了模型被无关信息干扰的可能性。对于必须保留但结构复杂的字段（如商品列表），我们会做摘要处理，只保留名称、数量、单价等关键信息。

4. 状态管理与上下文工程：让 Agent 记住该记住的

4.1 短期记忆与长期记忆的分离

Agent 的“记忆”问题，本质上和人类处理任务时的记忆机制类似。你在处理一个退款申请时，需要记住当前订单号、用户诉求、已执行步骤，这些是短期记忆。但你也需要知道公司的退款政策、历史类似案例的处理结果，这些是长期记忆。把两者混在一起塞进上下文窗口，是导致 Token 爆炸和推理混乱的主要原因。

我们的做法是：短期记忆用结构化状态对象存储，只保留当前任务相关的字段，比如{“order_id”: “...”, “current_step”: “verify_policy”, “retry_count”: 0}。这个对象在每个节点执行时被读取和更新，但不直接全部塞给模型。模型只接收当前节点需要的字段。长期记忆则存储在向量数据库里，通过语义检索按需召回。比如在“判断是否符合退款政策”节点，我们会用订单信息和用户诉求去检索最相关的 3 条政策条款，而不是把整本政策手册都喂给模型。

4.2 上下文窗口的动态管理策略

即使做了记忆分离，某些复杂任务仍然需要较长的上下文。比如处理一个涉及多个商品、多次沟通的售后工单，模型需要理解整个对话历史。我们的策略是滑动窗口 + 摘要压缩。保留最近 5 轮对话的完整内容，更早的对话用模型生成一段 200 字以内的摘要。摘要的提示词经过精心设计，要求保留“用户核心诉求”、“已承诺的解决方案”、“关键时间节点”三个要素。

实测下来，这种策略在保持推理质量的同时，把平均上下文长度从 6000 Token 压缩到了 1800 Token 左右。但要注意，摘要生成本身也会消耗 Token 和时间，所以只对超过 10 轮的长对话启用。对于短任务，直接保留完整历史反而更高效。

4.3 状态持久化与故障恢复

Agent 执行过程中，如果服务重启或节点崩溃，正在处理的任务不能丢。我们用的是检查点机制：每个节点执行完成后，把当前状态对象序列化后写入数据库（PostgreSQL 的 JSONB 字段）。如果服务重启，工作流引擎会从最后一个成功的检查点恢复执行。这个机制在灰度发布和紧急修复时特别有用，不用担心中间状态丢失导致任务卡死。

检查点的写入频率需要权衡。每个节点都写会增加数据库压力，但写得太少又会导致恢复时重复执行过多步骤。我们的经验是：对于有副作用的节点（如发起退款），执行前和执行后各写一次检查点；对于只读节点，可以每三个节点合并写一次。这样既保证了关键操作的可恢复性，又控制了写入频率。

5. 多 Agent 协作：什么时候需要，什么时候是过度设计

5.1 单 Agent 的能力边界在哪里

在决定是否引入多 Agent 架构之前，必须先搞清楚单 Agent 的瓶颈在哪。根据我们的实践，单 Agent 在以下情况会力不从心：任务需要多种截然不同的专业知识（如同时涉及法律条款解读和财务计算）、任务步骤超过 15 步导致上下文过长、或者需要并行处理多个子任务再汇总结果。如果只是步骤多但逻辑单一，比如一个 20 步的数据处理流水线，用工作流引擎串行执行完全够用，没必要拆成多个 Agent。

我们曾经在一个“合同智能审核”项目里尝试过多 Agent 方案：一个 Agent 负责提取关键条款，一个负责比对风险点，一个负责生成审核意见。结果发现，三个 Agent 之间的通信开销（传递合同文本、协调审核进度）比单 Agent 顺序执行还要大，而且经常出现“条款提取 Agent 认为某条款没问题，但风险比对 Agent 认为有问题”这种矛盾。后来改回单 Agent + 工作流，把三个环节做成三个节点，反而更稳定高效。

5.2 多 Agent 协作的通信协议设计

如果确实需要多 Agent，通信协议的设计至关重要。我们试过两种模式：黑板模式和消息传递模式。黑板模式是所有 Agent 共享一个中央状态存储，各自读取和写入。这种模式实现简单，但容易产生竞态条件，而且随着 Agent 数量增加，状态存储会成为瓶颈。消息传递模式是 Agent 之间直接发消息，解耦更彻底，但需要处理消息丢失和顺序问题。

最终我们选择了一个折中方案：基于事件总线的发布-订阅模式。每个 Agent 把自己的输出作为事件发布到总线，其他 Agent 按需订阅。比如“条款提取 Agent”发布clauses_extracted事件，“风险比对 Agent”订阅这个事件后开始工作。这种模式既避免了共享状态的竞态问题，又不需要点对点的复杂路由。事件总线用 Redis Streams 实现，轻量且支持消费者组，多个同类型 Agent 可以水平扩展。

5.3 避免“Agent 套 Agent”的递归陷阱

有一个很容易掉进去的坑：让一个“协调者 Agent”去调用其他“工作者 Agent”，而工作者 Agent 内部又可能调用子 Agent。这种递归结构在 Demo 里看起来很酷，但在生产环境里是灾难。首先，调用链路过长导致延迟不可控，一个请求可能经过五六个 Agent 才返回。其次，错误处理变得极其复杂，底层 Agent 的失败如何向上传播、如何回滚，很难设计清楚。最后，调试几乎不可能，你需要在多个 Agent 的日志之间来回跳转。

我们的原则是：Agent 层级不超过两层。顶层是工作流引擎，负责流程控制；底层是执行具体任务的 Agent 或工具。如果某个任务复杂到需要再拆一层，我们宁愿把它做成一个独立的工作流，通过事件触发，而不是嵌套调用。

6. 可观测性与评估：怎么知道 Agent 干得好不好

6.1 关键指标的定义与采集

Agent 系统的监控不能只看“成功率”一个指标。我们定义了四个维度的指标：任务完成率（最终成功完成的任务占比）、步骤效率（实际执行步骤数与最优步骤数的比值）、工具调用准确率（正确调用工具且参数无误的比例）、人工介入率（需要人工接管的任务占比）。这四个指标结合起来，才能全面反映 Agent 的健康状况。

采集方式上，我们在每个节点执行时打点，记录开始时间、结束时间、输入 Token 数、输出 Token 数、工具调用详情、以及模型返回的原始内容。这些数据汇总到 ClickHouse 里，用 Grafana 做可视化。每天早会时，团队会看一眼昨天的指标趋势，如果发现某个指标异常波动，就立即排查。

6.2 离线评估集的构建与迭代

线上指标反映的是“当前表现”，但要判断“改进了没有”，需要有一个固定的离线评估集。我们构建评估集的方法是：从历史任务中随机抽取 200 个已完成且人工确认结果正确的案例，覆盖各种边界情况（如超时订单、VIP 用户、多商品退款）。每次修改提示词、调整工作流、更换模型后，都在这 200 个案例上跑一遍，对比关键指标的变化。

评估集的维护也很重要。随着业务变化，旧的案例可能不再有代表性。我们每个季度会重新审视评估集，替换掉过时的案例，补充新出现的边界情况。这个过程虽然繁琐，但能避免“优化了半天，结果优化的是已经不存在的场景”这种尴尬。

6.3 人工反馈的闭环机制

无论自动化程度多高，人工反馈始终是提升 Agent 质量的关键。我们在工单系统里加了一个“Agent 处理质量”的评价按钮，客服人员可以快速标记“处理正确”、“处理有误”、“需要改进”。对于标记为“有误”的案例，系统会自动把完整的执行链路（包括每步的输入输出）推送到一个专门的复盘队列。每周我们会花两个小时集中分析这些案例，找出共性问题，然后针对性地调整提示词或工作流逻辑。

这个闭环机制运行三个月后，我们的 Agent 任务完成率从最初的 67% 提升到了 89%，人工介入率从 45% 降到了 18%。更重要的是，团队对 Agent 的能力边界有了更清晰的认识，不再盲目追求“全自动”，而是在合适的环节主动引入人工确认。

7. 踩坑实录：那些文档里不会写的教训

7.1 模型版本升级引发的“血案”

有一次，我们使用的模型服务商发布了一个小版本更新，官方说明是“提升了指令遵循能力”。我们没多想就直接切换了。结果第二天发现，退款金额计算节点开始出现错误，模型把“退款比例 80%”理解成了“退款 80 元”。排查了一整天，最后发现是新版本模型对百分比符号的处理逻辑变了。这件事给我们的教训是：任何模型版本变更都必须经过完整的回归测试，不能因为官方说是小更新就掉以轻心。现在我们有一个专门的回归测试流水线，包含 50 个核心案例，模型切换前必须全部通过。

7.2 工具描述里的“隐藏歧义”

我们有一个“发送通知”的工具，描述是“向用户发送短信通知”。结果模型经常在用户明确表示“不要发短信”的情况下仍然调用这个工具。后来发现，描述里没有说明“发送前需要检查用户的通知偏好设置”。加上这句后，问题解决了。这个案例说明，工具描述不仅要说明“做什么”，还要说明“什么时候不该做”以及“做之前需要检查什么”。这些约束条件在人类看来是常识，但模型需要显式地被告知。

7.3 并发场景下的状态覆盖问题

在高峰期，同一个用户可能同时提交多个工单。我们的 Agent 最初用user_id作为状态对象的键，结果两个工单的状态互相覆盖，导致处理混乱。修复方案是改用ticket_id作为唯一键，并且在状态对象里增加一个version字段，每次更新时检查版本号，防止并发写入冲突。这个坑在单用户测试时完全发现不了，只有压测才能暴露出来。

7.4 日志脱敏的疏忽

有一次安全审计发现，我们的 Agent 日志里包含了用户的完整手机号和身份证号。这是因为工具调用时，外部 API 返回了这些敏感信息，而我们直接记录到了日志里。后来我们在工具层加了一个脱敏过滤器，对手机号、身份证号、银行卡号等字段自动做掩码处理。这个教训提醒我们，Agent 系统处理的数据往往比传统系统更敏感，日志脱敏必须从第一天就做，不能等出事再补。

8. 从项目实战中提炼的架构决策清单

回顾这一年多的 Agent 落地历程，如果让我给正在准备把 Agent 推向生产的团队提建议，我会把以下几条作为架构评审的必查项。第一，工作流引擎是否独立于模型。如果你的 Agent 逻辑和模型调用深度耦合，换一个模型就要重写大量代码，那说明架构有问题。第二，状态是否可持久化、可恢复。服务重启后任务能不能接着跑，这是生产环境和 Demo 的分水岭。第三，工具层是否有统一的超时、重试、熔断、脱敏机制。这些横切关注点如果散落在各个工具里，维护成本会指数级上升。第四，是否有完整的可观测性。出了问题能不能快速定位到是哪个节点、哪次调用、哪个参数导致的。第五，是否有离线评估集和回归测试。没有这个，你就是在盲目迭代。

还有一个容易被忽视的点：文档和知识沉淀。Agent 系统涉及提示词、工作流定义、工具描述、评估案例等多个维度的配置，如果没有一个集中的知识库来管理这些内容，新人接手时会非常痛苦。我们内部用 Notion 建了一个 Agent 知识库，每个 Agent 一个页面，包含架构图、关键决策记录、已知问题、变更历史。这个习惯让团队在人员流动时依然保持了较高的交付效率。

最后分享一个我在实际项目中体会很深的原则：Agent 的价值不在于替代人，而在于把人从重复性劳动中解放出来，去做更需要判断力的事情。我们那个退款处理 Agent 上线后，客服人员并没有被裁掉，而是转去做更复杂的客诉处理和关系维护，工作满意度反而提升了。技术方案的设计，最终还是要回到业务价值和人的价值上来。