企业官网建设流程全解析

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_KEY=sk-你的实际Key TAOTOKEN_BASE_URL=https://taotoken.net/api # E2B 沙箱配置（后面会用到） E2B_API_KEY=你的E2B_Key # 数据库连接（可选，用于持久化） DATABASE_URL=postgresql://user:password@localhost: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-app@latest 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 兼容协议的 provider，TaoToken 走这个；@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中创建统一 client：

import { 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 的useChathook：

'use client'; import { useChat } from 'ai/react'; export function Chat() { const { messages, input, handleInputChange, handleSubmit } = useChat({ api: '/api/chat', }); return ( <div className="flex flex-col h-screen p-4"> <div className="flex-1 overflow-y-auto space-y-4"> {messages.map((m) => ( <div key={m.id} className="p-3 rounded bg-gray-100"> <strong>{m.role}:</strong> <p className="whitespace-pre-wrap">{m.content}</p> </div> ))} </div> <form onSubmit={handleSubmit} className="flex gap-2 mt-4"> <input value={input} onChange={handleInputChange} className="flex-1 border p-2 rounded" placeholder="输入你的问题..." /> <button type="submit" className="bg-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 端到端验证清单

跑完上面几步后，用这个清单确认闭环完整：

全部通过后，你就有了一个可部署的 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，根据你的业务场景调整就行。