用开源框架 15 分钟做出会听会说的 AI 语音助手

VideoSDK AI Agents

基于 VideoSDK AI Agents 的零门槛入门指南

适用人群：专科及以上学历的开发者、产品经理、技术爱好者
阅读收益：读完即可在自己的电脑跑起一个能实时对话的 AI 语音代理，并知道如何把它连进 Web、手机或电话系统。

一、为什么现在就能自己做语音助手？

过去，让 AI 听懂人话、回话并把声音传到千里之外，需要三拨工程师：

• 语音处理（STT、TTS）
• 大模型对话（LLM）
• 实时音视频（WebRTC、SIP）

VideoSDK 把三条链路封装成一个 Python 包 videosdk-agents，再配上一组可选插件，开发者只要写 不到 100 行代码 就能完成全部链路。

二、这个框架到底能做什么？

三、整体架构：一张图看懂数据流向

下图来自官方文档，展示了你的代码、VideoSDK 云端和用户终端三者之间的关系。

• 左：你写的 Python 代理
• 中：VideoSDK 负责音视频路由
• 右：浏览器、手机 App 或电话网关里的真人用户

四、准备清单：三分钟搞定前置条件

五、安装步骤：跟着命令行一步步来

1. 建立虚拟环境（防依赖冲突）

python3 -m venv venv
source venv/bin/activate

python -m venv venv
venv\Scripts\activate

2. 安装核心包

pip install videosdk-agents

3. 按需安装插件（示例）

# 让 AI 知道用户何时说完话
pip install videosdk-plugins-turn-detector

六、创建第一个会打招呼的 AI

把下面代码保存为 main.py，你就拥有了一个最简语音代理：

from videosdk.agents import Agent

class VoiceAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="你是一个友善的语音助理，回答尽量简洁。"
        )

    async def on_enter(self):
        await self.session.say("你好！有什么可以帮您？")

    async def on_exit(self):
        await self.session.say("再见，祝您愉快！")

七、让 AI 拥有“查天气”的超能力

方式 A：外部函数（可复用）

import aiohttp
from videosdk.agents import function_tool

@function_tool
async def get_weather(latitude: str, longitude: str):
    url = f"https://api.open-meteo.com/v1/forecast?latitude={latitude}&longitude={longitude}&current=temperature_2m"
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as resp:
            data = await resp.json()
            return {"temperature": data["current"]["temperature_2m"], "unit": "°C"}

在 VoiceAgent 的构造函数里注册：

super().__init__(
    instructions="你是一个友善的语音助理，可以查天气。",
    tools=[get_weather]
)

方式 B：内部函数（仅本代理用）

class VoiceAgent(Agent):
    @function_tool
    async def get_horoscope(self, sign: str):
        return {"sign": sign, "text": f"{sign} 今日宜写代码。"}

八、把耳朵、大脑、嘴巴串成流水线

下面以 Google Gemini 实时模型为例，演示如何连接：

from videosdk.plugins.google import GeminiRealtime, GeminiLiveConfig
from videosdk.agents import RealTimePipeline

model = GeminiRealtime(
    model="gemini-2.0-flash-live-001",
    api_key="YOUR_GOOGLE_API_KEY",        # 也支持写进 .env
    config=GeminiLiveConfig(
        voice="Leda",                     # 可选 8 种音色
        response_modalities=["AUDIO"]     # 只用语音，省流量
    )
)

pipeline = RealTimePipeline(model=model)

想用 OpenAI？把 GeminiRealtime 换成 from videosdk.plugins.openai import OpenAIRealtime 即可，其余代码不变。

九、启动代理并让它跑进会议室

import asyncio
from videosdk.agents import AgentSession, WorkerJob, RoomOptions, JobContext

async def start_session(ctx: JobContext):
    session = AgentSession(agent=VoiceAgent(), pipeline=pipeline)
    try:
        await ctx.connect()
        await session.start()
        await asyncio.Event().wait()   # 保持运行直到 Ctrl+C
    finally:
        await session.close()
        await ctx.shutdown()

def make_context():
    return JobContext(
        room_options=RoomOptions(
            room_id="填你的 Meeting ID",
            auth_token="填你的 VideoSDK Token",
            name="天气小助手",
            playground=True       # 打开即用的测试页面
        )
    )

if __name__ == "__main__":
    WorkerJob(entrypoint=start_session, jobctx=make_context).start()

终端执行：

python main.py

看到日志 Connected to room 就说明 AI 已就位。

十、客户端如何连进来？

官方给好了现成例子，任选其一即可：

• JavaScript 网页
• React
• React Native
• Android
• Flutter
• iOS

打开客户端，输入同样的 Meeting ID，立刻就能和 AI 说话。

十一、支持的大模型与工具一览表

十二、常见问题 FAQ

Q1：没有公网 IP，能测试吗？
A：VideoSDK 所有流量走官方中继，本地 localhost 即可。

Q2：免费额度有多少？
A：注册即送 10 美元体验金，跑语音对话大约能撑 3–4 小时。

Q3：可以同时开多个 AI 进同一个会议吗？
A：可以，每个 AI 用独立的 WorkerJob 即可，官方示例里有多代理协作案例。

Q4：如何换中文语音？
A：在 GeminiLiveConfig 里把 voice 换成支持中文的音色，或者在 TTS 插件里选 zh-CN 模型。

Q5：出现 ModuleNotFoundError 怎么办？
A：九成是插件没装全，按报错提示 pip install videosdk-plugins-xxx。

十三、进阶：把 AI 接进 400 客服电话

只需三步：

1. 在 Twilio 申请号码并开通 SIP Trunk；
2. Dashboard 里把号码指向 VideoSDK 提供的 SIP 域名；
3. 把 RoomOptions 中的 sip=True，AI 就能接听真实来电。

官方有完整示例：AI Telephony Demo

十四、自己动手写插件

如果你想接入尚未支持的模型，官方给了一份极简指南：BUILD_YOUR_OWN_PLUGIN.md。
核心只有两步：

1. 继承基类并实现 transcribe() / generate() / synthesize()；
2. PR 合并后所有人都能 pip install 使用。

十五、总结与下一步

今天，我们完成了：

• ✅ 环境准备
• ✅ 安装核心包与插件
• ✅ 创建会打招呼的 AI
• ✅ 添加天气查询工具
• ✅ 启动并接入客户端

下一步你可以：

• 把天气工具换成公司内部的 CRM 查询；
• 用 Simli 给 AI 加一张 3D 脸；
• 开三条电话线路，让 AI 同时处理售前、售后、技术支持。

代码已开源，社区在 Discord 等你提问。祝你玩得开心！