Open in
Používanie ThunderPhone s klientmi OpenAI Realtime
Nakonfigurujte klienta servera kompatibilného s OpenAI Realtime tak, aby používal ThunderPhone, a to buď s uloženým agentom, alebo s vloženou konfiguráciou relácie.
ThunderPhone implementuje zameranú podmnožinu modelu udalostí OpenAI Realtime. Existujúci klient na strane servera môže zachovať svoj tok udalostí WebSocketu, zvuku, relácie a odpovedí a zároveň používať hlasového agenta ThunderPhone.
Pred pripojením
Potrebujete tajný kľúč API organizácie ThunderPhone a serverové prostredie, ktoré dokáže otvárať WebSockety. Nepripájajte sa z kódu prehliadača ani nevystavujte kľúč prehliadaču. Ak chcete použiť uloženého agenta, najprv ho nasaďte a skopírujte jeho číselné ID agenta.
Pripojte sa k:
wss://api.thunderphone.com/v1/realtimeOverte aktualizáciu WebSocketu zo svojho servera:
Authorization: Bearer sk_live_YOUR_API_KEYOverovanie pomocou reťazca dotazu je dostupné pre klientov, ktorí nemôžu nastaviť hlavičky handshaku, ale adresy URL môžu ľahšie uniknúť do protokolov.
Vyberte, kto spravuje konfiguráciu
| Režim | Vyberiete ho pomocou | Zdroj konfigurácie |
|---|---|---|
| Uložený agent | session.prompt.id v prvom session.update alebo ?agent_id=12 | Nasadená výzva, hlas, produkt, jazyky, znalosti a kompatibilné nástroje spúšťané na serveri, plus pokyny a premenné tejto relácie |
| Vložený | Ani jedno | Prvý prijatý session.update od vášho klienta |
Uložený agent
V uloženom agentovi uchovávajte všetko, čo majú všetky hovory spoločné, kde má verzie a testovacie
sady, a v prvom session.update odošlite to, čo sa mení pre jednotlivé relácie:
session.prompt.id vyberá nasadeného agenta, session.instructions obsahuje
stručné zadanie tejto relácie a session.prompt.variables dopĺňa zástupné symboly
{{name}} v promte agenta.
{
"type": "session.update",
"session": {
"type": "realtime",
"prompt": {
"id": "12",
"variables": { "user_name": "Ada Park" }
},
"instructions": "Ada is a Costco member in Mountain View. Call the store and ask for today's opening hours.",
"audio": {
"input": { "format": { "type": "audio/pcm", "rate": 24000 } },
"output": { "format": { "type": "audio/pcm", "rate": 24000 } }
}
}
}Inštrukcie sa stanú kontextom hovoru,
pridaným za prompt agenta iba pre tento hovor. Vlastné možnosti relácie
(telephony, outbound, ivr_mode, call_events, placeholders) a jazyk,
v ktorom sa začína (primary_language), patria do session.config, rovnako ako
pri vloženej relácii. Hlas agenta, produkt a nástroje pochádzajú z jeho nasadenej
konfigurácie: hlas, iné nastavenie agenta alebo pole určené len pre OpenAI, napríklad
iná než predvolená hodnota tool_choice v aktualizácii, vyvolá udalosť error a bude
ignorované; nástroje spúšťané vaším klientom budú odmietnuté (nástroje spúšťané klientom
vyžadujú vloženú reláciu). prompt.version sa prijme a ignoruje. Všetky pravidlá nájdete v časti Použitie uloženého
agenta.
Pripojenie pomocou ?agent_id=12 namiesto toho spustí agenta počas pripájania soketu,
takže session.update nie je potrebné, no konfigurácia relácie je potom pevne daná:
inštrukcie, premenné a možnosti relácie (outbound,
ivr_mode, telephony, placeholders, call_events) odoslané potom budú
odmietnuté udalosťou error. Ak chcete agenta namiesto toho spustiť pri prvom
session.update, pridajte do adresy URL
&wait_for_session_update=1; táto aktualizácia potom rovnakým spôsobom obsahuje inštrukcie, premenné a
možnosti relácie. Odchádzajúca relácia to vyžaduje. Kým táto aktualizácia nepríde, zvuk volajúceho sa zadrží, ostatné udalosti budú
odmietnuté a soket sa zatvorí, ak žiadna nepríde do 10 sekúnd.
Úvodný pozdrav zostáva k dispozícii, ale Realtime vypne hovorené kontroly ticha
agenta a ponúka transfer_call a send_keypad_input iba s
call_events. Ostatné kompatibilné nástroje sa spúšťajú v ThunderPhone; nástroje spúšťané klientom
vyžadujú vloženú reláciu. Formáty zvuku ani inštrukcie a premenné relácie sa po
začatí hovoru nemôžu zmeniť.
Vložená relácia
Bez uloženého agenta počkajte na session.created a potom odošlite session.update:
{
"type": "session.update",
"session": {
"type": "realtime",
"instructions": "Answer questions clearly and keep responses brief.",
"audio": {
"input": {
"format": { "type": "audio/pcm", "rate": 24000 }
},
"output": {
"format": { "type": "audio/pcm", "rate": 24000 },
"voice": "olivia"
}
},
"config": {
"product": "bolt"
}
}
}Prvá prijatá aktualizácia zriadi hovor. session.updated znamená, že relácia je aktívna. Pokyny, hlas, produkt, nástroje a formáty zvuku po tomto bode nemožno zmeniť. Ak chcete zachovať pokyny nemenné a meniť iba pomenované hodnoty, zapíšte do nich zástupné symboly {{name}} a hodnoty odošlite v session.config.variables.
Vložené relácie nemajú automatický pozdrav ani hovorené kontroly ticha. Ak chcete,
aby agent prehovoril ako prvý, pridajte systémovú alebo používateľskú správu a odošlite
response.create. Úplne nečinná relácia sa stále ukončí pri limite platformy pre
tiché hovory, ktorý je predvolene 600 sekúnd.
Použite oficiálnu súpravu OpenAI SDK
Odovzdajte základnú URL adresu WebSocketu končiacu na /v1; súprava SDK pridá /realtime. Hodnota
model je názov kompatibility a nevyberá produkt ThunderPhone. Produkt vyberte v konfigurácii relácie alebo uloženom agentovi.
Táto kontrola pripojenia vytvorí vloženú reláciu Bolt, vypisuje udalosti až do
prvej udalosti session.updated a potom sa zatvorí. Na streamovanie zvuku použite minimálneho klienta
v jazyku Python.
import asyncio
import os
from openai import AsyncOpenAI
async def main():
client = AsyncOpenAI(
api_key=os.environ["THUNDERPHONE_API_KEY"],
websocket_base_url="wss://api.thunderphone.com/v1",
)
async with client.realtime.connect(
model="thunderphone-realtime"
) as connection:
await connection.session.update(session={
"type": "realtime",
"instructions": "Listen to the caller and help them complete the call.",
"config": {"product": "bolt"},
})
async for event in connection:
print(event.type)
if event.type == "session.updated":
break
if __name__ == "__main__":
asyncio.run(main())Zachovajte existujúce spracovanie pripájania vstupného zvuku, delta udalostí zvuku odpovede, prerušení, volaní funkcií, chýb a čistého zatvorenia soketu. Vložené vlastné funkcie sa vykonávajú vo vašom klientovi; ich výsledky vráťte prostredníctvom protokolu Realtime. Nástroje uloženého agenta sa vykonávajú v ThunderPhone.
Životný cyklus relácie a zlyhania
Jeden WebSocket predstavuje jeden hovor. Neplatné ID agenta alebo odmietnutá vložená
konfigurácia vytvorí udalosť error. Pred považovaním relácie za aktívnu počkajte na
session.updated. Zadajte skutočné vstupné a výstupné formáty a vzorkovacie frekvencie:
nesúlad frekvencie PCM prehrá zvuk príliš rýchlo alebo príliš pomaly namiesto
vytvorenia chyby overenia.
Po spustení relácie socket korektne zatvorte, keď aplikácia dokončí svoju činnosť. Vložené relácie môžu používať funkcie spúšťané klientom. Relácie s uloženým agentom používajú kompatibilné nástroje spúšťané službou ThunderPhone a ponúkajú transfer_call (a pri odchádzajúcich reláciách aj send_keypad_input) iba s call_events; tieto udalosti call.* vykonáva váš klient.
Otestujte integráciu
Začnite s minimálnym klientom WAV v jazyku Python a mono PCM16 WAV s deklarovanou vzorkovacou frekvenciou. Overte:
- Server prijme konfiguráciu a odošle
session.updated. - Vstup vytvorí udalosti prepisu a zvuku odpovede očakávanou rýchlosťou.
- Prerušenie a zrušenie odpovede zastavia zostávajúci výstupný zvuk.
- Výsledky vložených funkcií alebo nástrojov uloženého agenta sa vrátia modelu.
- Neplatný vstup vytvorí udalosť
error, ktorú váš klient spracuje. - Váš klient zatvorí soket a hovor sa zobrazí v histórii hovorov.
Referenčná dokumentácia Realtime WebSocket uvádza prijímané udalosti, zvukové formáty, polia relácie a úplné príklady.
Cena
Hovory v reálnom čase sa účtujú rovnako ako všetky ostatné hovory: podľa nákladov ich častí za cenníkové ceny našich poskytovateľov, plus poplatok za infraštruktúru a marža 17–25 %. Povolenie priebežných zmien prepisu pridáva prácu na prepise počas celej relácie; pozrite si Priebežné prepisy a Cenník.
POST /v1/realtime/sessions je samostatná spravovaná cesta LiveKit. Vytvorí
miestnosť a token účastníka s obmedzeným rozsahom; pre priame pripojenie WebSocket
nie je potrebná.
Informácie o integráciách s frameworkmi nájdete v časti Použitie ThunderPhone s Pipecat a Použitie ThunderPhone s LiveKit Agents.