1. 从零跑通 Agora convo AI 教育 AgentNextJS STT 的完整落地路径Agora convo AI 是声网推出的实时对话式 AI 框架它把 STT语音转文字、LLM大模型推理、TTS文字转语音三段链路封装成可插拔的 Agent 组件配合 RTC 实时音视频通道让开发者能在 NextJS 项目里快速搭出一个能听、能想、能说的教育 Agent 助手。这套方案最适合两类人一是想给教育产品加语音陪练能力的全栈工程师二是需要面向香港及海外学校做多语言教学工具的技术团队。我这次要交付的是一个中文 AI 家教「小E」的最小可运行版本——前端用 NextJS 骨架语音入口走 STT对话链路通过 TaoToken 统一 Key 接入大模型最终在浏览器里实现实时语音问答。整条链路涉及的关键文件包括invite-agent/route.ts、.env.local、settings.json和config.toml下面按可复制的方式逐个拆开。2. TaoToken 前置统一 Key 与配置文件骨架在动手改 Agora 示例之前先把模型侧的接入凭证理顺。TaoToken 的作用是给多个模型供应商提供一个统一的 API 入口你不需要在代码里分别维护 OpenAI、Deepgram、MiniMax 各自的 Key而是通过一份配置文件集中管理。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。2.1 获取 API Key 与模型对话入口先到控制台创建 Key路径是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole 创建完成后在 API Keys 页面复制密钥https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys 。如果你只是想先验证模型能不能通可以直接用模型对话页面发一条测试消息https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel 。这一步能帮你排除「Key 本身有问题」还是「代码配置有问题」。2.2 settings.json 骨架很多 AI 编辑器包括 Trae、Cursor 这类会读取项目根目录或用户目录下的settings.json来注入模型配置。下面这份骨架可以直接复制把apiKey换成你自己的{ models: { provider: taotoken, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, defaultModel: gpt-4o-mini, fallbackModel: deepseek-chat }, agent: { maxHistory: 50, temperature: 0.7, maxTokens: 1024 } }baseUrl指向 TaoToken 的 API 端点defaultModel是教育 Agent 的主推理模型fallbackModel用于主模型超时或限流时兜底。maxHistory控制对话记忆轮数教育场景建议 30 到 50 轮太低会让学生重复自我介绍太高会拖慢响应。2.3 config.toml 骨架如果你的工具链走 TOML 配置部分 CLI 工具和 Agent 框架默认读这个格式用下面这份[provider] name taotoken base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 [llm] model gpt-4o-mini temperature 0.7 max_tokens 1024 top_p 0.95 [stt] provider deepgram model nova-3 language zh-CN [tts] provider minimax model speech_2_6_turbo voice_id Chinese (Mandarin)_Warm_Girl注意[stt]段的language字段官方示例默认是en中文教育场景必须改成zh-CN否则学生说中文会被识别成乱码。[tts]段的voice_id决定 AI 老师的音色Chinese (Mandarin)_Warm_Girl是偏温暖的女声适合青少年教学场景。3. NextJS 侧可复制配置从 clone 到中文家教「小E」拿到 Key 之后进入 Agora 官方 NextJS 示例的改造环节。整个流程分四步拉代码、配环境变量、改 Agent 提示词、调 STT 语言。3.1 拉取示例并安装依赖git clone https://github.com/AgoraIO-Conversational-AI/agent-quickstart-nextjs.git cd agent-quickstart-nextjs pnpm install安装完成后在项目根目录新建.env.local这个文件官方示例里没有必须手动创建NEXT_PUBLIC_AGORA_APP_ID你的AppID NEXT_AGORA_APP_CERTIFICATE你的Primary Certificate NEXT_PUBLIC_AGENT_UID123456AppID 和 Certificate 在 Agora 控制台创建项目后获取。NEXT_PUBLIC_AGENT_UID是 Agent 在频道里的用户 ID随便填一个不冲突的数字即可。3.2 改造 invite-agent/route.ts 为中文导师打开app/api/invite-agent/route.ts这是 Agent 的初始化入口。核心改动有三处系统提示词换成中文导师人设、STT 语言改zh-CN、TTS 音色改中文。const EDU_PROMPT 你是小E一位耐心且知识渊博的 AI 导师。 你的任务是通过自然对话帮助学生高效学习。 # 角色定位与语气 - 温暖、鼓励、对知识充满好奇。 - 像一位好老师一样说话清晰、有吸引力绝不居高临下。 # 教学方法 - 苏格拉底式引导优先通过提问引导学生自己发现答案。 - 脚手架式教学把复杂话题拆解成容易消化的小块。 # 核心行为准则 - 保持简洁这是语音对话大多数回复控制在 1-3 句话。 - 一次一个概念每轮只聚焦一个最重要的点。 # 教学范围 数学、科学、语文写作、历史、编程、英语、学习方法。 遇到超出知识范围的问题诚实说明局限不要编造。; const greetings: Recordstring, string { essay: 你好我是小E。作文最重要的是真情实感你今天想写什么呢, math: 你好我是小E。数学题不用怕我们一步一步来你先说说卡在哪一步, science: 你好我是小E。科学就是好奇心的游戏你今天想探索什么现象, history: 你好我是小E。历史像故事一样有趣你想聊哪个时代, coding: 你好我是小E。编程是给计算机下指令你想写个什么小程序, english: 你好我是小E。学英语就像交朋友我们先用英语聊两句, };然后在 Agent 初始化部分把 STT 和 TTS 的配置改掉.withStt( new DeepgramSTT({ model: nova-3, language: zh-CN, }), ) .withLlm( new OpenAI({ model: gpt-4o-mini, greetingMessage: greeting, failureMessage: 请稍等片刻。, maxHistory: 15, params: { max_tokens: 1024, temperature: 0.7, top_p: 0.95, }, }), ) .withTts( new MiniMaxTTS({ model: speech_2_6_turbo, voiceId: Chinese (Mandarin)_Warm_Girl, }), )language: zh-CN是中文识别的关键voiceId决定 AI 老师的音色。maxHistory: 15是 LLM 侧的记忆轮数比 Agent 层的 50 轮更保守避免上下文过长导致响应变慢。3.3 话题卡片与 UI 中文化PreCallCard组件负责通话前的界面。把 6 个话题卡片改成彩色图标加选中高亮按钮用紫色渐变全站文字改亮白色以适配深色背景。这部分可以直接把需求丢给 AI 编辑器比如「请把页面改成适合青少年的 UI 设计深色背景配亮白文字话题卡片用彩色图标」。RTC 和 RTM 的逻辑不要动只改样式层。4. 验证请求跑通第一个语音问答配置改完后启动开发服务器npm run dev浏览器打开http://localhost:3000你会看到话题选择卡片。点「数学」卡片允许麦克风权限然后说一句「三加五等于几」。预期结果是STT 把语音转成文字LLM 生成回复TTS 用中文女声念出来整个过程端到端延迟在 650ms 左右。如果模型侧想单独验证 TaoToken 是否通可以在终端发一条 curlcurl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 用一句话解释什么是光合作用}] }返回里有choices[0].message.content就说明 Key 和端点都没问题。这一步能帮你快速区分是模型接入的问题还是 Agora 链路的问题。5. 本篇常见错排查5.1 STT 识别成英文或乱码最常见的原因是language字段没改。官方示例默认en中文场景必须显式写zh-CN。如果改了还是乱码检查 Deepgram 的 model 是不是nova-3旧版nova-2对中文支持较弱。5.2 Agent 加入频道失败报错通常是NEXT_AGORA_APP_ID或NEXT_AGORA_APP_CERTIFICATE没配。注意.env.local必须手动新建官方示例的.env.example不会自动生效。另外NEXT_PUBLIC_AGENT_UID不能和浏览器端用户 UID 重复否则会互相踢出频道。5.3 模型返回超时或 401先确认settings.json或config.toml里的baseUrl是https://taotoken.net/api不要多加/v1后缀部分框架会自动拼接。401 一般是 Key 复制时带了空格或者 Key 已被删除。可以到 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys 重新生成一个。5.4 语音有回音或抢话这是 VAD语音活动检测参数的问题。turnDetection里的silenceDurationMs控制「停顿多久算说完」教育场景建议设 800 到 1200ms太短会打断学生思考太长会让对话变慢。如果 AI 自己的声音被麦克风收进去检查是否开了回声消除Agora RTC 默认开启但浏览器端要确保audioProcessing没被关掉。5.5 长对话后响应变慢maxHistory设太大是主因。Agent 层 50 轮加 LLM 层 15 轮实际上下文可能超过模型窗口。教育场景建议 LLM 层保持 15 轮以内Agent 层 30 轮左右超出部分让模型做摘要压缩。6. 长期编码与 Agent 迭代Coding Plan 与接入文档如果你打算把这套教育 Agent 从 Demo 推到生产长期会涉及多模型切换、Agent 工具调用、成本控制这些事。TaoToken 的 Coding Plan 适合需要持续调用模型做编码和 Agent 迭代的场景入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan 。接入过程中遇到参数细节查文档比翻源码快https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc 。如果你用的是 Claude Code 这类终端 Agent 工具Anthropic 兼容接入的配置参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaudecode 。我实测下来教育 Agent 最容易踩的坑不是模型能力而是 STT 语言配置和 VAD 参数。把zh-CN和silenceDurationMs这两个值调对体验会有明显提升。另外 Agora 官方提供的 29 个 Recipes 覆盖了 7 种语言框架NextJS 只是其中一条路径如果你的团队用 Python 或 Go可以对照自己的技术栈选对应的示例跑一遍再套用本文的 TaoToken 配置骨架。
