Události klient–server
Na této stránce
Zprávy, které odesíláš
API Voice Agent funguje výměnou událostí ve formátu JSON přes WebSocket. V této lekci projdeš každou událost, kterou může tvoje aplikace odeslat na server. Každá z nich hraje v cyklu konverzace specifickou roli.
| Událost | Popis | Kdy ji použít |
|---|---|---|
| session.update | Konfigurace relace | Při spuštění a při změně konfigurace |
| input_audio_buffer.append | Odeslání části zvuku v base64 | Průběžně během nahrávání |
| input_audio_buffer.commit | Potvrzení zvukové vyrovnávací paměti | V režimu push-to-talk |
| input_audio_buffer.clear | Vyprázdnění paměti bez zpracování | Pro zrušení nahrávání |
| conversation.item.create | Přidání zprávy nebo výsledku funkce | Historie, kontext, výsledky funkcí |
| conversation.item.delete | Smazání položky podle ID | Čištění konverzace |
| response.create | Žádost o odpověď | V manuálním režimu (automaticky s VAD) |
| response.cancel | Zrušení probíhající odpovědi | Když uživatel přeruší řeč |
conversation.item.create
Tato událost ti umožňuje vložit zprávy do konverzace bez použití zvukového streamu. Pokrývá tři hlavní případy.
Přidání textové zprávy uživatele
{
"type": "conversation.item.create",
"item": {
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "What's the status of my order 12345?"
}
]
}
}
Vložení historie konverzace
Než hlasová konverzace začne, můžeš předem vyplnit historii dřívějšími výměnami, abys agentovi poskytl kontext:
{
"type": "conversation.item.create",
"item": {
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello, I'm your assistant. How can I help you?"
}
]
}
}
Vrácení výsledku funkce
Po spuštění volání funkce odešleš výsledek zpět pomocí této události (viz lekce 13 o volání funkcí):
{
"type": "conversation.item.create",
"item": {
"type": "function_call_output",
"call_id": "call_abc123",
"output": "{\"status\": \"shipped\", \"tracking\": \"FR123456789\"}"
}
}
conversation.item.delete
Smaže položku konverzace podle jejího ID:
{
"type": "conversation.item.delete",
"item_id": "item_audio_001"
}
To je užitečné pro odstranění nesprávné zprávy nebo pro zabránění přílišnému růstu historie konverzace.
response.create a response.cancel
response.create explicitně žádá server o vygenerování odpovědi. V režimu VAD to server udělá sám, jakmile detekuje konec řeči:
{
"type": "response.create"
}
response.cancel zastaví odpověď, která se právě generuje. Je to užitečné, když uživatel mluví přes agenta:
{
"type": "response.cancel"
}
Klíčové poznatky
- Z klienta na server lze odeslat osm typů událostí
session.updatekonfiguruje relaci a lze ji odeslat vícekrátconversation.item.createumožňuje přidat text, historii nebo výsledky funkcíresponse.createje vyžadován v manuálním režimu, v režimu VAD je automatickýresponse.cancelumožňuje přerušit agenta, když uživatel znovu začne mluvit