---
title: "Sử dụng ThunderPhone từ LiveKit Agents"
description: "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](https://github.com/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](/api-reference/calls) và được tính phí như mọi cuộc gọi thời gian thực khác ([bảng giá](/vi/guides/pricing)). 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

```bash
pip install livekit-plugins-thunderphone
export THUNDERPHONE_API_KEY=sk_live_...   # a secret API key
```

Vớ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](https://github.com/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](https://docs.livekit.io/agents/models/realtime/thunderphone/).

Plugin này bao bọc mô hình OpenAI Realtime của LiveKit vì
[Realtime WebSocket](/api-reference/realtime) 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.

```python
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.

```python
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 first
```

ThunderPhone 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:

```python
@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}`](/api-reference/calls) để 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_detection` trên `AgentSession`) 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.

<Note>
Bạn đang xây dựng trên Pipecat? Xem [Sử dụng ThunderPhone từ Pipecat](/vi/guides/use-with-pipecat).
</Note>
