Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Äänipohjainen funktiokutsu

Oppitunti 13 / 16 Päivitetty 30. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Funktioiden suorittaminen äänikeskustelun aikana
  2. Funktion määrittely
  3. Funktiokutsun vastaanottaminen ja käsittely
  4. Rinnakkaiset funktiokutsut
  5. Parhaat käytännöt
  6. Keskeiset asiat

Funktioiden suorittaminen äänikeskustelun aikana

Äänipohjainen funktiokutsu mahdollistaa sen, että agenttisi voi käynnistää todellisia toimia keskustelun aikana: tietokantakyselyt, tilauksen tekemisen, sähköpostin lähettämisen tai ulkoisen rajapinnan kutsumisen. Agentti päättää milloin funktiota kutsutaan käyttäjän puheen perusteella.

1

Agentti tunnistaa tarpeen

Käyttäjä sanoo jotain, mikä vaatii funktiokutsun. Agentti generoi argumentit.

2

Sovelluksesi suorittaa funktion

Vastaanotat argumentit `function_call_arguments.done`-tapahtuman kautta ja suoritat liiketoimintalogiikkasi.

3

Lähetät tuloksen takaisin

Lähetä `conversation.item.create` käyttäen tyyppiä `function_call_output` ja asiaankuuluvaa `call_id`:tä.

4

Agentti jatkaa keskustelua

Lähetä `response.create`, jotta agentti voi sisällyttää tuloksen puhuttuun vastaukseensa.

Funktion määrittely

Määrittelet funktiot session.update-kutsun tools-taulukossa:

{
  "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"]
        }
      }
    ]
  }
}

Funktiokutsun vastaanottaminen ja käsittely

Kun agentti päättää kutsua funktion, vastaanotat argumentit ensin virtana ja sen jälkeen kerralla:

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;

      // Suorita funktio
      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" };
  }

  // Lähetä tulos takaisin
  ws.send(JSON.stringify({
    type: "conversation.item.create",
    item: {
      type: "function_call_output",
      call_id: callId,
      output: JSON.stringify(result)
    }
  }));

  // Pyydä agenttia jatkamaan
  ws.send(JSON.stringify({
    type: "response.create"
  }));
}

Rinnakkaiset funktiokutsut

Agentti voi päättää kutsua useita funktioita samanaikaisesti. Tällöin vastaanotat useita function_call_arguments.done-tapahtumia. Sääntö on seuraava:

  1. Ratkaise jokainen funktio ennen vastaamista
  2. Lähetä jokainen tulos käyttäen yhtä conversation.item.create-kutsua tulosta kohden
  3. Lähetä yksi yksittäinen response.create lopussa
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) {
    // Jokainen funktio on ratkaistu
    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)
        }
      }));
    }
    // Yksi ainoa response.create kaikille tuloksille
    ws.send(JSON.stringify({ type: "response.create" }));
    pendingCalls.clear();
  }
  break;

Parhaat käytännöt

  • Selkeät kuvaukset: funktiokuvaustesi laatu määrittää sen, milloin agentti käyttää niitä
  • Nopea suoritus: funktio, jonka suoritus kestää yli 2–3 sekuntia, luo kiusallisen hiljaisuuden
  • Virheenkäsittely: palauta luettava virheilmoitus teknisen poikkeuksen sijaan
  • Suullinen vahvistus: arkaluonteisissa toimissa (maksut, poistot) pyydä käyttäjää vahvistamaan toiminto ennen sen suorittamista

Keskeiset asiat

  • Äänipohjainen funktiokutsu noudattaa nelivaiheista sykliä: havaitseminen, suoritus, tuloksen palauttaminen ja jatkaminen
  • Määrittelet funktiot kohdassa session.update käyttäen niiden parametreille JSON-skeemaa
  • Tulos on lähetettävä takaisin käyttäen conversation.item.create-kutsua, jossa type: "function_call_output"
  • Lähetä aina response.create tulosten lähettämisen jälkeen
  • Rinnakkaisten kutsujen yhteydessä odota kaikkia tuloksia ennen yhden response.create-kutsun lähettämistä