企业官网建设流程全解析

最近AI Agent的风刮得是真猛，DeepSeek公开了Agent训练新方法，吴恩达的Agent教程火了一轮又一轮，扣子、Dify、Codex这些工具和框架铺天盖地。很多开发者的困惑在于：看了无数概念图，一上手还是不知道从哪写起——要不要用框架？记忆怎么搞？工具调用为什么老报错？并发怎么扛？

这篇文章我不讲虚的，就从实战开发的视角，把Agent到底怎么搭、怎么选型、怎么调通、怎么排坑拆开揉碎了讲一遍。不管你是刚接触AI开发的前端/后端工程师，还是已经在用Coze这类平台搭过几个demo的爱好者，这篇文章都能帮你把零散的经验串成一条相对完整的开发路线。我会用一个真实的制度条例学习助手项目贯穿全文，一步步展示从需求拆解到参数调优的完整过程。

1. 先搞清楚Agent到底在解决什么问题

1.1 大模型只是"嘴"，Agent才是"手脚"

很多人容易把Agent和大模型API调用混为一谈。我给个直白的比喻：大模型本身就像一个刚毕业的高材生，知识储备很强，但你问一句他答一句，你不推他他不动，而且他手里没笔没纸没电脑，只能凭记忆说话。Agent呢，是给这个高材生配了电脑、配了计算器、配了资料库，还定了一套工作流程——他拿到任务后会自己列计划、查资料、调工具、检查结果、修正错误。

所以Agent开发的核心，不是"调大模型接口"这一步，而是把"大模型的决策能力"和"外部系统的执行能力"之间的齿轮咬合起来。这个齿轮是怎么咬合的，就是Agent框架存在的意义。

1.2 Agent和普通AI应用的本质区别

我用一张表说清楚传统AI应用和Agent式应用的区别：

拿制度条例学习助手来说，传统方式就是用户问"我们公司考勤制度里迟到怎么定义的"，系统去向量库里检索出相关段落，拼到Prompt里让大模型回答。Agent的方式是：大模型先判断"这是个制度查询问题，需要检索知识库，并且需要确认制度版本，如果查不到要告诉用户去哪里找原文"，然后自主调用检索工具，如果检索结果置信度不够，它还会换一种检索方式或者问用户补充信息。这个"先判断、后执行、按需调整"的能力，就是Agent的价值。

1.3 哪些场景真的需要Agent

我在实际评估项目时有一个判断标准：如果任务是一个单次的、无需多步操作的"查一下-答一下"，千万别上Agent，直接RAG就够了。但如果有下面几种特征之一，就得考虑Agent了：

第一类是任务闭环型场景。比如客服工单处理，不光要回答客户问题，还要查订单状态、生成退款工单、同步给财务系统，这就涉及多步工具调用，用Agent天然合适。

第二类是数据梳理和汇报型场景。比如让Agent去各个系统拉取运营数据，汇总成周报，还要按不同部门的口径分别输出，这就远不是一次Prompt能搞定的。

第三类是面向特定领域的知识助手。这类场景的核心是控制幻觉、给出出处、按制度版本回答问题，这也是我后面实战案例要讲的类型。

判断清楚场景，后面所有技术选型才有依据。

2. Agent内部四轮一引擎：架构拆解

2.1 引擎：大模型怎么"想一步做一步"

Agent的决策引擎本质上是让大模型按照"推理-行动-观察"的循环来工作，这个模式在学术上叫ReAct（Reasoning and Acting）。通俗解释就是：模型在每一轮不是直接给出最终答案，而是先输出"当前情况的分析"，再决定"下一步要调用哪个工具、传什么参数"，工具执行完返回结果后，模型再基于这个结果继续推理，直到它认为任务完成。

这里的关键点在Prompt工程上。ReAct模式的Prompt格式通常是：给你一套工具清单，每件工具标明名字、参数格式、用途，然后模型按照固定的思维模板输出。框架层做的事情，就是把模型的中间推理过程和工具调用请求解析出来，真正去执行工具，然后把结果塞回上下文里。

实操中有一件非常容易踩坑的事：不要指望模型按照你脑补的格式调用工具。所有工具参数必须写成严格的JSON Schema，并且要在Prompt里给出一到两个Few-shot示例。我见过太多开发者在Coze或自研框架里报"agent execution terminated due to error"，排查到最后发现不是代码问题，而是工具参数描述不清楚，模型生成了一堆无效调用。

2.2 Planning：把大任务拆成小步骤

规划能力是Agent能不能撑起复杂任务的关键。现在主流的实现方式有三种层次：

第一种是硬编码工作流，在Coze这类平台里叫做"工作流节点"，开发者提前把"意图识别→知识库检索→答案生成"这些步骤画成流程图，大模型只在某个节点内部做选择。这种方式可控性最高，适合业务路径清晰的场景。

第二种是模型自由规划，也就是常见的"Plan-and-Execute"模式，大模型接到任务后先自己输出一个步骤清单，然后一步步执行。Coze的"任务规划器"、LangGraph里的Planner节点都是这个思路。这个做法的优点是真的"智能"，缺点是容易跑飞——尤其当工具很多时，模型可能会选择一条匪夷所思的执行路径。

第三种是混合模式，规划由模型完成，但每一步的执行都被开发者在外部强校验，比如工具调用失败就自动切换备选方法，超过最大轮数强制结束。我强烈建议生产级Agent用这个模式，纯自由规划用在Demo里爽，用到生产环境就是事故制造机。

我做制度助手时的规划策略是：先定义几个明确的用户意图分支（制度查询、考勤规则查询、休假流程查询、投诉建议），再用模型判断用户属于哪个分支，每个分支走各自固定的工作流。这样既不牺牲灵活性，又避免了模型在知识库检索环节上自由发挥。

2.3 Memory：短期记忆与长期记忆怎么分层

记忆是Agent项目里最容易被低估的部分。很多Agent用着用着就变笨，不是模型变笨了，而是记忆该管没管。

短期记忆本质上就是对话历史。问题在于，大模型的上下文窗口再大都塞不下无限累积的对话。我见过不少项目，早期测试很聪明，用了两三个月之后用户发现它"忘了之前说过的事"，就是因为对话历史被粗暴截断，最早的关键信息被丢弃了。正确做法是：对历史消息做滑动窗口管理，保留最近N轮完整对话，从N轮之前的内容中做关键信息摘要，每轮对话结束后更新这个摘要，和最近窗口一起拼进Prompt。这样既控制了Token耗费，又不会把关键背景弄丢。

长期记忆则需要落地到存储层。通常做法是：把用户信息、业务关键数据、知识库标签等结构化内容存到数据库里，当新对话开始时，根据用户ID和当前意图，从长期记忆中检索相关内容拼进Prompt。比如制度助手需要记住"该用户是哪个部门、之前咨询过哪类制度"，这决定了检索知识库时的过滤条件。

另外要特别注意记忆的写入时机。不要每轮对话都写，那会浪费大量Token；建议只在关键节点写入——比如任务完成时、用户明确纠正了信息时、或者抽取到结构化实体时。我自己写记忆模块的教训是：先想清楚"哪些信息跨轮对话还需要"，再设计记忆存储结构，而不是看个Agent教程就上Vector Store。

2.4 Tools：工具调用的底层原理

工具调用（Function Calling）是Agent和外部世界交互的桥梁。你需要理解：它并不是大模型直接执行代码，而是大模型在理解工具描述之后，输出一个结构化的"调用意图"，由Agent框架去执行。

所以注册工具时有几个核心动作：定义工具名称、定义工具的描述（这直接决定模型会不会在合适时机调用它）、定义工具的入参Schema、定义出参结构。以制度助手为例，我定义了一个名为search_institution_docs的工具，描述是"根据关键词检索企业制度文档，返回相关片段和文档出处"，入参是keyword和department，出参是文档列表。模型判断用户问题涉及制度查询，就会输出类似{"tool": "search_institution_docs", "args": {"keyword": "迟到", "department": "研发部"}}的调用请求。

一个常见的误区是工具定义过多过杂。模型面对十几二十个工具时选择准确率会显著下降。我的经验是，优先合并功能相近的工具，把工具数量控制在6到8个以内。如果有20个工具，不如分成两组，先用一个路由工具决定调用哪一组。

2.5 Action：执行闭环与安全边界

Agent执行工具之后，拿回来的结果必须回到模型的上下文里，让模型观察结果、判断是否完成了任务，这就是行动-观察闭环。在这一环上，两件事必须做：

一是设置最大迭代轮数。我建议调试阶段设3到5轮，生产环境可以放宽到8到10轮，但绝对不能无限。Coze里默认的配置有时候会显得"卡了很久没反应"，很多就是Agent在反复调用工具走不出循环。设置轮数上限之后，超时就返回"当前问题需要人工处理"，同时记录全流程日志，方便排查。

二是做权限隔离和安全校验。Agent能调的每一个工具都要审查它的影响范围。比如一个能读数据库的工具，一定要在参数层加数据范围限制，避免用户通过Prompt注入诱导Agent执行越权查询。这块后面单独展开。

3. 框架与工作流选型：这步决定你能走多远

3.1 主流框架横向对比

现在做Agent的选项实在是太多了，我挑几个我实际用过的，按"从零到一快速落地"和"深度定制生产级"两个维度做个对比：

我个人的建议是：如果你只是验证业务想法，别犹豫，直接用Coze，它最大的价值是让你在一天内就搭出一个能跑通的Agent原型，把业务逻辑验证清楚比技术栈炫酷重要得多。如果这个原型验证成功、准备进生产，再考虑迁到代码框架，用LangGraph或自研去重构。

3.2 为什么建议先拿低代码平台跑通业务

我自己踩过一个大坑：上来就搞LangGraph，画了半天的状态图，写了一堆节点，结果连"业务上用户到底需要什么"都没确认清楚，最后推倒重来。

后来我养成了一个习惯——无论最终选什么框架，第一步永远先用低代码平台搭一个最小可行产品。原因有三个：第一，低代码平台把Agent运行时（工具调用、记忆管理、Prompt模板、调试日志）都内置了，你不用写基础设施代码；第二，可视化工作流让业务方可以直接参与设计，沟通成本大幅下降；第三，大部分平台自带的调试界面能直接把中间过程展示出来，这对理解Agent行为和定位问题太重要了。

Coze这类平台还有一个隐藏优势：它预置了大量插件。做制度助手时我需要文档解析、表格读取、Web搜索这些能力，如果自己写光文档解析就要折腾半天，平台插件直接填个API Key就行。

3.3 什么时候必须转向代码框架

低代码平台不是万能的，我遇到下面几种情况时会果断转代码框架：

第一，工具调用深度要求高的时候。比如Agent需要对接内部系统的复杂加密签名、需要在工具执行过程中做异步等待、需要操作数据库事务——这些低代码平台的插件机制很难优雅支持。

第二，需要对对话流程做极细粒度控制的时候。Coze的工作流节点虽然灵活，但如果你想做"根据用户情绪动态调整回复风格"这种动态策略，节点式编排会很别扭。

第三，并发量上来之后。低代码平台的多租户隔离和限流策略不一定符合你的成本模型，自建的话可以自己做请求队列优化、结果缓存、局部降级，能省不少成本。

转向代码框架时有一个平稳过渡的策略：先在Coze里把业务逻辑验证到80%的准确率，记录下工作流流转的每一步，然后照着这个流转逻辑，用LangGraph或者自研方式把同样的节点代码化。这样既保留了业务验证成果，又获得了代码级的控制力。

3.4 工作流搭建：可视化编排与代码编排的取舍

工作流这个词现在很流行，但它包含两个完全不同的东西：一个是"流程画布编排"，一个是"代码逻辑编排"。

流程画布编排适合那些业务路径相对固定、分支不超过十几个的场景。它的好处是产品、测试、运营都能看懂流程图，出问题时能直接指着某个节点说"这里卡住了"。坏处是当分支超过一定规模时，画布会变成一团乱麻。我自己定了个规矩：超过12个节点的工作流，就该考虑拆成多个子工作流，或者切换到代码编排。

代码编排适合路径不固定、需要动态路由的场景。代码里你可以用函数、条件分支、循环来实现更灵活的流程控制。比如我可以让Agent在第一次检索结果不满意时自动改检索词重试，这种逻辑在画布上画会很笨重，在代码里就是几行循环。

无论哪种编排方式，我建议工作流中所有节点都做埋点日志。至少记录：节点名、输入、输出、耗时、调用模型名称、Token消耗、错误信息。这套日志是后面排查问题最重要的依据。

4. 实战：制度条例学习助手从零搭到调优

4.1 需求拆解：别急着写代码，先画用例

这个项目来自一个真实需求：企业要把繁杂的员工制度文档（考勤制度、报销制度、休假流程、行为规范等）变成一个能对话的助手，让员工直接问自然语言问题，就能得到有出处的准确回答。

需求一上来，先别急着设计技术方案，先把用例穷举出来。我列了四类核心用例：制度条款查询（"迟到的定义是什么"）、流程步骤咨询（"年假怎么申请"）、制度差异对比（"研发部和市场部的远程办公制度有什么区别"）、无法回答问题时的兜底行为。

前三个用例基本都能用知识库检索的工作流解决，第四个用例很关键——它决定了助手在知识库查不到时的表现。我见过太多助手在这种时候一本正经地编答案，导致用户上当。这里我强制要求：知识库没有覆盖时，必须明确回答"该制度未收录或文档中未找到相关内容，请联系人力资源部确认"，禁止生成任何猜测内容。

4.2 数据准备与RAG知识库构建

知识库的构建质量直接决定了助手的回答质量，甚至比模型选型影响更大。制度文档大多是PDF和Word，第一步是清洗转换。我的建议是，不要直接用那些在线转换工具，容易丢失表格结构，要用Python的PyMuPDF和python-docx做批处理，把文档转换成带标题层级的Markdown格式，这样后面切割的时候能保持章节完整性。

切分策略是RAG效果的重中之重。我踩过的坑：一开始用固定长度切分，比如每500个字符一刀切，结果制度的编号条款经常被拦腰截断，检索出来语义残缺。后来改成按章节标题切分：先把文档按"章、节"结构拆块，如果某个块还超过800字再细化切割，切割时保留段落标题前缀。这一个小改动，检索准确率从60%提到了80%以上。

向量化方面，中文制度文档推荐用bge-m3或者国产中文Embedding模型，效果比OpenAI的Embedding在中文场景好不少。Chunk Size设700、Overlap设100是比较平衡的起始值，后面再按评测结果调整。

4.3 工作流设计：从意图识别到答案生成的完整路径

这部分的完整工作流我拆成六个步骤：

第一步，意图识别。用大模型对用户输入做分类，输出意图标签。这一步不要省，它决定了后续走哪条支路，也决定了整个系统的行为边界。我这里的意图用了一个小技巧：让模型输出JSON，包含intent（枚举值）、department（关联部门）、query_rewrite（改写后的检索词）。

第二步，检索改写。用户的自然语言往往不适合直接去知识库检索，比如用户问"我迟到半小时算不算违反纪律"，直接拿"迟到半小时"去检索不一定命中"考勤纪律"条款。所以先让模型基于历史对话和知识库索引里的关键词表，把用户问题改写成2到3组检索关键词。这一步对召回率提升非常明显。

第三步，知识库检索。拿改写后的关键词分别去向量库检索，同时做BM25关键词召回，两种结果做权重融合。Top-K设为5，把排名前5的片段返回。

第四步，答案生成。把检索到的制度片段、出处信息和用户问题拼成一个指令型的Prompt，要求模型只基于片段回答，并在回答末尾列出文档名称和章节出处。这里温度设0.1，最大输出长度设500字左右，防止模型自由发挥。

第五步，置信度校验。这一步是我的独门偏好：在Prompt里要求模型再输出一个confidence字段，标记它对当前答案的确信度。框架拿到这个字段后，如果confidence低于阈值，就自动转入兜底话术，而不是硬着头皮把不确定的答案发出去。

第六步，日志记录。把整套流程的输入、中间变量、输出完整记录到数据库，用于后续评测和问题回溯。

4.4 关键参数调优：温度、Top-K、阈值和模型选择

很多新手会忽略参数之间的联动关系。拿制度问答这个场景：

温度设低了，模型确实更忠实于知识库片段，但偶尔会把检索到的无关内容强行编进答案里；温度设高了，又容易自由发挥。我用0.1到0.2之间测试了一周，最终锁定在0.15。

Top-K直接影响引用来源的质量。K太大，会混入不相关片段干扰模型；K太小，可能漏掉真正覆盖答案的片段。对制度类文档，5是一个好起点，如果你的知识库文档段落普遍很长，可以降到3，片段越短、相关度越集中，模型越不容易被带偏。

置信度阈值则需要你自己根据评测集来标定。我先把200条测试问题的答案全部跑出来，看答案文本里有没有出现"不确定""可能""建议联系HR"之类的话，再用这些结果反推阈值。我这边最终用的是0.6，低于这个值就走兜底。

模型选型上，做意图识别这种分类任务用小模型（比如4o-mini这类）就够了，成本低速度快；做答案生成用强模型，中文场景DeepSeek和GPT-4系列都能打出不错的成绩。生产环境我习惯把意图识别和答案生成拆成两个不同的模型配置，不要混用。

4.5 项目复盘：效果评测与调优闭环

不要凭感觉说"效果好多了"，要建评测集。我通常的做法是：邀请业务方整理了150条真实员工咨询记录，人工标注出期望答案和对应制度原文章节，作为评测集。

评测指标用的是"答案有用率"和"溯源正确率"两个指标。答案有用率指模型回答是否能解决用户问题且没有错误信息；溯源正确率指给出的出处是否真实存在并且确实覆盖了答案的核心要素。这两项指标分别达到90%和85%，才够资格上线。

调优循环则是：把评测里失败案例的日志拉出来，看是检索没把正确片段召回来，还是召回了但模型生成时没采用。前者去调Embedding模型、切分策略、Top-K；后者去调Prompt结构、温度、片段在Prompt中的排列顺序。定位问题到具体环节，比盲目调参有效十倍。

5. 老鸟才知道的排坑速查表

5.1 Agent执行中断与工具调用失败的定位思路

在Coze、LangGraph或者自研框架里，最常见的报错就是像"agent execution terminated due to error"这类信息。这个信息的字面意思很简单，但实际原因千奇百怪。根据我几次排障经验，按下面顺序排查最快：

第一步，看工具调用日志，确认哪一步断的。如果断在工具调用，多半是工具入参格式不对或者工具本身报错。第二步，看模型响应日志，确认是因为模型输出超时还是模型输出了解析不了的格式。第三步，检查上下文长度，长对话很容易撞上上下文窗口上限。第四步，检查知识库检索是否超时，向量数据库偶尔会因为并发打满而返回异常。

还有一个合规细节：不要在这类错误日志里直接透传内部栈信息给前端，只保留"当前功能暂不可用"这样的用户提示，完整堆栈进后台日志。

5.2 上下文失控：为什么Agent用着用着会变笨

Agent越长越笨这件事几乎必然发生，除非你做记忆管理。我总结了一套三级策略：对话轮次多但都在一个任务里，用滑动窗口+摘要压缩历史；跨多个任务，每完成一个任务就把关键结论写入长期记忆，新任务开始时只带摘要；知识引用型内容，不放进对话历史，而是存到数据库，用到时再检索。

还有一个明显的坑：工具返回的结果太长了。比如知识库检索返回了8000字文本，全塞进上下文，后续对话的Token预算就被挤占了。我处理这类问题的方式是，在框架里写一个结果压缩函数，对工具返回的长文本做自动摘要，再拼进Prompt。

5.3 并发与性能：Agent服务怎么扛住真实流量

Agent和普通API服务最大的不同是：它单个请求耗时可能长达几十秒甚至几分钟。某个请求代码里要循环调用多次大模型API，每个OpenAI或DeepSeek请求都有延迟。如果你还是按传统的同步请求模式去设计，20个并发就能拖垮整个服务。

我建议的生产级方案是：前端请求只负责提交任务，后端把Agent任务放进队列，异步执行，执行过程中通过WebSocket或SSE流式把中间步骤推给前端。这样既实现了任务在执行过程中的可视化，又避免大量的长连接挤占Web服务线程。

同时，要主动给大模型API调用加并发限制和重试机制。以DeepSeek和GPT的开放API为例，它们的速率限制会动态变化，代码里必须用令牌桶限流算法做一层保险，超过限制的任务排队等待。另外，相同的问题可以做结果缓存，比如制度问答里"迟到定义"这种高频问题，第一次算完后写缓存，命中就直接返回。

5.4 Token成本失控：一个月多花几万块的原因

成本失控大部分不是模型单价的问题，而是调用次数和Prompt膨胀的问题。我曾见过一个Agent项目，一次完整的对话居然塞了完整的知识库索引描述、十轮历史对话、三个工具的超长说明，每次请求光Prompt就要吃掉5000多Token，成本直接翻了几倍。

控制成本的办法：一是压缩工具描述，只保留必要信息，把说明性内容移到离线文档；二是历史消息上屏的数量做严格限制，超过四轮就开始摘要；三是选用分级模型策略，意图识别分类和简单工具路由用小模型，答案生成才用旗舰模型，大多数场景成本能下降40%到60%。

5.5 安全与合规：提示词注入与越权访问

Agent安全最容易被忽略的是提示词注入。用户可能不直接问制度内容，而是拐弯抹角地让Agent忽略系统规则、泄露知识库原始文档，或者诱导Agent调用敏感工具。

防御手段分两层。一层是输入侧，在意图识别节点前加一条安全检查，用独立的轻量模型判断用户输入是否包含指令注入特征，命中可疑模式就走安全兜底话术。另一层是工具侧，凡是涉及查询、修改、删除等敏感操作，工具接收到的参数必须经过严格的类型校验和白名单过滤，绝不能直接拿用户提供的值拼进查询条件。

还有输出侧的合规审查：Agent生成的内容可能会涉及企业管理敏感信息，所以上线前配置了输出关键词过滤和人工抽检机制。Agent的能力再强，也强不过人的设置边界，如果定义一个能读取全库数据的工具，那么越权访问只是时间问题，而不是概率问题。

最后再分享一个我实际动手做这些项目时的体会。Agent开发和传统开发有一个很大的区别：传统开发你写对了逻辑它就对，Agent则是"你写对逻辑它大概率对，但你得帮它铺好所有退路"。所以做Agent项目，我最花时间的永远不是Prompt写得多漂亮，而是异常分支、兜底策略、日志埋点这些"不性感"的部分做得够不够扎实。你可以不追求一次就把整个架构搭完美，但至少从第一天起就坚持记日志、坚持建评测集、坚持给每个工具都加白名单校验。这三件事坚持下来，后面所有迭代都会顺畅很多。