企业官网建设流程全解析

1. 从一个前端视角重新理解 Agent 开发

1.1 为什么前端工程师会对 Agent 开发产生兴趣

过去两年，前端圈子里讨论最多的话题之一就是大模型应用。一开始大家的反应很直接：这东西跟前端有什么关系？不就是调个接口、渲染个对话框吗？但真正上手做过几个 AI 产品之后，我发现事情没那么简单。尤其是当产品从“单轮问答”进化到“能自己规划、自己调工具、自己反思”的 Agent 形态时，前端工程师反而站在了一个非常有利的位置上。

原因很朴素。Agent 的本质是一个“能感知输入、做决策、执行动作、拿到反馈再继续”的循环系统。这套东西前端工程师其实天天在打交道——事件循环、状态机、异步编排、错误重试、UI 反馈，这些概念换个名字就变成了 Agent 里的 planning、tool calling、memory、reflection。你不需要先成为算法工程师，才能理解 Agent 在干什么。

我写这篇东西的出发点，是身边不少前端朋友一提到 Agent 就下意识觉得“这是算法岗的事，我得先去学微调、学训练”。这个认知偏差挺耽误时间的。Agent 开发和模型训练是两条几乎平行的路径，前者更像是在做一套“带大脑的自动化流程编排”，后者才涉及权重、梯度、数据集配比。对绝大多数前端出身、想切入 AI 应用层的人来说，你真正要补的不是反向传播，而是如何把一个任务拆成模型能执行的步骤，以及如何用工程手段把不确定性兜住。

这篇文章适合三类人看：一是做过普通大模型对话应用、想往 Agent 方向走的前端；二是完全没碰过 AI、但工程能力扎实、想找个切入点的开发者；三是产品或者独立开发者，想搞清楚 Agent 到底难在哪、值不值得投入。我会尽量用工程语言讲清楚每个环节“为什么这么设计”，而不是堆一堆术语。

1.2 一个必须先纠正的认知：Agent 不等于训练模型

先把最容易混淆的地方说透。很多人把“做 Agent”和“训练模型”画等号，觉得不训练一个自己的模型就不算做 AI。实际上，市面上你能见到的绝大多数 Agent 产品，底层用的都是通用大模型，通过 API 调用，没有一行代码涉及训练。

训练模型是什么？是拿大量数据去调整模型内部的参数，让它在某个任务上的表现变好。这个过程需要算力、需要标注数据、需要评估体系，成本高、周期长，而且和前端技能栈几乎不重叠。

Agent 开发是什么？是在一个已经具备通用能力的模型之上，搭建一套“让它能完成具体任务”的系统。这套系统包括：怎么把用户需求翻译成模型能理解的指令、怎么让模型调用外部工具、怎么管理多轮对话的上下文、怎么在模型出错时补救。这些全是工程问题，是前端工程师的主场。

打个比方。训练模型像是造一台发动机，Agent 开发像是用这台发动机造一辆能上路的车。你不需要会造发动机，也能造出一辆好车，甚至很多好车的核心竞争力根本不在发动机，而在底盘调校、内饰设计、驾驶体验。Agent 产品的竞争力，同样大量体现在工程细节上。

提示：如果你现在还在纠结“要不要先学 PyTorch”，先停下来问自己一个问题——你的目标是让模型本身变强，还是让模型帮你把一件事做完？如果是后者，你大概率不需要碰训练。

2. Agent 的核心构成与前端能对应的概念

2.1 把 Agent 拆成四个可理解的模块

我不想用那种“感知-决策-执行”的学术框架来讲，太抽象。从工程实现角度看，一个能跑起来的 Agent 大致由四块组成，每一块都能在前端经验里找到对应物。

第一块是指令层，也就是系统提示词加上任务描述。它决定了模型“扮演什么角色、遵守什么规则、输出什么格式”。这有点像你写一个组件的 props 定义和类型约束，只不过约束对象从数据变成了模型的行为。

第二块是工具层，也就是模型可以调用的外部能力。查数据库、发请求、读写文件、调用某个计算函数，都属于工具。前端熟悉的“封装一个函数供别人调用”，在这里变成了“封装一个函数供模型调用”，区别只在于调用方从代码变成了模型。

第三块是记忆层，负责管理上下文。短期记忆是当前对话的历史，长期记忆可能是向量库或者结构化存储。这跟前端的状态管理非常像——你得决定哪些状态放本地、哪些放全局、哪些要持久化。

第四块是编排层，也就是控制整个循环的逻辑。模型输出一个动作，系统执行它，把结果喂回去，模型再决定下一步，直到任务完成。这就是一个带条件判断和循环的异步流程，用前端的话说，是一个复杂的状态机。

把这四块拆开之后你会发现，没有一块是“必须懂模型训练”才能做的。工具层和编排层几乎纯工程，记忆层涉及一点数据结构和检索概念，指令层需要的是对任务的理解和文字表达能力。

2.2 工具调用：Agent 真正区别于聊天机器人的地方

普通对话应用和 Agent 最大的分水岭，就是工具调用。一个只会聊天的模型，你问它“今天天气怎么样”，它只能根据训练数据瞎猜。一个能调工具的 Agent，会去调用一个天气查询接口，把真实结果拿回来再回答你。

工具调用的实现机制，简单说就是：你在请求里告诉模型“你有这些工具可用，每个工具叫什么、干什么、需要什么参数”，模型在需要的时候会返回一个结构化的调用请求，你的代码解析这个请求、执行对应函数、把结果再发回给模型。整个过程模型不直接执行任何代码，它只是“说”它想调用什么，真正执行的是你的程序。

这个设计非常关键，因为它把“决策”和“执行”分开了。模型负责决策，你的代码负责执行。这意味着安全边界掌握在你手里——模型想调用一个删除数据的工具，你完全可以在执行前拦截、确认或者拒绝。

前端工程师做这一块有天然优势。工具本质上就是一个个封装好的函数，参数校验、错误处理、返回值格式化，这些是写业务代码时的日常。你唯一需要额外注意的是，工具的“描述”要写得让模型能看懂，这跟写一份好的函数注释是一个道理，只不过读者从人变成了模型。

2.3 记忆管理：比想象中更需要工程取舍

记忆这块是最容易被低估的。新手常见的做法是把所有历史对话一股脑塞进上下文，结果就是 token 消耗飞快、模型注意力被稀释、响应变慢。真正做产品时，记忆管理是一道必须精打细算的工程题。

短期记忆的处理，核心是“保留什么、丢弃什么、压缩什么”。常见策略有几种：滑动窗口只保留最近 N 轮、对早期对话做摘要压缩、按重要性打分保留关键信息。这跟前端做长列表虚拟滚动的思路异曲同工——你不可能把所有 DOM 都渲染出来，得决定哪些在视口内、哪些回收、哪些缓存。

长期记忆则涉及检索。把历史信息存进向量库，需要时按语义相似度召回。这里前端要理解的核心概念是“嵌入”，也就是把一段文字变成一串数字向量，语义相近的文字向量距离也近。检索时把当前问题也转成向量，找最接近的历史片段。这套东西听起来玄，但用起来就是调几个 API 的事。

注意：记忆不是越多越好。我踩过的坑是早期把所有历史都塞进去，结果模型开始“翻旧账”，把不相关的早期对话当成当前任务的约束。后来改成按相关性召回，效果立刻稳定了。

3. 从零搭一个最小可用 Agent 的实操路径

3.1 环境与依赖准备

先说清楚，这一节讲的是“最小可用”，目标是让你在一个下午内跑通一个能调工具的 Agent，不追求生产级健壮性。技术栈我选最常见的组合：Node.js 环境加一个通用大模型的 API。

依赖方面其实很轻。你需要一个 HTTP 请求库（Node 18 以上自带 fetch，够用）、一个环境变量管理工具（dotenv 之类）、以及可选的向量库客户端（如果要做长期记忆）。不需要任何深度学习框架，不需要 GPU，一台普通开发机足够。

API Key 的管理要养成习惯，放环境变量，别硬编码。我见过太多人把 key 直接写进前端代码然后提交到仓库，这是低级但致命的错误。哪怕是本地 demo，也请从第一天就规范起来。

# 项目初始化 npm init -y npm install dotenv # 如果要做长期记忆，再加向量库客户端

环境变量文件里放两样东西：模型 API 的地址和密钥。不同服务商的字段名不一样，按文档填即可。这里不展开具体服务商，因为接口形态大同小异，你换成任何一家逻辑都一样。

3.2 定义工具与工具描述

工具的定义是 Agent 开发里最需要“手感”的部分。我建议从两个最简单的工具开始：一个查时间的，一个做数学计算的。别小看这两个，它们能覆盖“模型需要外部信息”和“模型需要精确计算”两种典型场景。

工具定义通常包含三部分：名称、自然语言描述、参数结构。名称要短且语义明确，描述要写清楚“什么时候该用它”，参数结构用 JSON Schema 描述。这里的关键经验是：描述的质量直接决定模型调用的准确率。描述写得含糊，模型就会在该调用的时候不调用，或者在不该调用的时候乱调用。

const tools = [ { name: "get_current_time", description: "获取当前系统时间，当用户询问现在几点、今天日期时使用", parameters: { type: "object", properties: { timezone: { type: "string", description: "时区，例如 Asia/Shanghai，默认使用本地时区" } }, required: [] } }, { name: "calculate", description: "执行数学计算，当需要进行加减乘除或复杂表达式求值时使用", parameters: { type: "object", properties: { expression: { type: "string", description: "要计算的数学表达式，例如 (3+5)*2" } }, required: ["expression"] } } ];

写完工具定义后，我强烈建议你手动测几个边界情况。比如问“现在几点”，看模型是否调用时间工具；问“1+1等于几”，看它是直接回答还是调用计算工具。这个测试过程能帮你快速建立对模型行为的直觉。

3.3 编排循环的实现

编排循环是整个 Agent 的心脏。它的逻辑用伪代码说就是：把用户输入和工具定义发给模型，如果模型返回的是普通文本就结束，如果返回的是工具调用请求就执行工具、把结果追加到对话里、再发给模型，如此循环直到模型给出最终回答或达到最大轮数。

这里有几个工程细节必须处理。第一是最大循环次数，一定要设上限，否则模型可能陷入无限调用。第二是工具执行异常，工具报错时不能直接崩溃，要把错误信息作为结果返回给模型，让它自己决定怎么办。第三是消息格式，不同模型对工具调用结果的消息格式要求不同，要严格按文档来。

async function runAgent(userInput, maxTurns = 10) { const messages = [ { role: "system", content: "你是一个助手，可以调用工具来完成任务。" }, { role: "user", content: userInput } ]; for (let turn = 0; turn < maxTurns; turn++) { const response = await callModel(messages, tools); // 模型没有调用工具，直接返回文本，结束 if (!response.toolCalls || response.toolCalls.length === 0) { return response.content; } // 把模型的工具调用请求加入对话 messages.push(response.rawMessage); // 逐个执行工具 for (const call of response.toolCalls) { let result; try { result = await executeTool(call.name, call.arguments); } catch (err) { result = `工具执行失败：${err.message}`; } messages.push({ role: "tool", toolCallId: call.id, content: JSON.stringify(result) }); } } return "达到最大循环次数，任务未完成。"; }

这段代码不长，但它就是 Agent 的骨架。你后面加的所有能力——记忆、多工具、反思——都是在这个循环上做加法。我建议你先把这段跑通，观察模型在每一步的输入输出，建立对“模型如何决策”的直观感受。

3.4 参数选择与成本控制

跑通之后，下一步是控制成本。Agent 因为有多轮循环，token 消耗比单轮对话高得多。一个任务如果循环五轮，每轮都带上完整历史，消耗可能是单轮的十几倍。

控制手段有几个。一是精简系统提示词，别写一大堆没用的角色设定。二是控制历史长度，超过一定轮数就做摘要或截断。三是工具结果瘦身，工具返回的数据如果很大，先做过滤再喂给模型，别把整个数据库查询结果塞进去。四是选择合适的模型档位，简单任务用便宜的小模型，复杂任务再上大模型。

我实测下来，一个设计良好的 Agent，单次任务成本能控制在单轮对话的三到五倍以内。如果超过十倍，通常是历史管理出了问题，值得回头检查。

4. 实操中绕不开的坑与排查思路

4.1 模型不调用工具怎么办

这是新手遇到的第一个高频问题。你明明定义了工具，模型却自顾自地用训练知识回答。原因通常有三个：工具描述不够明确、系统提示词没有引导、或者模型本身能力不足。

排查顺序我建议这样走。先看工具描述，是不是写得太笼统，比如“查询信息”这种描述模型根本不知道什么时候用。改成“当用户询问订单状态时，用订单号查询订单信息”这种具体描述，命中率立刻上升。再看系统提示词，加一句“当需要外部信息或精确计算时，优先调用工具而不是凭记忆回答”。最后如果还不行，考虑换一个工具调用能力更强的模型。

还有一个隐蔽的坑：有些模型在对话历史很长时会“忘记”工具的存在。解决办法是在每轮请求里都重新带上工具定义，别只在第一轮带。

4.2 工具调用参数错误怎么处理

模型生成的参数经常有格式问题，比如该传数字传了字符串、该传数组传了对象。这时候不要直接抛错，而是把校验失败的信息返回给模型，让它重新生成。模型看到“参数 expression 必须是字符串，你传了数字”这种反馈，通常能自己纠正。

更稳妥的做法是在工具执行前加一层参数校验和转换。比如用 JSON Schema 校验，失败就返回错误信息；能自动转换的就转换，比如把字符串数字转成数字。这层校验是纯工程活，前端写表单校验的经验直接能用上。

提示：把工具执行的所有输入输出都打日志。Agent 出问题时，日志是你唯一的线索。我习惯把每轮的模型输出、工具调用、工具结果都记下来，排查效率能提升好几倍。

4.3 循环停不下来或提前结束

循环停不下来，通常是模型反复调用同一个工具却拿不到满意结果。这时候最大轮数限制就是你的安全网。但光限制不够，还要在提示词里告诉模型“如果工具多次返回相同结果，说明此路不通，请换思路或直接告知用户”。

提前结束则相反，模型还没完成任务就给出了最终回答。这往往是因为系统提示词里没有明确“任务完成的判断标准”。加一句“只有当用户的问题被完整回答后，才输出最终答案”能缓解不少。

4.4 常见问题速查表

这张表是我自己踩坑踩出来的，基本覆盖了入门阶段八成的报错场景。遇到问题先对号入座，能省不少瞎试的时间。

5. 前端工程师做 Agent 的独特优势与能力补全

5.1 你已经具备的工程能力

很多前端同行低估了自己。做 Agent 需要的核心能力里，有一大半是前端日常就在练的。

异步编排能力。Agent 的循环本质是异步流程控制，处理 Promise、管理并发、做错误重试，这些是前端的基本功。状态管理能力。Agent 的上下文管理就是状态管理，什么时候更新、什么时候清理、怎么保证一致性，思路完全相通。接口封装能力。工具就是接口，参数校验、错误处理、返回值格式化，你写业务代码时天天在做。用户体验能力。Agent 的不确定性需要 UI 来兜底，加载态、流式输出、错误提示、人工确认，这些是前端的看家本领。

我甚至觉得，一个工程能力扎实的前端，转做 Agent 应用比一个只会调模型的算法同学更快出成果。因为 Agent 产品的成败，工程细节占的比重远大于模型本身。

5.2 需要补的三块知识

当然也有要补的。第一块是提示词工程，也就是怎么把任务描述清楚、怎么约束输出格式、怎么引导模型行为。这东西没有理论门槛，靠的是大量实践和总结，写多了自然有手感。

第二块是检索相关的基础概念，主要是嵌入和向量检索。不需要深入数学原理，理解“文字转向量、相似度匹配、召回排序”这套流程就够了。用起来就是调 API。

第三块是评估方法。Agent 的输出不确定，怎么判断它做得好不好？你需要建立一套评估集，准备一批典型任务，每次改动后跑一遍看通过率。这是从“能跑”到“可靠”的关键一步，也是很多个人开发者忽略的地方。

5.3 一个务实的进阶路线

如果你现在完全没碰过，我建议的路线是这样。第一步，跑通单轮对话，理解请求响应格式。第二步，加上工具调用，跑通最小 Agent 循环。第三步，加记忆管理，处理多轮任务。第四步，建立评估集，开始迭代优化。第五步，再考虑多 Agent 协作、复杂规划这些高级话题。

每一步都别跳。我见过太多人一上来就想做多 Agent 系统，结果连单 Agent 的工具调用都没调稳，最后卡在半路。Agent 开发的复杂度是叠加的，地基不稳，上面盖得越高越容易塌。

6. 关于 Agent 开发边界的一些个人判断

6.1 什么任务适合做成 Agent

不是所有任务都值得做成 Agent。我的判断标准是：任务是否有明确的步骤、是否需要外部信息或工具、是否允许一定的试错。三个都满足，适合做 Agent。比如“帮我查一下最近的订单并整理成表格”，有步骤、要查数据、允许重试，很适合。

反过来，如果任务是开放式的创意写作，或者对准确性要求极高不容出错，Agent 的自主性反而会带来麻烦。这种场景老老实实用单轮对话加人工审核更稳妥。

6.2 不要过度神化 Agent 的自主性

现在有一种风气，把 Agent 说得好像能完全自主完成一切。实际做下来你会发现，可靠的 Agent 都是“约束出来的”，不是“放养出来的”。你得给它清晰的工具、明确的边界、严格的格式要求，它才能稳定工作。自由度越高，不确定性越大。

所以我在设计 Agent 时，倾向于把大任务拆成小步骤，每一步都给明确的输入输出约束。这跟前端做复杂表单的思路一样——与其让用户自由输入然后各种校验，不如用分步引导把可能性收窄。

6.3 模型能力提升会改变什么、不会改变什么

模型能力在快速提升，这是事实。工具调用的准确率、长上下文的理解力、多步推理的稳定性，都在变好。这意味着一些现在需要靠工程手段硬补的短板，未来可能模型自己就解决了。

但有些东西不会变。任务拆解、边界定义、错误兜底、用户体验，这些是产品层面的工程问题，模型再强也需要有人来做。模型越强，Agent 能做的事越多，反而越需要工程手段来保证它做得对、做得稳。所以前端工程师在这个领域的价值，不会因为模型变强而消失，只会从“补模型的短板”转向“放大模型的能力”。

我个人的体会是，与其焦虑模型会不会取代什么，不如把精力放在理解模型的行为模式上。你越懂它在什么情况下会出错、为什么会出错，你就越能设计出可靠的系统。这种理解，只能靠动手做、靠踩坑积累，看再多文章也替代不了。

最后分享一个我一直在用的小习惯：每做一个 Agent，我都会建一个“失败案例库”，把每次它做错的输入输出记下来。这个库比任何教程都有价值，因为它记录的是真实系统在真实场景下的边界。等你积累到几十条，你会发现自己对 Agent 的理解已经超过大多数只停留在概念层面的人了。