ThunderPhone v3가 출시되었습니다.셀프서비스로, 분당 2¢부터.출시 소식 보기

Connect tools & data

LiveKit Agents에서 ThunderPhone 사용

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

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 플러그인 가이드에서 이를 문서화합니다.

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

저장된 에이전트 실행

에이전트가 수행하는 모든 작업(프롬프트, 음성, 엔진, 언어, 도구, 인사말, 무음 확인)은 ThunderPhone에서 구성합니다. 세션은 오디오만 전달합니다. 대시보드에서 에이전트를 구축하거나 ThunderPhone 에이전트를 구축, 테스트 및 조정하는 AI 에이전트인 Zeus가 설정하도록 한 다음, 해당 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가 없으면 지침과 도구는 OpenAI에서와 동일하게 LiveKit Agent에서 가져옵니다. 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 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은 실시간 프로토콜에 플랫폼 이벤트를 추가합니다. 세션은 다음 이벤트를 발생시킵니다.

@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)는 무시됩니다.
  • 통화가 시작된 후에는 지시와 도구를 변경할 수 없습니다.
  • 오디오는 양방향 모두 24kHz의 16비트 모노 PCM입니다.
  • 동영상 프레임은 무시됩니다.