Apelarea funcțiilor prin voce
Pe această pagină
Executarea funcțiilor într-o conversație vocală
Apelarea funcțiilor prin voce permite agentului dumneavoastră să declanșeze acțiuni reale în timpul unei conversații: interogarea unei baze de date, plasarea unei comenzi, trimiterea unui e-mail sau apelarea unui API extern. Agentul decide când să apeleze o funcție în funcție de ceea ce spune utilizatorul.
Agentul identifică necesitatea
Utilizatorul spune ceva care necesită un apel de funcție. Agentul generează argumentele.
Aplicația dumneavoastră execută funcția
Primiți argumentele prin evenimentul function_call_arguments.done și executați logica de afaceri.
Trimiteți rezultatul înapoi
Trimiteți conversation.item.create cu tipul function_call_output și call_id.
Agentul continuă conversația
Trimiteți response.create pentru ca agentul să integreze rezultatul în răspunsul său vocal.
Declararea unei funcții
Declarați funcțiile în tabloul tools al lui 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"]
}
}
]
}
}
Primirea și gestionarea unui apel de funcție
Când agentul decide să apeleze o funcție, primiți argumentele sub formă de flux, apoi toate deodată:
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;
// Run the function
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" };
}
// Send back the result
ws.send(JSON.stringify({
type: "conversation.item.create",
item: {
type: "function_call_output",
call_id: callId,
output: JSON.stringify(result)
}
}));
// Ask the agent to continue
ws.send(JSON.stringify({
type: "response.create"
}));
}
Apeluri de funcții paralele
Agentul poate decide să apeleze mai multe funcții simultan. Veți primi apoi mai multe evenimente function_call_arguments.done. Regula este:
- Rezolvați fiecare funcție înainte de a răspunde
- Trimiteți fiecare rezultat, cu câte un
conversation.item.createper rezultat - Trimiteți un singur
response.createla final
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) {
// Every function is resolved
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)
}
}));
}
// A single response.create for all the outputs
ws.send(JSON.stringify({ type: "response.create" }));
pendingCalls.clear();
}
break;
Cele mai bune practici
- Descrieri clare: calitatea descrierilor funcțiilor dumneavoastră determină momentul în care agentul le utilizează
- Execuție rapidă: o funcție care durează mai mult de 2 sau 3 secunde creează o tăcere stânjenitoare
- Gestionarea erorilor: returnați un mesaj de eroare lizibil în loc de o excepție tehnică
- Confirmare vocală: pentru acțiuni sensibile (plăți, ștergeri), cereți utilizatorului să confirme înainte de a le executa
Puncte cheie
- Apelarea funcțiilor prin voce urmează un ciclu în patru pași: detectare, execuție, returnarea rezultatului, continuare
- Declarați funcțiile în
session.updatecu o schemă JSON pentru parametrii lor - Rezultatul trebuie trimis înapoi prin
conversation.item.createcutype: "function_call_output" - Trimiteți întotdeauna
response.createdupă submiterea rezultatelor - Pentru apelurile paralele, așteptați fiecare rezultat înainte de a trimite un singur
response.create