1. 独立开发者做 Agent为什么总卡在“能跑 Demo 但上不了线”我见过太多 Agent 项目停在 Demo 阶段本地跑得挺欢一部署就各种问题。不是模型调用超时就是沙箱环境跑不起来再不然就是 Key 管理混乱导致成本失控。这个场景的核心矛盾在于——Agent 的难点从来不是 prompt而是工程化。你想想一个能上线的 Agent 应用至少需要这几层前端交互层负责流式展示消息和工具调用状态API 层处理鉴权和请求编排模型接入层统一管理多家模型厂商的 Key 和协议差异沙箱执行层让 Agent 能安全地跑代码数据持久层记录对话历史和 Token 消耗。每一层单独看都不复杂但拼在一起就是一堆 dirty work。我试过用 Next.js TypeScript 做骨架AI SDK 做模型编排E2B 做代码沙箱这套组合对独立开发者来说开发效率最高。但模型接入这块一直是个痛点OpenAI 兼容协议要配一套Anthropic 要配另一套用户想 BYOK 还得让他在前端填 Key安全和成本都难控制。TaoToken 在这里的价值就体现出来了它提供一个统一的 API 通道兼容 OpenAI 协议同时能路由到不同模型。你只需要在服务端配一个 Key前端不用暴露任何厂商密钥模型切换只改一个 model ID 就行。对于独立开发者来说这省掉了自己搭模型网关的功夫。这篇文章我会带你从零搭一条可部署的 Agent 最小闭环Next.js 项目初始化、TaoToken Key 配置、AI SDK 接入、E2B 沙箱执行、端到端验证。每一步都有可复制的代码和配置你跟着做就能跑通。适合谁看有 TypeScript 基础、想快速上线 Agent 产品的独立开发者正在选型 Agent 技术栈的产品技术负责人已经会用 AI SDK 但想统一模型接入层的工程师。2. TaoToken 统一 Key 接入前置准备从注册到拿到 API Key在开始写代码之前你需要先把 TaoToken 的 API Key 拿到手。这一步很快但有几个细节不注意后面会踩坑。2.1 注册与创建 API Key打开 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号后进入控制台。在控制台左侧找到「API Keys」页面点击创建新的 Key。创建时建议给 Key 起一个能区分用途的名字比如agent-dev-local这样后面如果有多个环境本地开发、预发布、生产不会搞混。创建完成后你会看到一串以sk-开头的字符串这就是你的 API Key。注意这个 Key 只在创建时完整显示一次关掉页面就看不到了所以先复制到安全的地方。2.2 确认 Base URL 和可用模型TaoToken 的 API 端点地址是https://taotoken.net/api这个地址兼容 OpenAI 的/v1/chat/completions接口规范。也就是说任何支持 OpenAI 协议的 SDK 或工具只需要把 Base URL 改成这个地址再把 API Key 换成 TaoToken 的 Key就能直接调用。你可以在控制台的「模型对话」页面先测试一下模型是否可用。选一个模型比如 Claude 系列或 GPT 系列发一条测试消息确认返回正常。这一步能帮你排除 Key 权限或余额问题。2.3 环境变量规划在 Next.js 项目里API Key 必须放在服务端环境变量中绝对不能暴露给浏览器。我建议在项目根目录创建.env.local文件写入以下内容# TaoToken 统一 API 配置 TAOTOKEN_API_KEYsk-你的实际Key TAOTOKEN_BASE_URLhttps://taotoken.net/api # E2B 沙箱配置后面会用到 E2B_API_KEY你的E2B_Key # 数据库连接可选用于持久化 DATABASE_URLpostgresql://user:passwordlocalhost:5432/agent_db注意.env.local要加到.gitignore里避免 Key 被提交到仓库。如果你用 Vercel 部署在项目设置的 Environment Variables 里配置同样的变量即可。2.4 为什么不用多个厂商 Key 分别配有人可能会想我直接配 OpenAI 的 Key 和 Anthropic 的 Key 不就行了为什么要走统一通道原因有三个。第一多厂商 Key 意味着多套鉴权逻辑、多套错误处理、多套计费统计代码复杂度翻倍。第二用户 BYOK 场景下你让用户填多个 Key 体验很差而且 Key 存在前端或数据库都有安全风险。第三模型切换时你要改的不只是 model ID还有 Base URL 和鉴权头容易出错。用 TaoToken 统一 Key 之后你的模型调用代码只需要维护一个 client 实例切换模型只改model参数。这对独立开发者来说省掉的是实打实的维护成本。3. Next.js AI SDK 可复制配置项目骨架与模型接入代码这一节是核心我会给出完整的项目目录结构、依赖安装命令、以及 AI SDK 接入 TaoToken 的可复制代码。你照着做就能跑起来。3.1 项目初始化与依赖安装先用create-next-app创建项目pnpm create next-applatest agent-stack --typescript --tailwind --eslint --app --src-dir --import-alias /* cd agent-stack然后安装核心依赖pnpm add ai ai-sdk/openai ai-sdk/anthropic e2b e2b/code-interpreter pnpm add -D types/node这里说明一下各包的作用ai是 Vercel AI SDK 的核心包提供流式响应和工具调用能力ai-sdk/openai是 OpenAI 兼容协议的 providerTaoToken 走这个ai-sdk/anthropic用于 Anthropic 协议的原生支持e2b和e2b/code-interpreter是沙箱执行环境。3.2 项目目录结构我建议的目录结构如下agent-stack/ ├── src/ │ ├── app/ │ │ ├── api/ │ │ │ └── chat/ │ │ │ └── route.ts # Agent 主入口 │ │ ├── page.tsx # 前端页面 │ │ └── layout.tsx │ ├── lib/ │ │ ├── ai-client.ts # TaoToken 统一 client │ │ ├── tools.ts # Agent 工具定义 │ │ └── sandbox.ts # E2B 沙箱封装 │ └── components/ │ └── chat.tsx # 聊天 UI 组件 ├── .env.local ├── next.config.js ├── package.json └── tsconfig.json这个结构把模型接入、工具定义、沙箱执行分开后面扩展多 Agent 或加新工具时不会乱。3.3 TaoToken 统一 Client 配置在src/lib/ai-client.ts中创建统一 clientimport { createOpenAI } from ai-sdk/openai; import { createAnthropic } from ai-sdk/anthropic; // TaoToken 走 OpenAI 兼容协议 export const taotokenClient createOpenAI({ baseURL: process.env.TAOTOKEN_BASE_URL ?? https://taotoken.net/api, apiKey: process.env.TAOTOKEN_API_KEY, }); // 如果需要 Anthropic 原生协议也可以用同一个 Key export const anthropicClient createAnthropic({ baseURL: process.env.TAOTOKEN_BASE_URL ?? https://taotoken.net/api, apiKey: process.env.TAOTOKEN_API_KEY, }); // 模型 ID 集中管理切换模型只改这里 export const MODELS { fast: gpt-4o-mini, balanced: claude-3-5-sonnet-20241022, powerful: gpt-4o, } as const;这里的关键点是baseURL指向 TaoToken 的 API 地址apiKey用环境变量注入。模型 ID 集中在一个对象里后面 Agent 路由时根据任务复杂度选不同模型。3.4 Agent 工具定义与沙箱执行在src/lib/tools.ts中定义 Agent 可调用的工具import { tool } from ai; import { z } from zod; import { runInSandbox } from ./sandbox; export const executeCode tool({ description: 在沙箱中执行 Python 代码并返回结果, parameters: z.object({ code: z.string().describe(要执行的 Python 代码), }), execute: async ({ code }) { const result await runInSandbox(code); return { stdout: result.stdout, stderr: result.stderr, error: result.error, }; }, }); export const tools { executeCode, };在src/lib/sandbox.ts中封装 E2B 沙箱import { Sandbox } from e2b/code-interpreter; export async function runInSandbox(code: string) { const sandbox await Sandbox.create({ apiKey: process.env.E2B_API_KEY, timeoutMs: 60_000, }); try { const execution await sandbox.runCode(code); return { stdout: execution.logs.stdout.join(\n), stderr: execution.logs.stderr.join(\n), error: execution.error?.value ?? null, }; } finally { await sandbox.kill(); } }注意沙箱用完要kill否则会一直占用资源。E2B 的免费额度有限生产环境建议加超时和并发控制。3.5 API Route 主入口在src/app/api/chat/route.ts中写 Agent 主逻辑import { streamText } from ai; import { taotokenClient, MODELS } from /lib/ai-client; import { tools } from /lib/tools; export const maxDuration 60; export async function POST(req: Request) { const { messages } await req.json(); const result streamText({ model: taotokenClient(MODELS.balanced), system: 你是一个数学建模助手。遇到需要计算的问题时调用 executeCode 工具在沙箱中运行 Python 代码。 不要自己心算复杂表达式一律用代码验证。, messages, tools, maxSteps: 5, }); return result.toDataStreamResponse(); }这段代码做了几件事接收前端消息、用 TaoToken client 调用模型、注入工具定义、允许最多 5 轮工具调用循环、返回流式响应。maxSteps: 5是防止 Agent 陷入无限工具调用循环。3.6 前端流式 UI在src/components/chat.tsx中用 AI SDK 的useChathookuse client; import { useChat } from ai/react; export function Chat() { const { messages, input, handleInputChange, handleSubmit } useChat({ api: /api/chat, }); return ( div classNameflex flex-col h-screen p-4 div classNameflex-1 overflow-y-auto space-y-4 {messages.map((m) ( div key{m.id} classNamep-3 rounded bg-gray-100 strong{m.role}:/strong p classNamewhitespace-pre-wrap{m.content}/p /div ))} /div form onSubmit{handleSubmit} classNameflex gap-2 mt-4 input value{input} onChange{handleInputChange} classNameflex-1 border p-2 rounded placeholder输入你的问题... / button typesubmit classNamebg-blue-500 text-white px-4 rounded 发送 /button /form /div ); }到这里一条完整的 Agent 链路就搭好了前端发消息 → API Route 接收 → TaoToken 调用模型 → 模型决定是否调工具 → E2B 沙箱执行代码 → 结果流式返回前端。4. 本地启动与端到端验证确认 Agent 闭环跑通代码写完了接下来要验证整条链路是否真的能跑通。这一步很多人会跳过结果部署后才发现问题。4.1 启动开发服务器确保.env.local里的三个变量都填好了然后运行pnpm dev打开http://localhost:3000你应该能看到聊天界面。如果页面报错先检查环境变量是否被正确加载。Next.js 的.env.local只在服务端生效前端代码里不能直接读process.env.TAOTOKEN_API_KEY。4.2 验证模型调用先发一条不需要工具的消息比如「你好介绍一下你自己」。如果模型正常返回说明 TaoToken 的 Key 和 Base URL 配置正确。如果这里报 401说明 Key 无效或没传对。检查.env.local里的TAOTOKEN_API_KEY是否以sk-开头以及createOpenAI的apiKey参数是否读到了环境变量。4.3 验证工具调用与沙箱执行发一条需要计算的消息比如「帮我算一下 1234 乘以 5678 等于多少用代码验证」。正常流程是模型识别到需要计算 → 调用executeCode工具 → E2B 沙箱执行 Python 代码 → 返回结果 → 模型整合结果回复你。你可以在终端看到 E2B 沙箱的创建和销毁日志。如果沙箱报错常见原因是E2B_API_KEY没配或额度用完。4.4 验证流式响应观察前端消息是不是逐字出现的。如果是整段突然出现说明流式没生效。检查route.ts里是否用了result.toDataStreamResponse()以及前端是否用了useChat的默认流式处理。4.5 端到端验证清单跑完上面几步后用这个清单确认闭环完整验证项预期结果失败排查方向模型基础对话正常返回文本检查 TaoToken Key 和 Base URL工具调用触发终端出现沙箱日志检查 tools 定义和 maxSteps沙箱代码执行返回计算结果检查 E2B Key 和超时设置流式输出逐字显示检查 toDataStreamResponse多轮工具调用Agent 能连续调工具检查 maxSteps 是否够大全部通过后你就有了一个可部署的 Agent 最小闭环。接下来可以加数据库持久化、加更多工具、加鉴权逐步往生产级靠。5. 本篇常见报错排查401、local proxy failed、reading choices 怎么解这一节整理我在搭建过程中真实遇到过的报错以及对应的排查思路。你如果卡住了先在这里找找。5.1 401 Unauthorized这是最常见的报错通常长这样AI_APICallError: Unauthorized原因一般是 Key 没传对。排查顺序第一确认.env.local里TAOTOKEN_API_KEY的值完整没有多余空格或换行第二确认createOpenAI的apiKey参数确实读到了环境变量可以在ai-client.ts里临时加一行console.log(process.env.TAOTOKEN_API_KEY?.slice(0, 8))确认第三确认 Base URL 是https://taotoken.net/api不要多加/v1或漏掉/api。5.2 local proxy failed这个报错通常出现在网络层Error: local proxy failed如果你在本地开发时遇到先检查是否能正常访问 TaoToken 的 API 地址。可以用 curl 测试curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:gpt-4o-mini,messages:[{role:user,content:hi}]}如果 curl 能通但应用报错检查 Next.js 的 fetch 配置或是否有其他中间件拦截了请求。5.3 reading choices of undefined这个报错说明返回结构不符合预期TypeError: Cannot read properties of undefined (reading choices)通常是因为模型返回了错误响应但代码直接去读choices字段。排查方法在route.ts里加错误捕获打印完整响应体。常见原因是模型 ID 写错了TaoToken 找不到对应模型返回了错误 JSON 而不是标准的 chat completion 结构。5.4 OAuth 相关报错如果你用了 Anthropic 原生协议可能会遇到OAuth error: invalid_client这是因为 Anthropic 的鉴权方式和 OpenAI 兼容协议不同。用 TaoToken 统一 Key 时建议优先走 OpenAI 兼容协议createOpenAI除非你需要 Anthropic 特有的功能比如 prompt caching。如果必须用 Anthropic 协议确认createAnthropic的apiKey和baseURL都配置正确。5.5 沙箱超时或创建失败E2B 沙箱报错通常是这两种SandboxError: Failed to create sandbox TimeoutError: Sandbox execution timed out创建失败先检查E2B_API_KEY是否有效、额度是否用完。超时的话把timeoutMs调大或者在代码里加超时处理逻辑。生产环境建议给沙箱执行加一个总时长限制避免用户提交死循环代码把额度跑光。5.6 工具调用不触发如果模型一直不调用工具只回复文本检查两点第一tools对象是否正确传给了streamText第二system prompt 里是否明确告诉模型「遇到计算问题必须调用工具」。有些模型对工具调用的触发比较保守需要在 prompt 里强调。6. 从最小闭环到生产级 Agent下一步该补什么跑通最小闭环之后你手里已经有一个能用的 Agent 了。但如果要真正上线给用户用还有几块需要补。第一块是持久化。现在对话记录只存在内存里刷新页面就没了。加 PostgreSQL Drizzle ORM把消息、工具调用记录、Token 消耗都存下来。这样既能做历史记录也能做成本分析。第二块是鉴权。现在任何人都能调你的 API Route上线前必须加用户登录和请求限流。可以用 Better Auth 快速接入或者在 API Route 里加一层中间件校验。第三块是观测。Agent 系统没有 observability 后期很难排查问题。建议接入 OpenTelemetry把模型调用、工具执行、沙箱创建都打上 trace。Langfuse 对 AI 产品很友好可以看每次调用的 Token 消耗和延迟。第四块是成本控制。TaoToken 控制台可以看用量但应用层最好也做一层预扣或限额。比如每个用户每天最多调多少次模型、沙箱执行最多多少秒避免被刷。如果你打算长期做 Agent 产品建议把模型调用层再抽象一层支持按任务复杂度动态选模型。简单任务用便宜模型复杂推理用强模型成本能降不少。TaoToken 的模型对话页面可以帮你快速测试不同模型的效果和响应速度选型时很有用。最后说一个我踩过的坑不要一上来就追求多 Agent 协作。单 Agent 工具调用能解决 80% 的场景多 Agent 的编排复杂度是指数级上升的。先把单 Agent 跑稳再考虑拆多个角色。代码仓库结构、环境变量、工具定义、沙箱封装这些你都可以直接复制到自己的项目里用。唯一需要改的是模型 ID 和 system prompt根据你的业务场景调整就行。
从0到1：用TaoToken统一Key搭建生产级Agent技术栈，独立开发者必备！
1. 独立开发者做 Agent为什么总卡在“能跑 Demo 但上不了线”我见过太多 Agent 项目停在 Demo 阶段本地跑得挺欢一部署就各种问题。不是模型调用超时就是沙箱环境跑不起来再不然就是 Key 管理混乱导致成本失控。这个场景的核心矛盾在于——Agent 的难点从来不是 prompt而是工程化。你想想一个能上线的 Agent 应用至少需要这几层前端交互层负责流式展示消息和工具调用状态API 层处理鉴权和请求编排模型接入层统一管理多家模型厂商的 Key 和协议差异沙箱执行层让 Agent 能安全地跑代码数据持久层记录对话历史和 Token 消耗。每一层单独看都不复杂但拼在一起就是一堆 dirty work。我试过用 Next.js TypeScript 做骨架AI SDK 做模型编排E2B 做代码沙箱这套组合对独立开发者来说开发效率最高。但模型接入这块一直是个痛点OpenAI 兼容协议要配一套Anthropic 要配另一套用户想 BYOK 还得让他在前端填 Key安全和成本都难控制。TaoToken 在这里的价值就体现出来了它提供一个统一的 API 通道兼容 OpenAI 协议同时能路由到不同模型。你只需要在服务端配一个 Key前端不用暴露任何厂商密钥模型切换只改一个 model ID 就行。对于独立开发者来说这省掉了自己搭模型网关的功夫。这篇文章我会带你从零搭一条可部署的 Agent 最小闭环Next.js 项目初始化、TaoToken Key 配置、AI SDK 接入、E2B 沙箱执行、端到端验证。每一步都有可复制的代码和配置你跟着做就能跑通。适合谁看有 TypeScript 基础、想快速上线 Agent 产品的独立开发者正在选型 Agent 技术栈的产品技术负责人已经会用 AI SDK 但想统一模型接入层的工程师。2. TaoToken 统一 Key 接入前置准备从注册到拿到 API Key在开始写代码之前你需要先把 TaoToken 的 API Key 拿到手。这一步很快但有几个细节不注意后面会踩坑。2.1 注册与创建 API Key打开 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号后进入控制台。在控制台左侧找到「API Keys」页面点击创建新的 Key。创建时建议给 Key 起一个能区分用途的名字比如agent-dev-local这样后面如果有多个环境本地开发、预发布、生产不会搞混。创建完成后你会看到一串以sk-开头的字符串这就是你的 API Key。注意这个 Key 只在创建时完整显示一次关掉页面就看不到了所以先复制到安全的地方。2.2 确认 Base URL 和可用模型TaoToken 的 API 端点地址是https://taotoken.net/api这个地址兼容 OpenAI 的/v1/chat/completions接口规范。也就是说任何支持 OpenAI 协议的 SDK 或工具只需要把 Base URL 改成这个地址再把 API Key 换成 TaoToken 的 Key就能直接调用。你可以在控制台的「模型对话」页面先测试一下模型是否可用。选一个模型比如 Claude 系列或 GPT 系列发一条测试消息确认返回正常。这一步能帮你排除 Key 权限或余额问题。2.3 环境变量规划在 Next.js 项目里API Key 必须放在服务端环境变量中绝对不能暴露给浏览器。我建议在项目根目录创建.env.local文件写入以下内容# TaoToken 统一 API 配置 TAOTOKEN_API_KEYsk-你的实际Key TAOTOKEN_BASE_URLhttps://taotoken.net/api # E2B 沙箱配置后面会用到 E2B_API_KEY你的E2B_Key # 数据库连接可选用于持久化 DATABASE_URLpostgresql://user:passwordlocalhost:5432/agent_db注意.env.local要加到.gitignore里避免 Key 被提交到仓库。如果你用 Vercel 部署在项目设置的 Environment Variables 里配置同样的变量即可。2.4 为什么不用多个厂商 Key 分别配有人可能会想我直接配 OpenAI 的 Key 和 Anthropic 的 Key 不就行了为什么要走统一通道原因有三个。第一多厂商 Key 意味着多套鉴权逻辑、多套错误处理、多套计费统计代码复杂度翻倍。第二用户 BYOK 场景下你让用户填多个 Key 体验很差而且 Key 存在前端或数据库都有安全风险。第三模型切换时你要改的不只是 model ID还有 Base URL 和鉴权头容易出错。用 TaoToken 统一 Key 之后你的模型调用代码只需要维护一个 client 实例切换模型只改model参数。这对独立开发者来说省掉的是实打实的维护成本。3. Next.js AI SDK 可复制配置项目骨架与模型接入代码这一节是核心我会给出完整的项目目录结构、依赖安装命令、以及 AI SDK 接入 TaoToken 的可复制代码。你照着做就能跑起来。3.1 项目初始化与依赖安装先用create-next-app创建项目pnpm create next-applatest agent-stack --typescript --tailwind --eslint --app --src-dir --import-alias /* cd agent-stack然后安装核心依赖pnpm add ai ai-sdk/openai ai-sdk/anthropic e2b e2b/code-interpreter pnpm add -D types/node这里说明一下各包的作用ai是 Vercel AI SDK 的核心包提供流式响应和工具调用能力ai-sdk/openai是 OpenAI 兼容协议的 providerTaoToken 走这个ai-sdk/anthropic用于 Anthropic 协议的原生支持e2b和e2b/code-interpreter是沙箱执行环境。3.2 项目目录结构我建议的目录结构如下agent-stack/ ├── src/ │ ├── app/ │ │ ├── api/ │ │ │ └── chat/ │ │ │ └── route.ts # Agent 主入口 │ │ ├── page.tsx # 前端页面 │ │ └── layout.tsx │ ├── lib/ │ │ ├── ai-client.ts # TaoToken 统一 client │ │ ├── tools.ts # Agent 工具定义 │ │ └── sandbox.ts # E2B 沙箱封装 │ └── components/ │ └── chat.tsx # 聊天 UI 组件 ├── .env.local ├── next.config.js ├── package.json └── tsconfig.json这个结构把模型接入、工具定义、沙箱执行分开后面扩展多 Agent 或加新工具时不会乱。3.3 TaoToken 统一 Client 配置在src/lib/ai-client.ts中创建统一 clientimport { createOpenAI } from ai-sdk/openai; import { createAnthropic } from ai-sdk/anthropic; // TaoToken 走 OpenAI 兼容协议 export const taotokenClient createOpenAI({ baseURL: process.env.TAOTOKEN_BASE_URL ?? https://taotoken.net/api, apiKey: process.env.TAOTOKEN_API_KEY, }); // 如果需要 Anthropic 原生协议也可以用同一个 Key export const anthropicClient createAnthropic({ baseURL: process.env.TAOTOKEN_BASE_URL ?? https://taotoken.net/api, apiKey: process.env.TAOTOKEN_API_KEY, }); // 模型 ID 集中管理切换模型只改这里 export const MODELS { fast: gpt-4o-mini, balanced: claude-3-5-sonnet-20241022, powerful: gpt-4o, } as const;这里的关键点是baseURL指向 TaoToken 的 API 地址apiKey用环境变量注入。模型 ID 集中在一个对象里后面 Agent 路由时根据任务复杂度选不同模型。3.4 Agent 工具定义与沙箱执行在src/lib/tools.ts中定义 Agent 可调用的工具import { tool } from ai; import { z } from zod; import { runInSandbox } from ./sandbox; export const executeCode tool({ description: 在沙箱中执行 Python 代码并返回结果, parameters: z.object({ code: z.string().describe(要执行的 Python 代码), }), execute: async ({ code }) { const result await runInSandbox(code); return { stdout: result.stdout, stderr: result.stderr, error: result.error, }; }, }); export const tools { executeCode, };在src/lib/sandbox.ts中封装 E2B 沙箱import { Sandbox } from e2b/code-interpreter; export async function runInSandbox(code: string) { const sandbox await Sandbox.create({ apiKey: process.env.E2B_API_KEY, timeoutMs: 60_000, }); try { const execution await sandbox.runCode(code); return { stdout: execution.logs.stdout.join(\n), stderr: execution.logs.stderr.join(\n), error: execution.error?.value ?? null, }; } finally { await sandbox.kill(); } }注意沙箱用完要kill否则会一直占用资源。E2B 的免费额度有限生产环境建议加超时和并发控制。3.5 API Route 主入口在src/app/api/chat/route.ts中写 Agent 主逻辑import { streamText } from ai; import { taotokenClient, MODELS } from /lib/ai-client; import { tools } from /lib/tools; export const maxDuration 60; export async function POST(req: Request) { const { messages } await req.json(); const result streamText({ model: taotokenClient(MODELS.balanced), system: 你是一个数学建模助手。遇到需要计算的问题时调用 executeCode 工具在沙箱中运行 Python 代码。 不要自己心算复杂表达式一律用代码验证。, messages, tools, maxSteps: 5, }); return result.toDataStreamResponse(); }这段代码做了几件事接收前端消息、用 TaoToken client 调用模型、注入工具定义、允许最多 5 轮工具调用循环、返回流式响应。maxSteps: 5是防止 Agent 陷入无限工具调用循环。3.6 前端流式 UI在src/components/chat.tsx中用 AI SDK 的useChathookuse client; import { useChat } from ai/react; export function Chat() { const { messages, input, handleInputChange, handleSubmit } useChat({ api: /api/chat, }); return ( div classNameflex flex-col h-screen p-4 div classNameflex-1 overflow-y-auto space-y-4 {messages.map((m) ( div key{m.id} classNamep-3 rounded bg-gray-100 strong{m.role}:/strong p classNamewhitespace-pre-wrap{m.content}/p /div ))} /div form onSubmit{handleSubmit} classNameflex gap-2 mt-4 input value{input} onChange{handleInputChange} classNameflex-1 border p-2 rounded placeholder输入你的问题... / button typesubmit classNamebg-blue-500 text-white px-4 rounded 发送 /button /form /div ); }到这里一条完整的 Agent 链路就搭好了前端发消息 → API Route 接收 → TaoToken 调用模型 → 模型决定是否调工具 → E2B 沙箱执行代码 → 结果流式返回前端。4. 本地启动与端到端验证确认 Agent 闭环跑通代码写完了接下来要验证整条链路是否真的能跑通。这一步很多人会跳过结果部署后才发现问题。4.1 启动开发服务器确保.env.local里的三个变量都填好了然后运行pnpm dev打开http://localhost:3000你应该能看到聊天界面。如果页面报错先检查环境变量是否被正确加载。Next.js 的.env.local只在服务端生效前端代码里不能直接读process.env.TAOTOKEN_API_KEY。4.2 验证模型调用先发一条不需要工具的消息比如「你好介绍一下你自己」。如果模型正常返回说明 TaoToken 的 Key 和 Base URL 配置正确。如果这里报 401说明 Key 无效或没传对。检查.env.local里的TAOTOKEN_API_KEY是否以sk-开头以及createOpenAI的apiKey参数是否读到了环境变量。4.3 验证工具调用与沙箱执行发一条需要计算的消息比如「帮我算一下 1234 乘以 5678 等于多少用代码验证」。正常流程是模型识别到需要计算 → 调用executeCode工具 → E2B 沙箱执行 Python 代码 → 返回结果 → 模型整合结果回复你。你可以在终端看到 E2B 沙箱的创建和销毁日志。如果沙箱报错常见原因是E2B_API_KEY没配或额度用完。4.4 验证流式响应观察前端消息是不是逐字出现的。如果是整段突然出现说明流式没生效。检查route.ts里是否用了result.toDataStreamResponse()以及前端是否用了useChat的默认流式处理。4.5 端到端验证清单跑完上面几步后用这个清单确认闭环完整验证项预期结果失败排查方向模型基础对话正常返回文本检查 TaoToken Key 和 Base URL工具调用触发终端出现沙箱日志检查 tools 定义和 maxSteps沙箱代码执行返回计算结果检查 E2B Key 和超时设置流式输出逐字显示检查 toDataStreamResponse多轮工具调用Agent 能连续调工具检查 maxSteps 是否够大全部通过后你就有了一个可部署的 Agent 最小闭环。接下来可以加数据库持久化、加更多工具、加鉴权逐步往生产级靠。5. 本篇常见报错排查401、local proxy failed、reading choices 怎么解这一节整理我在搭建过程中真实遇到过的报错以及对应的排查思路。你如果卡住了先在这里找找。5.1 401 Unauthorized这是最常见的报错通常长这样AI_APICallError: Unauthorized原因一般是 Key 没传对。排查顺序第一确认.env.local里TAOTOKEN_API_KEY的值完整没有多余空格或换行第二确认createOpenAI的apiKey参数确实读到了环境变量可以在ai-client.ts里临时加一行console.log(process.env.TAOTOKEN_API_KEY?.slice(0, 8))确认第三确认 Base URL 是https://taotoken.net/api不要多加/v1或漏掉/api。5.2 local proxy failed这个报错通常出现在网络层Error: local proxy failed如果你在本地开发时遇到先检查是否能正常访问 TaoToken 的 API 地址。可以用 curl 测试curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:gpt-4o-mini,messages:[{role:user,content:hi}]}如果 curl 能通但应用报错检查 Next.js 的 fetch 配置或是否有其他中间件拦截了请求。5.3 reading choices of undefined这个报错说明返回结构不符合预期TypeError: Cannot read properties of undefined (reading choices)通常是因为模型返回了错误响应但代码直接去读choices字段。排查方法在route.ts里加错误捕获打印完整响应体。常见原因是模型 ID 写错了TaoToken 找不到对应模型返回了错误 JSON 而不是标准的 chat completion 结构。5.4 OAuth 相关报错如果你用了 Anthropic 原生协议可能会遇到OAuth error: invalid_client这是因为 Anthropic 的鉴权方式和 OpenAI 兼容协议不同。用 TaoToken 统一 Key 时建议优先走 OpenAI 兼容协议createOpenAI除非你需要 Anthropic 特有的功能比如 prompt caching。如果必须用 Anthropic 协议确认createAnthropic的apiKey和baseURL都配置正确。5.5 沙箱超时或创建失败E2B 沙箱报错通常是这两种SandboxError: Failed to create sandbox TimeoutError: Sandbox execution timed out创建失败先检查E2B_API_KEY是否有效、额度是否用完。超时的话把timeoutMs调大或者在代码里加超时处理逻辑。生产环境建议给沙箱执行加一个总时长限制避免用户提交死循环代码把额度跑光。5.6 工具调用不触发如果模型一直不调用工具只回复文本检查两点第一tools对象是否正确传给了streamText第二system prompt 里是否明确告诉模型「遇到计算问题必须调用工具」。有些模型对工具调用的触发比较保守需要在 prompt 里强调。6. 从最小闭环到生产级 Agent下一步该补什么跑通最小闭环之后你手里已经有一个能用的 Agent 了。但如果要真正上线给用户用还有几块需要补。第一块是持久化。现在对话记录只存在内存里刷新页面就没了。加 PostgreSQL Drizzle ORM把消息、工具调用记录、Token 消耗都存下来。这样既能做历史记录也能做成本分析。第二块是鉴权。现在任何人都能调你的 API Route上线前必须加用户登录和请求限流。可以用 Better Auth 快速接入或者在 API Route 里加一层中间件校验。第三块是观测。Agent 系统没有 observability 后期很难排查问题。建议接入 OpenTelemetry把模型调用、工具执行、沙箱创建都打上 trace。Langfuse 对 AI 产品很友好可以看每次调用的 Token 消耗和延迟。第四块是成本控制。TaoToken 控制台可以看用量但应用层最好也做一层预扣或限额。比如每个用户每天最多调多少次模型、沙箱执行最多多少秒避免被刷。如果你打算长期做 Agent 产品建议把模型调用层再抽象一层支持按任务复杂度动态选模型。简单任务用便宜模型复杂推理用强模型成本能降不少。TaoToken 的模型对话页面可以帮你快速测试不同模型的效果和响应速度选型时很有用。最后说一个我踩过的坑不要一上来就追求多 Agent 协作。单 Agent 工具调用能解决 80% 的场景多 Agent 的编排复杂度是指数级上升的。先把单 Agent 跑稳再考虑拆多个角色。代码仓库结构、环境变量、工具定义、沙箱封装这些你都可以直接复制到自己的项目里用。唯一需要改的是模型 ID 和 system prompt根据你的业务场景调整就行。