Open in
从 LiveKit Agents 使用 ThunderPhone
将 ThunderPhone 语音智能体作为 LiveKit Agents 会话的实时(语音到语音)模型运行,并借助 LiveKit 房间、SIP 和电话功能进行集成。
LiveKit Agents 是一个基于 LiveKit 房间构建实时语音智能体的开源框架。ThunderPhone 作为实时模型接入:该框架发送参与者的音频,ThunderPhone 返回智能体语音、转录文本和函数调用,而 LiveKit 的房间、SIP 中继和电话系统负责传输音频。语音识别、语言模型、语音、轮次管理、62 种语言和工具均在 ThunderPhone 上运行。
通过这种方式进行的通话会显示在通话记录中,并与其他实时通话一样计费(定价)。无需订阅,也不涉及 ThunderPhone 电话号码。
安装
pip install livekit-plugins-thunderphone
export THUNDERPHONE_API_KEY=sk_live_... # a secret API key使用 uv 时,uv add "livekit-agents[thunderphone]~=1.8" 会安装相同的
插件。它位于 livekit/agents
仓库中,并随 livekit-agents 一同发布,因此请保持两者版本
一致。LiveKit 在其自己的
ThunderPhone 插件指南中提供了相关文档。
该插件封装了 LiveKit 的 OpenAI Realtime 模型,因为 ThunderPhone 的
Realtime WebSocket 使用相同的协议。它
需要 livekit-agents 1.8 或更高版本。
运行已保存的智能体
智能体执行的所有操作(提示词、语音、引擎、语言、工具、问候语、静默期间的主动跟进)均在 ThunderPhone 中配置。会话仅传输音频。请在控制台中构建智能体,或让 Zeus(用于构建、测试和调优 ThunderPhone 智能体的 AI 智能体)完成设置,然后在此处传入其 ID。您在 ThunderPhone 上部署的更改会应用于下一通电话,无需修改您的 LiveKit 代码。
from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
from livekit.plugins import thunderphone
async def entrypoint(ctx: JobContext):
session = AgentSession(llm=thunderphone.RealtimeModel(agent_id=12))
await session.start(agent=Agent(instructions=""), room=ctx.room)
if __name__ == "__main__":
cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))已保存的智能体会在 ThunderPhone 上进行问候并运行自己的工具;LiveKit
Agent 的指令和工具不会被发送。ThunderPhone 智能体挂断时,
通话结束,会话也随之关闭。
内联配置会话
如果未提供 agent_id,指令和工具将来自 LiveKit Agent,其方式与 OpenAI 相同。model 选择引擎,voice 选择 ThunderPhone 语音。
from livekit.agents import Agent, AgentSession, RunContext, function_tool
from livekit.plugins import thunderphone
class Receptionist(Agent):
def __init__(self):
super().__init__(instructions="You are Acme Dental's receptionist. Be brief.")
@function_tool
async def check_availability(self, context: RunContext, date: str) -> dict:
"""Free appointment slots on a date."""
return {"slots": await calendar.free_slots(date)}
async def entrypoint(ctx: JobContext):
session = AgentSession(
llm=thunderphone.RealtimeModel(model="bolt", voice="olivia", language="es"),
)
await session.start(agent=Receptionist(), room=ctx.room)
await session.generate_reply() # the agent speaks firstThunderPhone 会在通话开始时冻结指令和工具,因此通话过程中不支持
update_instructions、update_tools 以及会更改它们的智能体交接。
内联会话由客户端驱动:当您调用 generate_reply() 或参与者完成一轮发言时,
智能体会进行回应。
选项
| 参数 | 含义 |
|---|---|
api_key | 密钥(sk_live_...)。默认使用 THUNDERPHONE_API_KEY。 |
agent_id | 运行已保存的智能体。不能与 model 和 voice 同时使用。 |
model | 内联会话的引擎:bolt(仍接受较早版本的 spark 和 storm)。 |
voice | 内联会话的 ThunderPhone 语音名称。 |
language | 内联会话的主要语言提示,例如 es。 |
caller_number, callee_number | 当房间接入电话线路时的通话电话号码。它们会在通话记录中显示为主叫和被叫号码。 |
live_transcripts | 在来电者发言过程中流式传输转录片段(额外计费)。 |
base_url | 端点覆盖地址,默认为 wss://api.thunderphone.com/v1/realtime。 |
事件
ThunderPhone 在实时协议之上添加了平台事件。会话会发出以下事件:
@session.llm.session.on("thunderphone_call_ended") # or on the RealtimeSession you hold
def on_call_ended(event):
print("call ended:", event["reason"])会话上线后,RealtimeSession 会公开 call_id。通话结束后,使用它调用
GET /v1/calls/{call_id} 获取录音、转录和评分。其他所有 call.* 事件(转接、按键、语音被忽略)都会作为 thunderphone_call_event 到达。
限制
- 轮次检测在服务器端执行且始终启用;框架端的轮次检测
(
AgentSession上的turn_detection)会被忽略。 - 通话开始后,无法更改指令和工具。
- 双向音频均为 24 kHz 的 16 位单声道 PCM。
- 视频帧会被忽略。