Open in
Sử dụng ThunderPhone từ LiveKit Agents
Chạy một tác nhân AI giọng nói ThunderPhone làm mô hình thời gian thực (giọng nói sang giọng nói) của một phiên LiveKit Agents, cùng với phòng LiveKit, SIP và hệ thống điện thoại xung quanh.
LiveKit Agents là một framework mã nguồn mở dành cho tác nhân AI giọng nói thời gian thực trên các phòng LiveKit. ThunderPhone tích hợp với vai trò mô hình thời gian thực: framework gửi âm thanh của người tham gia, ThunderPhone trả về giọng nói, bản chép lời và lệnh gọi hàm của tác nhân AI, còn phòng LiveKit, trunk SIP và hệ thống điện thoại truyền tải âm thanh. Nhận dạng giọng nói, mô hình ngôn ngữ, giọng nói, luân phiên lượt nói, 62 ngôn ngữ và công cụ đều chạy trên ThunderPhone.
Các cuộc gọi được thực hiện theo cách này sẽ xuất hiện trong lịch sử cuộc gọi và được tính phí như mọi cuộc gọi thời gian thực khác (bảng giá). Không cần gói thuê bao và cũng không liên quan đến số điện thoại ThunderPhone.
Cài đặt
pip install livekit-plugins-thunderphone
export THUNDERPHONE_API_KEY=sk_live_... # a secret API keyVới uv, uv add "livekit-agents[thunderphone]~=1.8" cài đặt cùng plugin đó. Plugin này có trong kho lưu trữ livekit/agents và được phát hành cùng với livekit-agents, vì vậy hãy giữ hai phiên bản giống nhau. LiveKit có tài liệu riêng trong hướng dẫn plugin ThunderPhone.
Plugin này bao bọc mô hình OpenAI Realtime của LiveKit vì
Realtime WebSocket của ThunderPhone sử dụng cùng giao thức. Plugin
yêu cầu livekit-agents phiên bản 1.8 trở lên.
Chạy tác nhân đã lưu
Mọi thứ tác nhân AI thực hiện (prompt, giọng nói, engine, ngôn ngữ, công cụ, lời chào, kiểm tra khi im lặng) đều được cấu hình trên ThunderPhone. Phiên chỉ truyền âm thanh. Tạo tác nhân AI trong bảng điều khiển hoặc để Zeus (tác nhân AI tạo, kiểm thử và tinh chỉnh tác nhân AI ThunderPhone) thiết lập, rồi truyền ID của tác nhân tại đây. Các thay đổi bạn triển khai trên ThunderPhone sẽ áp dụng cho cuộc gọi tiếp theo mà không cần chạm vào mã LiveKit của bạn.
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))Tác nhân đã lưu sẽ chào và chạy các công cụ riêng trên ThunderPhone; hướng dẫn và
công cụ của Agent LiveKit không được gửi đi. Cuộc gọi kết thúc khi tác nhân AI
ThunderPhone gác máy và phiên cũng đóng theo.
Cấu hình phiên trực tiếp trong mã
Không có agent_id, hướng dẫn và công cụ đến từ Agent của LiveKit, giống như với OpenAI. model chọn engine và voice chọn giọng nói 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 khóa hướng dẫn và công cụ khi cuộc gọi bắt đầu, vì vậy
update_instructions, update_tools và các lượt chuyển giao tác nhân làm thay đổi chúng
không được hỗ trợ trong khi gọi. Phiên trực tiếp trong mã do máy khách điều khiển: tác nhân AI nói
khi bạn gọi generate_reply() hoặc khi người tham gia kết thúc một lượt nói.
Tùy chọn
| Tham số | Ý nghĩa |
|---|---|
api_key | Khóa bí mật (sk_live_...). Mặc định là THUNDERPHONE_API_KEY. |
agent_id | Chạy một tác nhân AI đã lưu. Không thể dùng cùng với model và voice. |
model | Công cụ cho phiên nội tuyến: bolt (vẫn chấp nhận spark và storm cũ). |
voice | Tên giọng nói ThunderPhone cho phiên nội tuyến. |
language | Gợi ý ngôn ngữ chính cho phiên nội tuyến, ví dụ: es. |
caller_number, callee_number | Số điện thoại của cuộc gọi khi phòng đại diện cho một đường dây điện thoại. Chúng xuất hiện dưới dạng số gọi đi và số nhận cuộc gọi trong lịch sử cuộc gọi. |
live_transcripts | Truyền các đoạn bản chép lời của người gọi trong khi họ đang nói (tính phí thêm). |
base_url | Ghi đè endpoint, mặc định là wss://api.thunderphone.com/v1/realtime. |
Sự kiện
ThunderPhone bổ sung các sự kiện nền tảng bên trên giao thức thời gian thực. Phiên phát ra các sự kiện này:
@session.llm.session.on("thunderphone_call_ended") # or on the RealtimeSession you hold
def on_call_ended(event):
print("call ended:", event["reason"])RealtimeSession hiển thị call_id sau khi phiên hoạt động. Dùng giá trị này với
GET /v1/calls/{call_id} để lấy bản ghi âm,
bản chép lời và điểm đánh giá sau cuộc gọi. Mọi sự kiện call.* khác (chuyển cuộc gọi,
bàn phím, lời nói bị bỏ qua) đều đến dưới dạng thunderphone_call_event.
Giới hạn
- Phát hiện lượt nói được xử lý phía máy chủ và luôn bật; phát hiện lượt nói phía framework
(
turn_detectiontrênAgentSession) bị bỏ qua. - Không thể thay đổi hướng dẫn và công cụ sau khi cuộc gọi bắt đầu.
- Âm thanh là PCM đơn kênh 16-bit ở 24 kHz theo cả hai chiều.
- Khung hình video bị bỏ qua.