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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 完成账号注册后进入控制台。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在这里你能看到账户余额、调用统计和模型列表。接着去 API Keys 页面创建密钥地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 点创建后把 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_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 在网页里直接发几条消息确认模型响应正常再回到代码里接入。这一步能帮你排除「是通道问题还是代码问题」。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_URLhttps://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.jsimport { 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/completionsVite 会代理到 TaoTokenKey 留在 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/apirewrite是否把前缀去掉了。如果你在浏览器直接请求还会遇到 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/apiKey 填你的 API KeyModel 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_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合持续性的开发场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言的请求示例和参数说明遇到接口细节可以直接查。API Keys 管理页还是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 需要新建或轮换密钥时从这里进。最后给你一个实用技巧把模型 ID 做成配置项而不是硬编码这样你可以在不改业务代码的情况下切换模型做对比。前端项目里可以放一个models.js导出候选列表请求失败时自动降级到备用模型这对线上稳定性帮助很大。通道统一之后切换成本就是改一个字符串这是统一 Key 接入最实在的好处。