Funktsioonitööriistad

Anna oma AI-agentidele funktsioonitööriistad, mis kutsuvad vestluse ajal väliseid API-sid, et tuua kliendiandmeid, broneerida kohtumisi ja uuendada kirjeid, kasutades tüübistatud parameetreid.

Funktsioonitööriistad võimaldavad sinu AI häälagentidel telefonikõnede ajal väliseid API-sid kutsuda. Kasuta neid kliendiandmete otsimiseks, saadavuse kontrollimiseks, kohtumiste broneerimiseks või mis tahes toimingu tegemiseks, mida sinu taustsüsteem toetab.

Kuidas see toimib#

1. Määratled tööriistad skeemiga (milliseid argumente tööriist aktsepteerib)
2. Esitad endpoint-i konfiguratsiooni (kus ThunderPhone sinu API-t kutsub) või jätad selle ära, et saada tööriistakutseid oma organisatsiooni veebikonksu kaudu
3. Kõne ajal otsustab AI vestluse põhjal, millal tööriista kasutada
4. ThunderPhone kutsub sinu lõpp-punkti tööriista argumentidega
5. Sinu API vastus edastatakse vestluse jätkamiseks tagasi AI-le

Tööriista skeem#

Iga tööriist järgib seda struktuuri:

{
  "type": "function",
  "function": {
    "name": "search_appointments",
    "description": "Find available appointment slots for a given date",
    "parameters": {
      "type": "object",
      "properties": {
        "date": {
          "type": "string",
          "description": "Date in YYYY-MM-DD format"
        },
        "service": {
          "type": "string",
          "description": "Type of service (e.g., 'consultation', 'follow-up')"
        }
      },
      "required": ["date"]
    }
  },
  "endpoint": {
    "url": "https://api.example.com/appointments/search",
    "method": "POST",
    "headers": {
      "X-Api-Key": "your-api-key"
    }
  },
  "timeout": 120
}

Tööriista konfiguratsioon#

Funktsiooni määratlus#

Lõpp-punkti konfiguratsioon#

Kaks kutsumise teed#

See, millise päringu sinu server saab, sõltub sellest, kas tööriistal on endpoint:

Mõlemad teed on blokeerivad — AI ootab tulemuse järel keset lauset. Vaikimisi ajalõpp on 20 s; pikema täitmisaja lubamiseks määra tööriista tipptasemel timeout, kuni platvormi 180 s maksimaalse piirini. Hoia töötlejad kiired. Kombineerimine on lubatud: kõne puhul, mille organisatsioonil on veebikonksu URL, kutsutakse endpoint-iga tööriistad otse ning ülejäänud kasutavad veebikonksu.

Otsesed endpointi kutsed#

Kui AI käivitab tööriista, millel on endpoint, saadab ThunderPhone päringu sinu URL-ile:

Päringu päised#

POST /appointments/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-ThunderPhone-Signature-V2: t=1767225600,v1=5f2c...
X-ThunderPhone-Signature: abc123...
X-ThunderPhone-Call-ID: 987654321
X-ThunderPhone-From-Number: +14155550199
X-ThunderPhone-To-Number: +14155550100
X-ThunderPhone-Call-Direction: inbound
X-Api-Key: your-api-key

Sinu endpoint.headers kohandatud päised lisatakse alati sõna-sõnalt koos järgmiste ThunderPhone'i nimeruumiga päistega:

• X-ThunderPhone-Signature-V2 — ajatempliga HMAC-SHA256 meetodi, tee, päringuparameetrite ja keha kohta, võtmena sinu organisatsiooni webhooki salavõti. Kontrolli seda ja lükka tagasi üle 5 minuti vanused päringud; vaata Webhooki allkirjade kontrollimine
• X-ThunderPhone-Signature — pärand-HMAC-SHA256 päringu keha täpsete baitide kohta, sama võtmega, saadetakse endiselt olemasolevatele kontrollijatele
• X-ThunderPhone-Call-ID — praeguse kõne ID
• X-ThunderPhone-From-Number ja X-ThunderPhone-To-Number — kõne From- ja To-numbrid E.164 vormingus. Neil on sama tähendus nagu from_number ja to_number väljadele sündmuses telephony.complete: väljamineva kõne korral on From sinu agendi number ja To on isik, kellele helistatakse. Number jäetakse välja, kui helistaja ID on varjatud või ei ole telefoninumber
• X-ThunderPhone-Call-Direction — inbound või outbound, et saaksid kindlaks teha, kumb number kuulub kliendile

Kõnenumbrite päised saadetakse ainult telefonikõnede korral. Veebi-, vidina-, reaalajas ja brauseri Talk-testid ei sisalda telefoninumbrit ning jätavad need välja. Agendi redaktori testkõned ja AI-simulatsioonid sisaldavad simuleeritud helistaja numbrit. Allkirjad ei kata päiseid: V2 allkirjastab ajatembli, meetodi, tee, päringuparameetrid ja keha. Kui vajad allkirjastatud numbreid, loe need hoopis kehast: retell päringuvorming sisaldab kõiki kolme ning vapi sisaldab kliendi numbrit.

Content-Type: application/json määratakse, välja arvatud juhul, kui sinu endpoint.headers selle alistab — kohandatud Content-Type on ülimuslik.

Taotluse vorming#

Igal API-ühendusel on säte request_format. Vali vapi või retell, kui imporditud tööriist peaks jätkama sellele platvormile loodud lõpp-punkti kutsumist. Uute ja olemasolevate ühenduste vaikeseade on standard.

POST / PUT / PATCH päringute puhul serialiseerib ThunderPhone valitud ümbrise kanooniliselt (sorditud võtmed, kompaktsed eraldajad). Mõlemad allkirjad katavad täpselt neid baite.

Standard#

standard saadab ainult tööriista argumendid, ilma ümbriseta. See on vaikeseade ja säilitab ThunderPhone'i algse päringu sisu bait-baidilt:

{"date":"2025-01-02","service":"consultation"}

Vapi#

vapi saadab Vapi tool-calls serverisõnumi Vapi dokumenteeritud kujul. call.id on ThunderPhone'i kõne ID. Telefonikõnedes on call.customer.number teise osapoole number, nagu Vapi kõneobjektis: sissetuleva kõne korral helistaja, väljamineva kõne korral isik, kellele helistatakse. See jäetakse välja, kui number on varjatud või ei ole telefoninumber. Tööriistakutse id on kutsumise jaoks kordumatu ja seda kasutatakse uuesti lõpp-punkti tulemuse sobitamiseks. Kõne kuvatakse nii toolCallList-is kui ka toolWithToolCallList-is ning function.arguments on JSON-objekt:

{
  "message": {
    "type": "tool-calls",
    "timestamp": 1725000000123,
    "call": { "id": "987654321" },
    "toolCallList": [
      {
        "id": "call_00112233445566778899aabbccddeeff",
        "type": "function",
        "function": {
          "name": "search_appointments",
          "arguments": { "date": "2025-01-02", "service": "consultation" }
        }
      }
    ],
    "toolWithToolCallList": [
      {
        "type": "function",
        "function": { "name": "search_appointments" },
        "toolCall": {
          "id": "call_00112233445566778899aabbccddeeff",
          "type": "function",
          "function": {
            "name": "search_appointments",
            "arguments": { "date": "2025-01-02", "service": "consultation" }
          }
        }
      }
    ]
  }
}

Vapi-spetsiifilisi välju, nagu assistant, artifact ja täielik call-objekt, ei saadeta.

Tagasta Vapi vastuse ümbris sobiva tööriistakutse ID-ga:

{
  "results": [
    {
      "toolCallId": "call_00112233445566778899aabbccddeeff",
      "result": "{\"available_slots\":[\"9:00 AM\",\"2:00 PM\"]}"
    }
  ]
}

ThunderPhone annab AI-le pakkimata result-stringi. Ühilduvuse tagamiseks lõpp-punktidega, mis juba tagastavad JSON-väärtuse, aktsepteerib see ka JSON-väärtust. error, mis on esitatud result asemel, tagastatakse AI-le tööriistaveana. Kui lõpp-punkt tagastab vigase või mittevastava Vapi ümbrise, salvestab ThunderPhone hoiatuse ja kasutab kõne nurjumise asemel standardset vastuse parsimist.

Retell#

retell saadab Retelli kohandatud funktsiooni jaoks dokumenteeritud päringu:

{
  "name": "search_appointments",
  "call": {
    "call_id": "987654321",
    "from_number": "+14155550199",
    "to_number": "+14155550100",
    "direction": "inbound"
  },
  "args": { "date": "2025-01-02", "service": "consultation" }
}

Telefonikõnedes sisaldab objekt call välju call_id, from_number, to_number ja direction (inbound või outbound), mille nimed vastavad Retelli telefonikõne objekti väljadele. Need ühtivad kõnenumbrite päistega ning erinevalt päistest katavad neid mõlemad allkirjad. Varjatud või telefoninumbriks mitteolev number jäetakse välja. Veebi-, vidina-, reaalaja- ja brauseri Talki testides sisaldab see ainult välja call_id. ThunderPhone ei lisa Retellile omaseid välju, mida ta ei saa edastamisel tegelikult pakkuda, näiteks agent_id, transcript, transcript_object, metadata või dünaamilised muutujad. Retell aktsepteerib mis tahes vastuse sisu; ThunderPhone edastab selle standardse vastuse töötlemise abil.

GET / DELETE päringute puhul saadetakse argumendid päringuparameetritena ning sisu on tühi olenemata sättest request_format. V2 allkiri katab saadetud päringustringi; pärandallkiri arvutatakse tühja baidistringi põhjal. Vaata veebikonksu allkirjade kontrollimist.

Vastus#

Tagasta tööriista tulemusega JSON-vastus:

{
  "available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"],
  "timezone": "America/Los_Angeles"
}

Vastus vormindatakse ja antakse AI-le vestluse jätkamiseks. Mitte-JSON-vastused mähitakse kujule {"data": "<text>"}; ajalõppudest ja ühenduse tõrgetest teatatakse AI-le vigadena, et agent saaks vabandada ja jätkata, mitte takerduda.

Veebikonksurežiimi saatmine#

Tööriistad, millel pole endpoint-i, saadetakse sinu organisatsiooni pärand- veebikonksu URL-ile allkirjastatud telephony.tool (telefonikõned) või web.tool (veebikõned) päringuna. Erinevalt auditeerimisteavitustest, mis saadetakse veebikonksu endpointidele pärast käivitamist, on see päring käivitamine — sinu HTTP-vastus on tööriista tulemus.

{
  "type": "telephony.tool",
  "data": {
    "call_id": 987654321,
    "tool_name": "search_appointments",
    "arguments": { "date": "2026-04-21" },
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  }
}

web.tool sisaldab väljade from_number / to_number asemel välja origin_domain. Vasta tööriista tulemusega JSON-vormingus — sama vastuseleping nagu otseste lõpp-punkti väljakutsete korral. Päring on allkirjastatud organisatsiooni webhooki saladusega ja sisaldab mõlemat allkirjapäist, nagu iga teinegi webhook.

Allkirja kinnitamine#

Otsesed tööriistakutsed allkirjastatakse samamoodi nagu veebikonksud, kasutades sinu organisatsiooni veebikonksu salajast võtit:

• X-ThunderPhone-Signature-V2 allkirjastab ajatembli, meetodi, tee ja päringu saadetud kujul ning täpsed päringukeha baidid. Lükka tagasi päringud, mille ajatempel erineb sinu kellaajast rohkem kui 5 minutit.
• X-ThunderPhone-Signature (pärand) allkirjastab ainult päringukeha baidid ning tühja baidistringi GET / DELETE puhul. Seda saadetakse endiselt muutmata kujul.

SDK abifunktsioonid kontrollivad V2 päist, sealhulgas 5-minutilist ajavahemikku:

import json
 
from fastapi import FastAPI, HTTPException, Request
from thunderphone import verify_signature
 
app = FastAPI()
 
@app.post("/appointments/search")
async def search_appointments(request: Request):
    body = await request.body()
    query = request.scope.get("query_string", b"").decode("latin-1")
    path = request.url.path + (f"?{query}" if query else "")
 
    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=WEBHOOK_SECRET,
        method=request.method,
        path=path,
        body=body,
    ):
        raise HTTPException(status_code=401)
 
    data = json.loads(body)
    date = data["date"]
 
    # Look up availability
    slots = await get_available_slots(date)
 
    return {"available_slots": slots}

import express from "express";
import { verifySignature } from "@thunderphone/sdk";
 
app.post('/appointments/search', express.raw({type: 'application/json'}), (req, res) => {
  const ok = verifySignature({
    header: req.header('X-ThunderPhone-Signature-V2'),
    secret: WEBHOOK_SECRET,
    method: req.method,
    path: req.originalUrl,
    body: req.body,
  });
  if (!ok) return res.status(401).send('Invalid signature');
 
  const { date, service } = JSON.parse(req.body);
 
  // Look up availability
  const slots = getAvailableSlots(date, service);
 
  res.json({ available_slots: slots });
});

Täielikud juhised — allkirjastatud string, läbitöötatud näide, SDK-ta kood, juhtumid GET / DELETE ja salajase võtme puudumise hoiatus — leiad jaotisest Veebikonksu allkirjade kontrollimine.

Näide: täielik broneerimisvoog#

Siin on tööriistade komplekt täieliku kohtumiste broneerimissüsteemi jaoks:

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_appointments",
        "description": "Find available appointment slots",
        "parameters": {
          "type": "object",
          "properties": {
            "date": { "type": "string", "description": "YYYY-MM-DD" },
            "service": { "type": "string" }
          },
          "required": ["date"]
        }
      },
      "endpoint": {
        "url": "https://api.example.com/appointments/search",
        "method": "POST",
        "headers": { "X-Api-Key": "key" }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "book_appointment",
        "description": "Book an appointment at a specific time",
        "parameters": {
          "type": "object",
          "properties": {
            "date": { "type": "string", "description": "YYYY-MM-DD" },
            "time": { "type": "string", "description": "HH:MM format" },
            "customer_name": { "type": "string" },
            "customer_phone": { "type": "string" }
          },
          "required": ["date", "time", "customer_name"]
        }
      },
      "endpoint": {
        "url": "https://api.example.com/appointments/book",
        "method": "POST",
        "headers": { "X-Api-Key": "key" }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "cancel_appointment",
        "description": "Cancel an existing appointment",
        "parameters": {
          "type": "object",
          "properties": {
            "confirmation_number": { "type": "string" }
          },
          "required": ["confirmation_number"]
        }
      },
      "endpoint": {
        "url": "https://api.example.com/appointments/cancel",
        "method": "POST",
        "headers": { "X-Api-Key": "key" }
      }
    }
  ]
}

Käivita tööriist kõne alguses#

Tööriist võib käivituda automaatselt ka iga telefonikõne alguses, enne kui agent ütleb oma esimese sõna, et tervitus saaks tulemust kasutada. Tavapärane juhtum on CRM-i päring helistaja numbri alusel: „Tere tagasi, Arthi! Kas soovid oma tavapärast tellimust?“

Ava juhtpaneelil API-ühendus ja määra Millal see käivitub väärtuseks Iga telefonikõne alguses, seejärel sisesta väärtus, mille iga parameeter saab. API kaudu määra integratsiooni trigger väärtuseks call_start ja selle call_start_arguments (API-ühendused) või lisa tekstisisesele tööriistale plokk call_start:

{
  "type": "function",
  "function": {
    "name": "get_contact_by_phone",
    "description": "Look up a customer by phone number.",
    "parameters": {
      "type": "object",
      "properties": {
        "business_id": {"type": "string"},
        "phone_number": {"type": "string"}
      },
      "required": ["business_id", "phone_number"]
    }
  },
  "endpoint": {"url": "https://crm.example.com/contacts/lookup"},
  "call_start": {
    "arguments": {
      "business_id": "a0a81c23",
      "phone_number": "{{caller_number}}"
    }
  }
}

Argumentidel peab olema väärtus iga kohustusliku parameetri jaoks, sest kõne alguses ei sisesta keegi midagi. Väärtused on stringid, arvud või tõeväärtused. Need salvestatakse ja tagastatakse lihttekstina ning agent näeb neid, seega hoia saladusi, näiteks API-võtmeid, ühenduse päistes, mitte siin. Stringid võivad kasutada järgmisi kohatäiteid:

Käitumine:

• Päring on sama, mille saadavad agendi enda tööriistakutsed (sama lõpp-punkt, päised, päringuvorming ja signatuur).
• Tööriist käivitub kõne alguses ning töötab ajal, mil esitatakse ühendustoon, sissejuhatus või salvestusteade. Tervitus ootab tulemust sellest hetkest alates kuni umbes 3 sekundit. Aeglasem tulemus antakse agendile ülejäänud kõne ajaks kohe, kui see saabub. Väljamineva kõne korral käivitub see kõne algatamisel, seega töötab see iga katse puhul, ka siis, kui keegi ei vasta.
• Agendi puhul, kus helistaja räägib esimesena, ei ole tervitust, mida oodata; agent saab tulemuse kohe, kui see saabub.
• Tulemus antakse agendile kogu kõne kontekstina. Ütle agendile oma viibas, kuidas seda kasutada; vastasel juhul seda ette ei loeta.
• Kui tööriist ebaõnnestub või aegub, tervitab agent helistajat tavapäraselt ega ütle selle kohta midagi.
• Agent saab tööriista ka hiljem kõne jooksul ise kutsuda.
• See töötab telefonikõnedel, sealhulgas juhtpaneelilt sinu telefonile tehtud testkõnedel, ja AI-simulatsioonides, mis saadavad sinu lõpp-punktile simuleeritud helistaja numbri. See ei tööta brauseri Räägi testides ega veebividina seanssides, millel puudub helistaja number, kõnedel, mille puhul helistaja ID on varjatud, ega sammudega agentidel.
• Agent käivitab korraga kuni kolm kõne alguse tööriista.

Maini tulemust oma viibas, et agent teaks, kuidas seda kasutada, näiteks: „Kui kõne alguse päring leidis helistaja, tervita teda eesnimega.”

Parimad tavad#

Seotud#