---
title: "LiveKit Agents에서 ThunderPhone 사용"
description: "LiveKit 룸, SIP 및 전화 기능과 함께 LiveKit Agents 세션의 실시간(음성 간 음성) 모델로 ThunderPhone 음성 에이전트를 실행합니다."
---

[LiveKit Agents](https://github.com/livekit/agents)는 LiveKit 룸 기반의 실시간 음성 에이전트를 위한 오픈 소스 프레임워크입니다. ThunderPhone은 **실시간 모델**로 연결됩니다. 프레임워크가 참가자의 오디오를 전송하면 ThunderPhone이 에이전트의 음성, 트랜스크립트 및 함수 호출을 반환하고, LiveKit의 룸, SIP 트렁크 및 전화 기능이 오디오를 전달합니다. 음성 인식, 언어 모델, 음성, 턴테이킹, 62개 언어 및 도구는 모두 ThunderPhone에서 실행됩니다.

이 방식으로 이루어진 통화는 [통화 기록](/api-reference/calls)에 표시되며 다른 실시간 통화와 동일하게 과금됩니다([요금](/ko/guides/pricing)). 구독이나 ThunderPhone 전화번호는 필요하지 않습니다.

## 설치

```bash
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](https://github.com/livekit/agents)
리포지토리에 포함되어 있으며 `livekit-agents` 자체와 함께 릴리스되므로, 두 항목의
버전을 동일하게 유지합니다. LiveKit은 자체
[ThunderPhone 플러그인 가이드](https://docs.livekit.io/agents/models/realtime/thunderphone/)에서 이를 문서화합니다.

ThunderPhone의 [Realtime WebSocket](/api-reference/realtime)이 동일한 프로토콜을 사용하므로 이 플러그인은 LiveKit의 OpenAI Realtime 모델을 래핑합니다. `livekit-agents` 1.8 이상이 필요합니다.

## 저장된 에이전트 실행

에이전트가 수행하는 모든 작업(프롬프트, 음성, 엔진, 언어, 도구, 인사말, 무음 확인)은 ThunderPhone에서 구성합니다. 세션은 오디오만 전달합니다. 대시보드에서 에이전트를 구축하거나 ThunderPhone 에이전트를 구축, 테스트 및 조정하는 AI 에이전트인 Zeus가 설정하도록 한 다음, 해당 ID를 여기에 전달합니다. ThunderPhone에 배포한 변경 사항은 LiveKit 코드를 수정하지 않아도 다음 통화에 적용됩니다.

```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))
```

저장된 에이전트는 ThunderPhone에서 인사하고 자체 도구를 실행합니다. LiveKit `Agent`의 지침과 도구는 전송되지 않습니다. ThunderPhone 에이전트가 전화를 끊으면 통화가 종료되고 세션도 함께 닫힙니다.

## 세션을 인라인으로 구성

`agent_id`가 없으면 지침과 도구는 OpenAI에서와 동일하게 LiveKit `Agent`에서 가져옵니다. `model`은 엔진을 선택하고 `voice`는 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은 통화가 시작될 때 지침과 도구를 고정하므로, 이를 변경하는 `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은 실시간 프로토콜에 플랫폼 이벤트를 추가합니다. 세션은
다음 이벤트를 발생시킵니다.

```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`은 세션이 활성화되면 `call_id`를 제공합니다. 통화 후
[`GET /v1/calls/{call_id}`](/api-reference/calls)와 함께 사용하여 녹음,
대화 기록 및 평가를 가져옵니다. 그 외 모든 `call.*` 이벤트(통화 전환,
키패드, 음성 무시)는 `thunderphone_call_event`로 수신됩니다.

## 제한 사항

- 턴 감지는 서버 측에서 처리되며 항상 활성화됩니다. 프레임워크 측 턴 감지
  (`AgentSession`의 `turn_detection`)는 무시됩니다.
- 통화가 시작된 후에는 지시와 도구를 변경할 수 없습니다.
- 오디오는 양방향 모두 24kHz의 16비트 모노 PCM입니다.
- 동영상 프레임은 무시됩니다.

<Note>
Pipecat을 사용하시나요? [Pipecat에서 ThunderPhone 사용](/ko/guides/use-with-pipecat)을 참조하세요.
</Note>
