企业官网建设流程全解析

从一次翻车Demo说起。前阵子我给一个内部工具做Agent化改造，目标是让模型自动查订单状态、补发通知、按规则升级异常单。演示前我信心很足，结果当着使用方负责人的面，Agent第一轮就栽了——工具调用返回的JSON被截断，参数嵌套错位，整个流程卡死在中间态。我一边手忙脚乱修数据，一边解释“模型输出有点随机”，场面相当尴尬。

那次之后我花了很长时间重新审视Agent开发这件事。结论是：Agent开发真正的门槛不在模型，而在编排。模型再怎么强，也只是个会犯错、会遗忘、会钻牛角尖的“脑力劳动者”；你要设计的不只是一段提示词，而是一整套让这个“脑力劳动者”能干活的流程、边界和纠偏机制。

这篇文章不聊概念，就聊我实际做下来看到的门道，给正在做Agent项目、或者准备评估Agent能力的团队做个参考。

1. 为什么说Agent开发不是写程序，而是组织一次“委托协作”

1.1 一次翻车Demo给我的三个冲击

那天的场景其实是标准的多步任务：查询订单状态、判断是否需要补发、给客户发送通知。我事先把系统提示词写得非常详细，工具描述也做了结构化模板，自认为万无一失。结果同一个任务跑三次，三次结果都不一样：

• 第一次调用成功，模型正确解析了订单号；
• 第二次同样的输入，模型把参数名从order_id换成了orderId，工具层没认出来；
• 第三次更离谱，模型连续两次调用了同一个查询工具，参数一模一样，纯粹空转。

这件事给我的冲击主要有三个。第一，模型不是程序，它不会“给定相同输入，永远给出相同输出”，同一个提示词在不同轮次可能有细微波动，这种不确定性是Agent开发的底层前提。第二，提示词写得再详细，也只是降低了出错概率，并没有消除出错可能，你必须在外层做兜底。第三，人工“调通一次”和“工程可靠”是两回事，一两个Demo成功不能说明系统可用，你需要用数据去度量它。

后来我把这次事故当作团队内部的一个反面教材反复讲：Agent开发里最危险的心态，就是把模型当作一个“听话的函数”。模型不是函数，它是个有主见但也会马虎的协作者。

1.2 传统编程与Agent开发的本质分野

传统编程的世界是确定性的：if/else、循环、数据库事务，给定输入，期望输出基本固定，出错了能通过日志精确回溯。你写的每一行逻辑，都是确定的因果关系。

Agent开发不一样。模型在每一步都是“概率性决策”，它可能在两个同样合理的行动之间摇摆，可能因为上下文太长而忘掉最初目标，也可能在一个已经失败的选项上反复重试。代码层面的if/else管不住这些行为，因为模型的“输入”是自然语言，输出也是自然语言或半结构化数据，边界是模糊的。

我常用一个类比来解释这件事：传统编程是你在骑自行车，每个动作精确可控制；Agent开发是你给一个实习生交代任务，告诉他目标、给他工具、告诉他哪些事情绝对不能做，然后放手让他干。实习生的好处是会变通，坏处是你得随时准备纠偏、复查、处理他交回来的“半成品”。

所以Agent开发的本质，不是“写逻辑”，而是“组织一次委托协作”。你的核心任务是定义清楚：目标是什么、有哪些工具、每一轮决策需要什么信息、什么情况下停下来、什么情况下必须回到人类这里来。换句话说，代码管规则，模型管判断。

2. Agent的心智模型：用“任命高管”的思路设计系统

2.1 LLM Agent的五个核心组件拆解

我把一个完整的Agent系统拆成五个组件，做任何Agent项目都可以拿这个框架对一下，看看自己漏了哪块：

• 目标：任务定义，通常写在系统提示词里。目标要明确，但不能把步骤也写死。比如“查询订单状态并处理补发”，比“先调接口A，若返回B再调接口C”更合理，因为模型需要保留判断空间，而步骤很可能在实际执行中需要调整。
• 规划器：决定“下一步做什么”。常见有ReAct循环（推理-行动-观察）和Plan-and-Execute（先列计划再执行）。规划器决定了系统是走一步看一步，还是先把方案定了再动手。
• 工具集：模型可调用的外部能力，包括API、数据库查询、代码解释器、搜索等。工具集是Agent的“手和脚”，也是出错率最高的地方。
• 记忆：短期记忆是当前上下文窗口，长期记忆可以是向量库、摘要缓存或外部数据库。记忆设计不好，Agent会变成“金鱼”。
• 护栏：权限白名单、预算上限、步骤数上限、敏感操作人工审批等。护栏是Agent系统能不能上生产的生死线，没有护栏的Agent只配活在Demo里。

这五个组件里，目标决定方向，规划器决定策略，工具决定能力边界，记忆决定连续性，护栏决定安全性。任何一个组件缺位，系统都能跑起来，但跑不远。

2.2 开发者的工作重心：定协议而不是写逻辑

很多刚接触Agent开发的同事喜欢在系统提示词里穷举各种情况：“如果用户说A，你就做B；如果说C，你就做D。”这种写法的产出是一个无比臃肿的提示词，看起来面面俱到，实际上模型根本记不住，而且一旦场景超出枚举范围，反而会无所适从。

我的经验是：提示词负责定义角色和目标，代码负责定义规则。你要把主要精力放在“模型与工具之间的协议”上。协议至少包括这几个问题：

• 工具描述怎么写？参数类型、必选可选、枚举值、示例值，都要结构化地写清楚。模型对工具描述的理解，直接决定了它能不能正确调用工具。
• 工具结果怎么返回？返回结构要固定，比如{ "status": "success", "data": {...} }，不要让模型去解析一段自由文本。
• 出错怎么上报？工具异常应该有明确的错误码和错误消息，模型看到错误之后才能做出正确的下一步决策，比如换个参数重试，或者放弃并上报。
• 什么情况下停止？成功条件、失败条件、最大步数，都要在协议里定义清楚，否则Agent会一直“努力”下去。

举个例子，一个查询工具的描述我是这样写的：

工具名：query_order 功能：根据订单号查询订单状态 参数： order_id（string，必填）：订单编号，格式为 14 位数字 include_items（boolean，可选，默认 false）：是否返回订单商品明细 返回： status（string）：success / not_found / error data（object）：订单状态、更新时间、物流信息

工具描述写得好不好，直接决定模型调用的准确率。我之前测试过：把参数描述从一行简单文本改成带有类型和示例的结构化描述后，同一批测试用例的工具调用正确率能从76%提升到91%，而且这还是在模型版本、提示词完全不变的情况下。协议设计是Agent开发里投入产出比最高的环节，可惜大多数人把精力都花在提示词上了。

3. 框架选型与模式取舍：从单Agent到多智能体

3.1 三种模式的定位差异

Agent开发在架构上通常有三种模式，很多团队一开始没想清楚就上了最复杂的，后面维护成本非常高。这三种模式我都实际跑过，先说结论：能简单就简单，能用工作流解决就别上多智能体。

单Agent模式：一个模型循环负责全部决策，每一步决定调用哪个工具、如何解读结果。优点是实现简单、容易排查，缺点是单个模型要承担所有认知负担，任务一复杂就容易顾此失彼。我用下来觉得，适合步骤不超过五六步、工具不超过十个的垂直场景。

工作流模式：把流程预先编排成固定步骤（DAG或者状态机），只在特定节点让模型做决策。比如“先识别意图，再抽取参数，再查询数据，最后由模型生成回复”。这种模式的稳定性和可调试性最好，因为流程的骨架是确定的，模型的自由度被限制在特定环节。缺点是灵活度低，不适合需要临场发挥的任务。

多智能体模式：多个模型角色协作，比如规划者、执行者、审查者，各自有独立的提示词和工具权限，通过某种通信协议交换信息。这种模式的想象力上限最高，但复杂度也最高：角色之间可能互相误解、上下文重复消耗、成本指数级上升。我的判断是，只有当任务本身真的需要“分工协作”时才值得用，比如需要一边搜索资料一边做对比分析的场景。

3.2 选型三原则

面对这三种模式，我是用三个原则来判断的：

复杂度决定分工。任务越复杂，越需要拆角色。但如果一个单Agent能跑下来的任务，硬拆成三个Agent，只会徒增成本和不稳定性。我见过一个客服项目，早期用多智能体做意图识别和情感分析，结果两个角色之间互相覆盖，最后改回单Agent加工作流，效果反而更稳定。

容错成本决定护栏强度。任务出错代价越高，越要把决策权交给代码和人工。比如涉及支付、法务、对外承诺的操作，我的建议是模型只负责生成“建议动作”，由代码层或者人工审批确认之后再执行。之前团队做过一个自动回复项目，凡是涉及赔偿金额的回复，一律设置了人工审批门槛，这个设计后来避免了好几次低级事故。

迭代速度决定抽象程度。项目早期，别急着引入花哨框架。先用最原始的“写死循环 + 提示词”跑通核心链路，验证业务效果，再逐步抽象。框架只是解决基础设施问题，Agent的策略和协议设计始终在你自己的手里，别把框架当万能药。

3.3 框架层的能力对比

我陆续试过几类主流的Agent开发框架，简单说下体感（不点名具体产品，你可以对照自己的场景来判断）：

我的核心建议是：框架只是给你提供了“进程、调用、解析”这些基础设施，真正决定Agent上限的是你的目标定义、工具协议、记忆策略和护栏设计。选框架的时候就问一个问题：它能不能让我方便地记录每一步的调用链路、控制工具白名单、设置步数和成本上限？能，就值得用；不能，再花哨也别选。

4. 踩坑实录：工具调用、幻觉与上下文失控的完整排障链路

4.1 工具调用的“格式抖动”是最普遍的翻车点

做Agent开发，第一个高频翻车点永远在工具调用。模型需要输出一个结构化的“函数调用指令”，比如 JSON 格式的参数，但这个输出是概率性的，偶尔就会出错。我实际遇到的问题有这几类：

• JSON被截断：输出到一半就停了，可能是生成了过长的参数或嵌套结构；
• 字段缺失或参数名漂移：模型把user_name写成username，工具层就认不出来；
• 参数类型错误：定义的是数字类型，模型给了一个字符串；
• 幻觉工具名：模型编造了一个不存在的工具名，或者是把两个工具的名字拼接在一起。

这些问题非常磨人，因为不是每次都出现，而是在特定输入、特定上下文长度下偶发。排查这类问题，我的链路是这样的：

1. 先记录原始响应。不要只看最终结果，要把模型每一步的原始输出（包括原始工具调用、原始错误）完整记录下来。没有完整的trace，这种随机性问题根本无从下手。
2. 对比失败案例的共同特征。把几十条失败日志放在一起看，找规律：是不是所有失败都发生在上下文超过一定长度之后？是不是集中在某个特定工具上？我遇到过一种情况，凡是参数里出现长文本描述，JSON截断率就明显升高。
3. 启用平台的强制工具调用机制。现在很多模型支持“强制调用某个工具”或者“结构化生成”，能显著降低参数格式错误。如果你的模型平台支持，优先用，别裸写提示词去约束格式。
4. 加一层解析与校验。在模型输出和业务逻辑之间，必须有一层代码做JSON修复和字段校验，不符合协议的直接要求模型重新生成，而不是把脏数据传给下游。这个校验层是Agent系统的“安全带”。

我还试过一种双步法：先让模型输出“意图”字段（比如“查询订单”），再根据意图输出“参数”。拆分之后，参数生成的上下文更聚焦，格式抖动的概率确实下降了，但代价是一次任务多了一次模型调用，成本和延迟都有上升。要看你的场景到底更在意准确率还是响应速度。

4.2 上下文窗口的气球效应

第二个坑是上下文管理。Agent执行任务时，每一步的工具结果都会追加到上下文里，上下文越来越大，模型的理解力反而在下降。我把这个现象叫做“气球效应”：气球吹得越大，模型越容易漏掉最原始的目标。

最典型的场景是长任务。比如一个数据分析Agent，需要连续查询十几张报表，每张报表返回几十行的JSON。查完第三张的时候，模型还能准确记住目标；到第七张，它已经开始把前面报表的字段跟后面的指标混淆；到第十二张，它甚至会“忘掉”最初的分析维度，产出跟目标无关的内容。

我的应对方案有三个：

• 滑动窗口：只保留最近N轮对话和工具调用结果，更早的内容自动丢弃。这个最简单粗暴，但要注意监督式任务不能丢关键上下文，所以往往要配合下面两个方案。
• 结构化摘要：工具结果不要原文塞进上下文，而是先经过一段摘要逻辑，转成只包含关键字段的精简格式。比如查询订单列表，200行结果可能缩成“最近三笔订单，金额分别为500、320、750，其中一笔已发货”。这个做法让上下文占用大幅下降，模型决策时反而更聚焦。
• 长期记忆外置：需要长期跟踪的信息，比如用户偏好、项目历史，放到外部向量库或数据库里，只在决策需要时检索出来注入上下文。

我给自己的原则是：上下文里只放“为当前决策服务”的信息，不放流水账。模型不是数据库，它的上下文窗口是推理工作台，不是仓库。

4.3 循环死锁：Agent为什么回不到正轨

第三个坑是循环。模型会非常执着地重复同一个动作，特别是在面对失败时。我见过一个客服Agent，在查询物流信息返回“接口超时”之后，居然连续七次用同样的参数重试同一个接口，直到步数上限被打满。这不是模型“傻”，而是它在缺乏新信息的情况下，只会重复尝试已知的行为。

这里你要明白一个本质问题：模型没有真正的“全局视角”，它每一步只看到当上下文里的信息，如果重试结果一直是失败，它不知道“换一条路”而不是“再试一次”。所以解决方案不能放在提示词里，要放在代码层：

• 设置最大步数和单一工具最大调用次数。我在项目里让模型每次最多连续三次调用同一个工具，超过后强制进入“换策略”或“上报人工”分支；
• 检测到相同工具+相同参数时自动打断。代码层维护一个“最近调用指纹”集合，发现完全重复的调用就返回一个错误提示，让模型知道这条路不通；
• 改用Plan-and-Execute模式。让模型在开始时先列出执行计划，再逐步执行，而不是每次临场决策。这种方式能减少因“不知道接下来做什么”而原地打转的概率。

其实循环死锁的本质不是模型能力问题，而是你没有给模型提供“此路不通就换路”的机制。把重试策略从模型手里收回到代码里，这个问题就能基本解决。

4.4 最小化复现：排障唯一可靠的路径

Agent项目的Bug和传统项目的Bug有一个本质区别：不可稳定复现。同一个输入，这次跑通了，下次可能失败。这导致很多人一遇到问题就改提示词，改完又不知道到底有没有用，纯靠碰运气。

我的做法永远是最小化复现。每接到一个线上失败案例，先做这几步：

1. 把失败的完整链路记录导出来，包括系统提示词版本、模型版本、模型原始输出、工具调用入参和结果；
2. 用固定的模型参数（温度设为0）在测试环境重跑同一条用例，确认能否复现；
3. 如果不能复现，就尝试改变一个变量：比如去掉上下文里的某段赘余、调整工具描述措辞、或者缩短工具返回结果，直到能找到“触发条件”；
4. 找到触发条件后，修复一个问题，再用全量回归集跑一遍，防止修了A坏了B。

这种排查方式很费时间，但它是唯一可靠的路径。我在这个项目后期建立了一个“失败案例库”，每一条都带着原始trace和触发条件，每次改完提示词或升级模型版本，都要拿这批案例回归。这个案例库后来成了团队最重要的资产之一，比任何提示词模板都值钱。

5. 把不确定性关进笼子：Agent项目的工程架构实践

5.1 推理层与执行层的两个世界

架构上，我坚持把Agent系统拆成两个世界：推理层和执行层。

推理层是模型做决策的地方，允许模糊、允许概率性、允许犯错的余地。执行层是代码和API运行的地方，要求精确、要求校验、要求可重试。模型不应该直接去操作数据库或调用外部系统，而应该输出“指令”——一段结构化的描述，比如“查询订单号abc123的状态并确认收货地址”。代码层负责解析这段指令、做权限校验、调用真正的API、把结果转成结构化数据返回给模型。

有人可能会觉得这样多此一举。但实际项目中，这个分层救了不知道多少次。一层是把模型的自由裁量权限制在“提建议”的范围内，真正动手的是确定性的代码；二层是所有的敏感操作比如支付、转账、删除，都可以在这层强制加人工审批。模型可以建议“给用户退50元”，但真正执行退款的，是一道带着审批标记的代码调用。模型再厉害，也碰不到钱。

这个设计我用一句话总结：CEO可以做决策，但付款必须走财务流程。

5.2 状态机加LLM的混合编排

我见过不少团队做完Agent后，流程控制完全靠模型的自然语言输出，整个系统的运行轨迹就像一锅粥。我的建议是：用状态机管骨架，用LLM管决策。状态机负责定义任务的合法状态和转移条件，LLM负责在某个状态下选择下一步动作。

举个例子，一个工单处理Agent，我定义了这样几个状态：

每个状态之间的“合法转移”是代码写死的，模型只能在当前状态下选择可执行的动作。比如在processing状态下，模型可以调用工具查询数据，但不能直接跳到done，必须满足代码定义的完成条件。这样整个系统就有了一个“剪枝”机制：模型再怎么自由发挥，都逃不出你画的笼子。

这套混合编排的调试体验比纯Agent自主循环好太多了。出了问题，你可以直接看状态机停在哪个状态、是哪一次转移决策导致的，而不是在几十轮对话日志里大海捞针。

5.3 数据模型、权限与预算的安全设计

Agent项目里的安全设计绝不是“模型不做危险的事”，而是“危险的事根本到不了模型手里”。我做项目时维护这样的基础设计：

工具白名单：每个Agent绑定一份工具清单，不需要的工具一律不在提示词里出现，接口层再做一层校验。不加白名单的话，模型一旦幻觉出一个工具名，可能直接撞上真实接口，这是事故源头。

用户级权限：每个用户的权限在工具层校验，不能信任模型输出的用户身份。模型可能会在上下文里看到用户A的信息，然后错误地用它去执行用户B的查询。工具层要强制校验“当前会话对应的用户”与“被操作对象的所有者”是否一致。

预算控制：每一个Agent任务都要设置费用上限、步数上限、token上限。模型本身没有成本意识，它不会想着省着点用。我在项目里设了三层：每步计费、每任务封顶、全局并发限流，超了就自动熔断，回到人工流程。

敏感操作审批：涉及支付、退款、对外发布、改账号等操作，模型只能生成“建议动作”，由代码层生成审批单，人工确认后才执行。这个机制会牺牲一些自动化率，但换来的是可追责、可解释。

数据模型方面，我用四张核心表记录一切：任务表（task）、步骤表（step）、工具调用记录表（tool_call）、人工审核记录表（approval）。每一条Agent行为都有案可查，这既是排障的基础，也是背锅的时候能说清楚问题的底气。

5.4 可观测性：日志、链路追踪和成本仪表盘

黑盒系统必须有白盒运维手段。Agent项目的可观测性比传统项目更重要，因为它的行为是概率性的，不在运行期记录足够的信息，事后根本无从分析。

我给每个Agent请求设计的标准日志包含：系统提示词版本、模型名称与参数、模型的完整输入输出（原样保留，不做截断）、工具调用列表（每个工具的入参、出参、耗时、费用）、状态转移记录、最终结果和人工修改记录。日志全部带trace_id，一条任务的全过程可以完整串起来。

成本仪表盘是另一个必需的运维工具。我做过一个Agent，单任务平均成本从早期的0.8元降到0.3元，怎么做到的？就是靠仪表盘发现“模型在工具调用失败后反复重试，白白消耗了大量token”。后来加了重试限制，成本立刻降下来。没有成本仪表盘，这种钱就无声无息地烧掉了。

可观测性不是“出了事再上”，而是项目第一天就要有。因为Agent项目的Bug是概率性的，比如在测试环境跑50次才出现一次，如果没有trace，复现和修复基本无从谈起。

6. 评测与迭代：Agent项目最难的是“觉得它已经够好”

6.1 评测集建设：比调Prompt重要十倍

Agent开发的另一个核心工作，是建设一套能代表真实场景的评测集。我吃过一个很大的亏：早期项目开发时沉浸在Demo里，觉得对话流畅、工具调用正常，功能应该是能用了。结果放到真实用户手里，各种奇怪的输入扑面而来，成功率骤降到三成以下，整个项目直接返工。

现在我的做法是，每做一个Agent，第一件事不是写提示词，而是先整理评测集。评测集至少要覆盖三类场景：

• 正常场景：代表大部分用户的主流请求，占评测集的60%左右；
• 边界场景：输入格式奇怪、语义含糊、需要澄清的情况，占25%左右；
• 异常场景：工具失败、数据缺失、需要安全兜底的场景，占15%左右。

异常场景的来源有三个：线上失败案例、客服反馈、自己脑补的风险点。每条评测用例都要人工标注“期望结果”，不只是期望的最终答案，还包括期望的工具调用路径。注意：最终答案对但工具调用路径错乱的用例，也要算失败，因为路径是判断Agent逻辑健康度的关键。

6.2 四个核心指标判断健康度

有了评测集，就要用指标来衡量Agent的健康度。我自己看四个核心指标：

这四个指标不是孤立看的。比如工具调用有效率低，往往意味着工具描述不清楚、或者上下文里有干扰信息；步数激增，往往意味着模型在做无效尝试。每个指标都能导向一个具体的优化方向，而不是“凭感觉调提示词”。

6.3 回归测试与灰度发布

Agent模型升级是双刃剑。升级模型版本后，Demo效果可能变好，但整体成功率可能反而下降，因为模型的行为在长尾场景可能完全不一样。我遇到过一次：升级模型版本后，顺畅场景的回复质量明显提升了，但在一批口语化长尾请求上，工具参数抽取成功率掉了二十个百分点。最后是评测集的回归测试抓住了这个问题，否则直接上生产就是事故。

所以我的上线流程是严格灰度：

1. 跑评测集对比：新旧模型在同一评测集上跑一遍，对比四个核心指标，不达标就不上。
2. 小流量灰度：先切5%的流量到新版本，观察真实场景的成功率、成本和客诉反馈，运行几天再评估。
3. 逐步放量：灰度数据稳定后才逐步扩到30%、100%。如果过程中指标回弹，立即回滚到旧版本。

Agent项目的迭代尤其要有这个纪律，靠感觉不能上线。模型是个概率系统，小样本下的优秀表现说明不了真实分布下的可靠性。

7. 我在这个过程里最大的转变

7.1 从“调通一次”到“稳定跑一周”

做Agent开发之前，我是在传统后端开发的环境里长大的，习惯“写一次、跑一万次都一个结果”的心智。做Agent之后，我最大的转变就是接受不确定性：模型会犯错、会不走寻常路、会冒出让你哭笑不得的输出，这不是Bug，这是这个技术形态的属性。

所以我不再追求“模型永不犯错”，而是追求“犯错之后系统能兜住”。我给自己定了条规矩：一个Agent从能演示到敢上线，至少要准备两倍于功能开发的评测与护栏时间。这个比例听起来很夸张，但实际项目里不过这条线就上线，多半会出问题。

我现在带项目时，也会刻意要求成员先写评测集、先画状态机、先列工具白名单，再写系统提示词。顺序反了，后面全是坑。

7.2 一句让我反复咀嚼的工程口诀

最后分享一句我在这个过程中反复咀嚼的口诀：“把确定的事情写进代码，把不确定的事情交给模型，把模型不确定的事情拦在系统外面。”

这句口诀大概可以解释我前面聊的所有内容：确定的流程、权限、状态转移，用代码写死；需要判断的意图、参数抽取、方案选择，交给模型；模型不确定的高风险动作，用护栏和人工审批拦在外面。

Agent开发做久了，你会慢慢发现它其实不只是软件工程，更像是在设计一个组织：有目标、有分工、有流程、有边界、有复盘。一个稳定的Agent系统，本质上是一个把人类协作经验抽象成“协议+护栏+纠偏机制”的系统。这些经验无法从模型能力本身获取，只能靠一遍遍踩坑积攒。希望这篇内容能帮你少踩几个我踩过的坑。