Functieaanroepen via spraak
Op deze pagina
Functies uitvoeren tijdens een spraakgesprek
Met functieaanroepen via spraak kan uw agent tijdens een gesprek daadwerkelijke acties uitvoeren: een database bevragen, een bestelling plaatsen, een e-mail verzenden of een externe API aanroepen. De agent bepaalt zelf wanneer een functie wordt aangeroepen, op basis van wat de gebruiker zegt.
De agent identificeert de behoefte
De gebruiker zegt iets waarvoor een functieaanroep nodig is. De agent genereert de argumenten.
Uw app voert de functie uit
U ontvangt de argumenten via de gebeurtenis function_call_arguments.done en voert uw bedrijfslogica uit.
U stuurt het resultaat terug
Verzend conversation.item.create met het type function_call_output en de call_id.
De agent zet het gesprek voort
Verzend response.create zodat de agent het resultaat verwerkt in zijn gesproken antwoord.
Een functie declareren
U declareert functies in de tools-array van 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"]
}
}
]
}
}
Een functieaanroep ontvangen en afhandelen
Wanneer de agent besluit een functie aan te roepen, ontvangt u de argumenten eerst als stream en vervolgens in één keer:
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;
// Voer de functie uit
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" };
}
// Stuur het resultaat terug
ws.send(JSON.stringify({
type: "conversation.item.create",
item: {
type: "function_call_output",
call_id: callId,
output: JSON.stringify(result)
}
}));
// Vraag de agent om door te gaan
ws.send(JSON.stringify({
type: "response.create"
}));
}
Parallelle functieaanroepen
De agent kan besluiten meerdere functies tegelijk aan te roepen. U ontvangt dan meerdere function_call_arguments.done-gebeurtenissen. De regel is:
- Los elke functie op voordat u reageert
- Dien elk resultaat in, met één
conversation.item.createper resultaat - Verzend één enkele
response.createaan het einde
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) {
// Elke functie is opgelost
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)
}
}));
}
// Een enkele response.create voor alle outputs
ws.send(JSON.stringify({ type: "response.create" }));
pendingCalls.clear();
}
break;
Best practices
- Duidelijke beschrijvingen: de kwaliteit van uw functiebeschrijvingen bepaalt wanneer de agent ze gebruikt
- Snelle uitvoering: een functie die langer dan 2 of 3 seconden duurt, creëert een ongemakkelijke stilte
- Foutafhandeling: retourneer een leesbaar foutbericht in plaats van een technische exceptie
- Mondelinge bevestiging: laat bij gevoelige acties (betalingen, verwijderingen) de gebruiker bevestigen voordat u ze uitvoert
Belangrijkste punten
- Functieaanroepen via spraak volgt een cyclus van vier stappen: detectie, uitvoering, resultaat terugsturen, voortzetting
- U declareert functies in
session.updatemet een JSON-schema voor hun parameters - Het resultaat moet worden teruggestuurd via
conversation.item.createmettype: "function_call_output" - Verzend altijd
response.createna het indienen van de resultaten - Wacht bij parallelle aanroepen op elk resultaat voordat u één enkele
response.createverstuurt