Open in
Używaj ThunderPhone z LiveKit Agents
Uruchom agenta głosowego ThunderPhone jako model czasu rzeczywistego (mowa na mowę) w sesji LiveKit Agents, z pokojami LiveKit, SIP i telefonią wokół niego.
LiveKit Agents to framework open source dla agentów głosowych działających w czasie rzeczywistym w pokojach LiveKit. ThunderPhone integruje się jako model czasu rzeczywistego: framework wysyła dźwięk uczestnika, ThunderPhone zwraca głos agenta, transkrypcje i wywołania funkcji, a pokoje LiveKit, łącza SIP i telefonia przesyłają dźwięk. Rozpoznawanie mowy, model językowy, głos, zarządzanie kolejnością wypowiedzi, 62 języki i narzędzia działają w ThunderPhone.
Połączenia wykonywane w ten sposób pojawiają się w historii połączeń i są rozliczane jak każde inne połączenie w czasie rzeczywistym (cennik). Nie wymagają subskrypcji ani numeru telefonu ThunderPhone.
Instalacja
pip install livekit-plugins-thunderphone
export THUNDERPHONE_API_KEY=sk_live_... # a secret API keyW przypadku uv polecenie uv add "livekit-agents[thunderphone]~=1.8" instaluje tę samą
wtyczkę. Jest ona dostępna w repozytorium livekit/agents
i jest wydawana razem z samym livekit-agents, dlatego zachowaj tę samą wersję obu
pakietów. LiveKit dokumentuje ją we własnym
przewodniku po wtyczce ThunderPhone.
Wtyczka opakowuje model OpenAI Realtime LiveKit, ponieważ Realtime WebSocket ThunderPhone
obsługuje ten sam protokół. Wymaga livekit-agents w wersji 1.8 lub nowszej.
Uruchamianie zapisanego agenta
Wszystko, co robi agent (prompt, głos, silnik, języki, narzędzia, powitanie, sprawdzanie ciszy), jest konfigurowane w ThunderPhone. Sesja tylko przesyła dźwięk. Zbuduj agenta w panelu lub zleć jego skonfigurowanie Zeusowi (agentowi AI, który tworzy, testuje i dostraja agentów ThunderPhone), a następnie przekaż tutaj jego identyfikator. Zmiany wdrożone w ThunderPhone zostaną zastosowane przy następnym połączeniu bez modyfikowania kodu 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))Zapisany agent wita i uruchamia własne narzędzia w ThunderPhone; instrukcje i narzędzia
Agent LiveKit nie są wysyłane. Połączenie kończy się, gdy
agent ThunderPhone się rozłączy, a sesja zamyka się razem z nim.
Konfigurowanie sesji w kodzie
Bez agent_id instrukcje i narzędzia pochodzą z Agent LiveKit, tak
samo jak w przypadku OpenAI. model wybiera silnik, a voice wybiera głos
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 blokuje instrukcje i narzędzia w chwili rozpoczęcia połączenia, dlatego
update_instructions, update_tools i przekazania agenta, które je zmieniają, nie są
obsługiwane w trakcie połączenia. Sesje w kodzie są sterowane przez klienta: agent mówi,
gdy wywołasz generate_reply() lub gdy uczestnik zakończy swoją turę.
Opcje
| Argument | Znaczenie |
|---|---|
api_key | Tajny klucz (sk_live_...). Domyślnie: THUNDERPHONE_API_KEY. |
agent_id | Uruchamia zapisanego agenta. Wzajemnie wykluczające się z model i voice. |
model | Silnik dla sesji wbudowanych: bolt (starsze spark i storm są nadal obsługiwane). |
voice | Nazwa głosu ThunderPhone dla sesji wbudowanych. |
language | Wskazówka dotycząca głównego języka dla sesji wbudowanych, np. es. |
caller_number, callee_number | Numery telefonów połączenia, gdy pokój obsługuje linię telefoniczną. Pojawiają się jako numery od i do w Historii połączeń. |
live_transcripts | Przesyła fragmenty transkrypcji rozmówcy w trakcie wypowiedzi (dodatkowo płatne). |
base_url | Zastępuje punkt końcowy; domyślnie wss://api.thunderphone.com/v1/realtime. |
Zdarzenia
ThunderPhone dodaje zdarzenia platformy do protokołu czasu rzeczywistego. Sesja je emituje:
@session.llm.session.on("thunderphone_call_ended") # or on the RealtimeSession you hold
def on_call_ended(event):
print("call ended:", event["reason"])RealtimeSession udostępnia call_id, gdy sesja jest aktywna. Użyj go z
GET /v1/calls/{call_id}, aby pobrać nagranie,
transkrypcję i ocenę po połączeniu. Każde inne zdarzenie call.* (przekazanie,
klawiatura, zignorowana mowa) dociera jako thunderphone_call_event.
Ograniczenia
- Wykrywanie końca wypowiedzi odbywa się po stronie serwera i jest zawsze włączone; wykrywanie końca wypowiedzi po stronie frameworka
(
turn_detectionwAgentSession) jest ignorowane. - Instrukcje i narzędzia nie mogą zostać zmienione po rozpoczęciu połączenia.
- Dźwięk to 16-bitowy monofoniczny PCM o częstotliwości 24 kHz w obu kierunkach.
- Klatki wideo są ignorowane.