Wywoływanie funkcji głosowych
Na tej stronie
Uruchamianie funkcji podczas rozmowy głosowej
Wywoływanie funkcji głosowych pozwala Twojemu agentowi podejmować rzeczywiste działania w trakcie rozmowy: odpytywać bazę danych, składać zamówienie, wysyłać e-mail lub wywoływać zewnętrzne API. Agent sam decyduje, kiedy wywołać funkcję, w zależności od tego, co powie użytkownik.
Agent rozpoznaje potrzebę
Użytkownik mówi coś, co wymaga wywołania funkcji. Agent generuje odpowiednie argumenty.
Twoja aplikacja uruchamia funkcję
Otrzymujesz argumenty poprzez zdarzenie `function_call_arguments.done` i wykonujesz swoją logikę biznesową.
Wysyłasz wynik z powrotem
Wyślij `conversation.item.create` z typem `function_call_output` oraz identyfikatorem `call_id`.
Agent kontynuuje rozmowę
Wyślij `response.create`, aby agent uwzględnił wynik w swojej odpowiedzi głosowej.
Deklarowanie funkcji
Funkcje deklarujesz w tablicy tools obiektu session.update:
{
"type": "session.update",
"session": {
"tools": [
{
"type": "function",
"name": "get_balance",
"description": "Gets the balance of a customer's bank account",
"parameters": {
"type": "object",
"properties": {
"client_id": {
"type": "string",
"description": "Customer ID"
}
},
"required": ["client_id"]
}
}
]
}
}
Odbieranie i obsługa wywołania funkcji
Gdy agent zdecyduje się wywołać funkcję, otrzymujesz argumenty najpierw jako strumień, a następnie całość naraz:
let functionArgs = "";
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "response.function_call_arguments.delta":
functionArgs += event.delta;
break;
case "response.function_call_arguments.done":
const args = JSON.parse(event.arguments);
const callId = event.call_id;
const functionName = event.name;
// Uruchom funkcję
handleFunctionCall(functionName, args, callId);
break;
}
});
async function handleFunctionCall(name, args, callId) {
let result;
switch (name) {
case "get_balance":
result = await getBalance(args.client_id);
break;
default:
result = { error: "Unknown function" };
}
// Wyślij wynik z powrotem
ws.send(JSON.stringify({
type: "conversation.item.create",
item: {
type: "function_call_output",
call_id: callId,
output: JSON.stringify(result)
}
}));
// Poproś agenta o kontynuację
ws.send(JSON.stringify({
type: "response.create"
}));
}
Równoległe wywołania funkcji
Agent może zdecydować się na jednoczesne wywołanie kilku funkcji. Wtedy otrzymasz kilka zdarzeń function_call_arguments.done. Zasada jest następująca:
- Rozwiąż każdą funkcję przed odpowiedzią
- Prześlij każdy wynik, używając jednego
conversation.item.createna wynik - Wyślij pojedyncze
response.createna końcu
const pendingCalls = new Map();
let expectedCalls = 0;
case "response.function_call_arguments.done":
const result = await executeFunction(event.name, event.arguments);
pendingCalls.set(event.call_id, result);
if (pendingCalls.size === expectedCalls) {
// Każda funkcja została rozwiązana
for (const [callId, output] of pendingCalls) {
ws.send(JSON.stringify({
type: "conversation.item.create",
item: {
type: "function_call_output",
call_id: callId,
output: JSON.stringify(output)
}
}));
}
// Pojedyncze response.create dla wszystkich wyników
ws.send(JSON.stringify({ type: "response.create" }));
pendingCalls.clear();
}
break;
Najlepsze praktyki
- Jasne opisy: jakość opisów Twoich funkcji decyduje o tym, kiedy agent będzie z nich korzystał
- Szybkie wykonanie: funkcja trwająca dłużej niż 2–3 sekundy tworzy niezręczną ciszę
- Obsługa błędów: zwracaj czytelny komunikat o błędzie zamiast technicznego wyjątku
- Potwierdzenie głosowe: w przypadku działań wrażliwych (płatności, usuwanie) poproś użytkownika o potwierdzenie przed ich wykonaniem
Kluczowe wnioski
- Wywoływanie funkcji głosowych przebiega w czterech krokach: wykrycie, wykonanie, zwrócenie wyniku i kontynuacja
- Funkcje deklarujesz w
session.update, używając schematu JSON dla ich parametrów - Wynik musi zostać odesłany przez
conversation.item.createztype: "function_call_output" - Zawsze wysyłaj
response.createpo przesłaniu wyników - W przypadku wywołań równoległych poczekaj na wszystkie wyniki przed wysłaniem pojedynczego
response.create