企业官网建设流程全解析

1. 前端做 AI Agent 智能体，先搞清楚要补哪些课

前端开发 AI Agent 智能体，本质上是把「会补全文本的大模型」接进你熟悉的 JS/TS 工程里，再给它加上工具调用、上下文管理和流式输出。它不是什么新语言，而是你现有技能栈的一次横向扩展：你写 React 的状态管理、写 Node 的接口封装、写 Promise 的异步编排，这些经验全都能直接迁移过来。适合谁？适合已经能独立写前端项目、想把手里的页面变成「能自己判断、自己调工具」的开发者。

我先把知识地图摊开，你对照着看自己缺哪块。第一层是 LLM 基础认知：大模型的核心机制是预测下一个词，它不理解语义，只是在你给的上下文里做概率补全。你提示词写得越具体，它补全得越准。第二层是 Prompt Engineering，也就是怎么把用户输入包装成模型能稳定执行的指令，包括角色约束、输出格式约束、思维链引导。第三层是工程框架，前端首选 LangChain.js，它的 LangGraph 用来编排 Agent 工作流，LangSmith 用来追踪每一步的输入输出。第四层是 RAG 检索增强，把私有资料转成向量存进向量库，提问时先检索再生成。第五层是 Agent 本体结构：LLM 负责思考、workflow 负责节点流转、tools 负责调外部服务、memory 负责记住上下文。第六层是 MCP 协议，让模型用统一方式调用第三方能力。第七层是多模态，处理图片、PDF、音视频的输入输出。

这些概念听着多，但落到代码上，最小可用的智能体只需要三样东西：一个能发请求的模型通道、一段能描述工具的 JSON、一个能循环「模型输出→判断是否调工具→把结果塞回上下文」的循环。你不需要一次学完，先把通道跑通，再逐步加工具、加记忆、加检索。

这里有个前端容易踩的认知坑：很多人以为 Agent 是「模型自己变聪明了」，其实不是。Agent 的智能来自你给它的工具描述和流程约束。模型只负责在每一步选择「下一步该调哪个工具、传什么参数」，真正的业务逻辑还是你写的函数。所以前端做 Agent 的优势在于，你本来就在写各种 API 封装和状态流转，把这些函数注册成工具，模型就能调用它们。

再说说为什么需要统一 Key 接入。前端项目里如果每个模型、每个工具都单独配一套鉴权和 Base URL，环境变量会迅速膨胀，本地、测试、生产三套环境同步起来非常痛苦。用 TaoToken 这类统一通道，你只需要维护一个 Base URL 和一个 Key，切换模型只改 Model ID，这对前端多环境部署特别友好。下面我就从环境准备开始，带你跑通第一个能对话的最小智能体。

2. TaoToken 统一 Key 接入前置准备

在写 Agent 循环之前，先把模型通道打通。这一步的目标是：拿到一个 Base URL、一个 API Key、一个可用的 Model ID，然后用最少的代码验证通道是活的。TaoToken 在这里扮演的是统一入口的角色，你不需要为每个模型单独申请账号，一个 Key 就能访问多种模型，这对前端做多模型对比、做降级兜底非常实用。

先注册并登录控制台。打开官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，完成账号注册后进入控制台。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，在这里你能看到账户余额、调用统计和模型列表。接着去 API Keys 页面创建密钥，地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，点创建后把 Key 复制下来，注意它只显示一次，丢了只能重建。

拿到 Key 之后，记住两个固定值：Base URL 是https://taotoken.net/api，这个地址不加任何查询参数，直接作为请求前缀。Model ID 根据你要用的模型填，比如对话场景常用的通用模型 ID，具体以控制台模型列表里显示的为准。这三个值就是前端 Agent 的全部鉴权信息，后面所有配置都围绕它们展开。

为什么强调「统一」？因为前端项目通常有.env.development、.env.production多套环境文件，如果每个模型一套 Key，你就要在每套文件里维护多组变量，CI 里还要注入多份密钥。统一通道后，你只需要在每套环境里放同一个TAOTOKEN_API_KEY，模型切换通过代码里的 Model ID 参数控制，环境文件保持干净。这对团队协作也友好，新人拉下代码只需要配一个 Key 就能跑。

安全上提醒一句：Key 不要写进前端打包产物。浏览器里直接暴露 Key 等于把账户交出去。正确做法是前端请求你自己的后端，由后端持有 Key 去调模型；或者本地开发时用 Node 脚本、Vite 的 server 中间件代理。下面配置片段我会用 Node 环境变量演示，你迁移到自己的后端或代理层即可。

如果你还没决定用哪个模型，可以先去模型对话页面试一下手感，地址是 https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite ，在网页里直接发几条消息，确认模型响应正常，再回到代码里接入。这一步能帮你排除「是通道问题还是代码问题」。

3. 可复制的环境变量与请求配置片段

这一节给你可以直接抄的配置。先建一个 Node 项目，安装依赖：

mkdir frontend-agent-demo && cd frontend-agent-demo npm init -y npm install openai dotenv

这里用openai这个 SDK，是因为它兼容 OpenAI 风格的接口，TaoToken 的 API 也遵循这套格式，所以 Base URL 一换就能用。接着创建.env文件：

TAOTOKEN_API_KEY=你的APIKey TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_MODEL=你的ModelID

注意 Base URL 结尾不要带斜杠，SDK 会自己拼接路径。然后写一个client.js，把客户端初始化封装好：

import 'dotenv/config'; import OpenAI from 'openai'; export const client = new OpenAI({ apiKey: process.env.TAOTOKEN_API_KEY, baseURL: process.env.TAOTOKEN_BASE_URL, }); export const MODEL = process.env.TAOTOKEN_MODEL;

如果你用 TypeScript，把process.env的类型补一下即可，逻辑一样。前端项目里如果要在 Vite 中调用，建议走服务端代理，配置vite.config.js：

import { defineConfig } from 'vite'; export default defineConfig({ server: { proxy: { '/api/llm': { target: 'https://taotoken.net/api', changeOrigin: true, rewrite: (path) => path.replace(/^\/api\/llm/, ''), headers: { Authorization: `Bearer ${process.env.TAOTOKEN_API_KEY}`, }, }, }, }, });

这样前端请求/api/llm/chat/completions，Vite 会代理到 TaoToken，Key 留在 Node 侧不暴露。生产环境换成你自己的网关做同样的事。

接下来定义工具。Agent 的工具就是一个带描述和参数结构的对象，模型根据描述决定调不调。写一个查询天气的假工具：

export const tools = [ { type: 'function', function: { name: 'get_weather', description: '查询指定城市的当前天气，当用户询问天气时调用', parameters: { type: 'object', properties: { city: { type: 'string', description: '城市名称，例如 北京' }, }, required: ['city'], }, }, }, ]; export async function runTool(name, args) { if (name === 'get_weather') { return JSON.stringify({ city: args.city, weather: '晴', temp: 24 }); } return JSON.stringify({ error: 'unknown tool' }); }

工具描述要写清楚「什么时候调用」，这是模型判断的依据。参数用 JSON Schema 描述，模型会按这个结构生成参数。到这里，通道、客户端、工具三件套就齐了，下一节写循环把它们串起来。

4. 跑通一次对话请求并验证成功结果

现在写 Agent 主循环。核心逻辑是：把用户消息和工具定义发给模型，模型如果返回tool_calls，就执行工具、把结果作为tool角色消息追加进上下文，再发一次；如果模型直接返回文本，就结束。代码：

import { client, MODEL } from './client.js'; import { tools, runTool } from './tools.js'; async function chat(userInput) { const messages = [ { role: 'system', content: '你是一个前端助手，需要天气信息时调用工具。' }, { role: 'user', content: userInput }, ]; while (true) { const res = await client.chat.completions.create({ model: MODEL, messages, tools, stream: false, }); const msg = res.choices[0].message; messages.push(msg); if (!msg.tool_calls || msg.tool_calls.length === 0) { console.log('最终回答：', msg.content); return msg.content; } for (const call of msg.tool_calls) { const args = JSON.parse(call.function.arguments); const result = await runTool(call.function.name, args); messages.push({ role: 'tool', tool_call_id: call.id, content: result, }); } } } chat('北京今天天气怎么样？');

运行node agent.js，你会看到模型先返回一个tool_calls，里面是get_weather和{"city":"北京"}，然后你的runTool返回天气数据，模型拿到后再生成一句自然语言回答。这个过程就是 Agent 的最小闭环：模型决策、工具执行、结果回填、模型总结。

验证成功的标志有三个：第一，控制台打印出最终回答，且内容里包含你工具返回的天气信息；第二，如果你在runTool里加一行console.log，能看到它被调用了一次；第三，把用户输入改成「你好」，模型不会调工具，直接返回文本。这三个现象都出现，说明通道、工具调用、循环逻辑全部正常。

流式响应是前端体验的关键。把stream: true打开，然后逐块读取：

const stream = await client.chat.completions.create({ model: MODEL, messages, tools, stream: true, }); for await (const chunk of stream) { const delta = chunk.choices[0]?.delta; if (delta?.content) process.stdout.write(delta.content); }

注意流式模式下工具调用的增量是分片返回的，你需要把delta.tool_calls按 index 累积拼接，等流结束后再解析完整参数。前端展示时，文本增量直接渲染，工具调用等拼接完再执行。这一步跑通，你的智能体就能在页面上一个字一个字往外蹦了。

5. 本篇常见报错排查

接入过程里最容易撞的几个错，我按真实报错信息给你对照。

第一个是401 Unauthorized或invalid api key。原因通常是 Key 复制时带了空格、.env没被加载、或者请求头没带上。排查顺序：先确认dotenv/config在文件顶部导入；再打印process.env.TAOTOKEN_API_KEY的前几位看是否为空；最后检查 Base URL 是不是写成了带/v1的地址。TaoToken 的 Base URL 就是https://taotoken.net/api，不要自己加后缀。

第二个是local proxy failed或连接被拒。这通常出现在 Vite 代理配置里，target写错或者changeOrigin没开。检查target是否是https://taotoken.net/api，rewrite是否把前缀去掉了。如果你在浏览器直接请求，还会遇到 CORS，这时候必须走代理或后端，不要试图在前端直连。

第三个是reading 'choices'报错，比如Cannot read properties of undefined (reading 'choices')。这说明返回体结构和你预期不符，常见于请求失败但你没检查状态码。在create外面包一层 try/catch，把error.response?.data打出来，通常能看到真实原因，比如模型 ID 写错、余额不足、参数不合法。

第四个是工具调用相关：模型返回了tool_calls，但你执行后报tool_call_id不匹配。检查你追加的tool消息里tool_call_id是否和call.id完全一致，一个字符都不能差。另外，messages数组的顺序必须是 assistant 的 tool_calls 消息在前，tool 结果在后，顺序错了模型会拒绝。

第五个是流式模式下delta.content一直为空。这往往是因为模型这一轮返回的是工具调用而不是文本，delta里只有tool_calls。你需要判断delta.tool_calls是否存在并累积，等流结束后统一处理，而不是只盯着content。

如果你用的是 Claude Code 这类工具做本地开发，配置里同样要写全三件套：Base URL 填https://taotoken.net/api，Key 填你的 API Key，Model ID 填控制台里的模型标识。三者缺一，或者 Model ID 用了别的平台的命名，都会报鉴权或模型不存在。Cline、CC Switch 这类插件也是同样的三件套逻辑，配置项名称不同但值一致。

排查时养成一个习惯：先用模型对话页面发一条消息，确认账号和模型没问题；再用 curl 或 Node 脚本发一条最小请求，确认代码没问题；最后才上框架。这样能把问题范围快速缩小到某一层。

6. 继续深入的方向与接入入口

最小智能体跑通后，你可以按需往上叠能力。想让它记住多轮对话，就把messages持久化到数据库或 localStorage，每次请求带上历史。想让它查私有资料，就加 RAG：把文档切片、调 embedding 接口转成向量、存进向量库，提问时先检索再拼进 prompt。想让它调更多外部服务，就按第 3 节的工具格式继续注册函数，或者用 MCP 协议把第三方能力标准化接入。

前端做 Agent 的长期价值在于交互层。模型能力会越来越强，但用户怎么和 Agent 协作、怎么展示中间步骤、怎么在流式输出里插入工具执行状态，这些体验问题最终都要前端解决。你现在的 JS 异步编排、状态管理、组件渲染经验，在这个方向上全是硬通货。

如果你准备把 Agent 用到长期编码或自动化任务里，可以了解 Coding Plan，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它更适合持续性的开发场景。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各语言的请求示例和参数说明，遇到接口细节可以直接查。API Keys 管理页还是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，需要新建或轮换密钥时从这里进。

最后给你一个实用技巧：把模型 ID 做成配置项而不是硬编码，这样你可以在不改业务代码的情况下切换模型做对比。前端项目里可以放一个models.js导出候选列表，请求失败时自动降级到备用模型，这对线上稳定性帮助很大。通道统一之后，切换成本就是改一个字符串，这是统一 Key 接入最实在的好处。