Funkcióhívás hangalapú beszélgetésben
Ezen az oldalon
Funkciók futtatása hangalapú beszélgetésből
A hangalapú funkcióhívás lehetővé teszi, hogy az ügynököd valós műveleteket hajtson végre beszélgetés közben: lekérdezhet egy adatbázist, leadhat egy rendelést, küldhet e-mailt, vagy meghívhat egy külső API-t. Az ügynök a felhasználó szavai alapján dönti el, mikor hívjon meg egy függvényt.
Az ügynök felismeri az igényt
A felhasználó olyat mond, ami funkcióhívást igényel. Az ügynök generálja az argumentumokat.
Az alkalmazásod futtatja a függvényt
Megkapod az argumentumokat a `function_call_arguments.done` eseményen keresztül, és lefuttatod az üzleti logikádat.
Visszaküldöd az eredményt
Küldj egy `conversation.item.create` üzenetet `function_call_output` típussal és a megfelelő `call_id`-vel.
Az ügynök folytatja a beszélgetést
Küldj egy `response.create` üzenetet, hogy az ügynök beépítse az eredményt a szóbeli válaszába.
Függvény deklarálása
A függvényeket a session.update üzenet tools tömbjében deklarálod:
{
"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"]
}
}
]
}
}
Függvényhívás fogadása és kezelése
Amikor az ügynök úgy dönt, hogy meghív egy függvényt, az argumentumokat először streamelve, majd egyszerre kapod meg:
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;
// Függvény futtatása
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" };
}
// Eredmény visszaküldése
ws.send(JSON.stringify({
type: "conversation.item.create",
item: {
type: "function_call_output",
call_id: callId,
output: JSON.stringify(result)
}
}));
// Az ügynök folytatására való felszólítás
ws.send(JSON.stringify({
type: "response.create"
}));
}
Párhuzamos funkcióhívások
Az ügynök dönthet úgy, hogy több függvényt hív meg egyszerre. Ilyenkor több function_call_arguments.done eseményt is kapsz. A szabály a következő:
- Oldj meg minden függvényt, mielőtt válaszolsz
- Küldd be az összes eredményt, minden eredményhez egy-egy
conversation.item.createüzenettel - Küldj egyetlen
response.createüzenetet a végén
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) {
// Minden függvény megoldva
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)
}
}));
}
// Egyetlen response.create az összes kimenethez
ws.send(JSON.stringify({ type: "response.create" }));
pendingCalls.clear();
}
break;
Legjobb gyakorlatok
- Érthető leírások: a függvényeid leírásának minősége határozza meg, hogy az ügynök mikor használja őket
- Gyors végrehajtás: egy 2–3 másodpercnél tovább tartó függvény kínos csendet eredményez
- Hibakezelés: olvasható hibaüzenetet küldj vissza technikai kivételek helyett
- Szóbeli megerősítés: érzékeny műveleteknél (fizetések, törlések) kérd a felhasználó megerősítését, mielőtt végrehajtod őket
Főbb megállapítások
- A hangalapú funkcióhívás egy négy lépésből álló ciklust követ: észlelés, végrehajtás, eredmény visszaküldése, folytatás
- A függvényeket a
session.updateüzenetben deklarálod, JSON sémával a paramétereikhez - Az eredményt a
conversation.item.createüzenettel kell visszaküldeni,type: "function_call_output"értékkel - Az eredmények beküldése után mindig küldj egy
response.createüzenetet - Párhuzamos hívások esetén várj meg minden eredményt, mielőtt egyetlen
response.createüzenetet küldenél