--- title: "Funktsioonitööriistad" description: "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 | Võimekus | Kus see töötab | Seadistus | | --- | --- | --- | | [Sisseehitatud tööriistad](/et/guides/built-in-tools) | ThunderPhone | Viibajuhised; mõned tööriistad vajavad ka agendi seadistust | | [Rakenduseühendused](/et/guides/connect-apps) | ThunderPhone ja ühendatud teenusepakkuja | Ühenda konto ja lisa heakskiidetud toimingud | | [API-ühendused](/et/guides/api-connections) ja funktsioonitööriistad | Sinu HTTP API | Määratle lõpp-punkt ja skeem või võta funktsioonikutsed vastu veebikonksu kaudu | | [MCP-serverid](/et/guides/mcp-servers) | Kaug-MCP-server | Lisa server, tuvasta selle tööriistad ja lisa see agendile | --- ## Tööriista skeem Iga tööriist järgib seda struktuuri: ```json { "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 | Väli | Tüüp | Kohustuslik | Kirjeldus | |-------|------|----------|-------------| | `timeout` | number | Ei | Maksimaalne täitmisaeg sekundites (vaikimisi: `20`, maksimaalselt: `180`) | ### Funktsiooni määratlus | Väli | Tüüp | Kohustuslik | Kirjeldus | |-------|------|----------|-------------| | `name` | string | Jah | Tööriista kordumatu identifikaator | | `description` | string | Jah | Selgitab AI-le, millal seda tööriista kasutada | | `parameters` | object | Jah | Tööriista argumentide JSON-skeem | ### Lõpp-punkti konfiguratsioon | Väli | Tüüp | Kohustuslik | Kirjeldus | |-------|------|----------|-------------| | `url` | string | Jah | Sinu API lõpp-punkti URL | | `method` | string | Ei | HTTP-meetod (vaikimisi: `POST`) | | `headers` | object | Ei | Kaasatavad kohandatud päised | `endpoint`-i konfiguratsiooni **ei** saadeta AI-mudelile — ThunderPhone kasutab seda ainult tööriistakutse käivitamiseks. --- ## Kaks kutsumise teed See, millise päringu sinu server saab, sõltub sellest, kas tööriistal on `endpoint`: | | Tööriist **koos** `endpoint`-iga | Tööriist **ilma** `endpoint`-ita | |---|---|---| | Kuhu päring saadetakse | Otse aadressile `endpoint.url` | Sinu organisatsiooni [pärand-veebikonksu URL](/api-reference/organizations#legacy-single-url-webhook) | | Sisu | **Ainult tööriista argumendid** | Ümbris `telephony.tool` / `web.tool` | | Päised | Sinu `endpoint.headers` + `X-ThunderPhone-Call-ID` + `X-ThunderPhone-Signature` | `Content-Type` + `X-ThunderPhone-Signature` | | Allkirjastamisvõti | Organisatsiooni veebikonksu saladus | Organisatsiooni veebikonksu saladus | 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 ```http POST /appointments/search HTTP/1.1 Host: api.example.com Content-Type: application/json X-ThunderPhone-Signature: abc123... X-ThunderPhone-Call-ID: 987654321 X-Api-Key: your-api-key ``` Sinu `endpoint.headers` kohandatud päised lisatakse alati muutmata kujul koos kahe ThunderPhone'i nimeruumiga päisega: - `X-ThunderPhone-Signature` — päringu keha täpsete baitide HMAC-SHA256, mis on võtmega sinu **organisatsiooni veebikonksu saladus** - `X-ThunderPhone-Call-ID` — praeguse kõne ID `Content-Type: application/json` määratakse, välja arvatud juhul, kui sinu `endpoint.headers` selle alistab — kohandatud `Content-Type` on ülimuslik. Allkiri on võtmega organisatsioonitaseme veebikonksu saladus, mis pärineb [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook). Kui sinu organisatsioon pole kunagi pärand-veebikonksu seadistanud, puudub saladus ja tööriistakutsed sisaldavad **ainult** `X-ThunderPhone-Call-ID` — töötleja, mis ebaõnnestub puuduva allkirja korral, lükkaks need tagasi. Seadista saladuse saamiseks pärand-veebikonks või lisa oma jagatud saladus `endpoint.headers`-i. ### Päringu keha `POST` / `PUT` / `PATCH` puhul sisaldab keha **ainult** tööriista argumente (ilma ümbriseta), mis on kanooniliselt serialiseeritud (sorditud võtmed, kompaktsed eraldajad): ```json {"date":"2025-01-02","service":"consultation"} ``` `GET` / `DELETE` puhul saadetakse argumendid **päringuparameetritena** ja keha on tühi — allkiri arvutatakse siis tühja baitstringi põhjal. Vaata [Veebikonksu allkirjade kontrollimine](/et/guides/verify-webhook-signatures). ### Vastus Tagasta tööriista tulemusega JSON-vastus: ```json { "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": ""}`; 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](/et/webhooks/events), mis saadetakse veebikonksu endpointidele pärast käivitamist, **on** see päring käivitamine — sinu HTTP-vastus on tööriista tulemus. ```json { "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 endpointi kutsete puhul. Päring allkirjastatakse organisatsiooni veebikonksu saladusega töötlemata keha põhjal nagu iga teinegi veebikonks. Tellitud [veebikonksu endpointid](/et/webhooks/endpoints) saavad lisaks mitteblokeeriva `telephony.tool` / `web.tool` **teavituse pärast** iga tööriista käivitamist (olenemata sellest, milline tee selle käivitas), koos tööriista vastusega — kasulik auditeerimisjälgede jaoks. Vaata [sündmuste kataloogi](/et/webhooks/events). --- ## Allkirja kinnitamine Otsesed tööriistakutsed allkirjastatakse samamoodi nagu veebikonksud: - HMAC-SHA256 täpsete päringukeha baitide põhjal (kanooniline JSON — sorditud võtmed, ilma lisatühikuteta) - Võtmeks on sinu organisatsiooni veebikonksu saladus - `GET`- ja `DELETE`-tööriistad allkirjastavad tühja baidistringi ```python Python import hmac import hashlib def verify_tool_call(body: bytes, signature: str, secret: str) -> bool: expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature) @app.post("/appointments/search") async def search_appointments(request: Request): body = await request.body() signature = request.headers.get("X-ThunderPhone-Signature", "") if not verify_tool_call(body, signature, WEBHOOK_SECRET): 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} ``` ```javascript Node.js app.post('/appointments/search', express.raw({type: 'application/json'}), (req, res) => { const signature = req.headers['x-thunderphone-signature'] || ''; const expected = crypto .createHmac('sha256', WEBHOOK_SECRET) .update(req.body) .digest('hex'); if (!signature || signature.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) { 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 näited — sealhulgas tühja päringukeha juhtum ja hoiatus saladuse puudumise kohta — leiad jaotisest [Veebikonksu allkirjade kinnitamine](/et/guides/verify-webhook-signatures). --- ## Näide: täielik broneerimisvoog Siin on tööriistade komplekt täieliku kohtumiste broneerimissüsteemi jaoks: ```json { "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" } } } ] } ``` --- ## Parimad tavad Väli `description` aitab AI-l mõista, **millal** tööriista kasutada. Kirjelda täpselt, mida see teeb ja millal seda kasutada. Tagasta veateated, millest AI aru saab: `{"error": "No slots available for that date"}`, mitte üldised 500 vead. Tagasta ainult see, mida AI vajab vestluse jätkamiseks. Suured andmekoormad aeglustavad vastamisaega. Märgi väljad `required`, ainult kui see on tõesti vajalik. AI küsib kasutajalt kohustuslikku teavet enne tööriista kutsumist. --- ## Seotud Käivita platvormi hallatavaid kõnetoiminguid ilma lõpp-punkti määratlemata. Platvormi hallatavad tööriistad HubSpoti, Salesforce'i, Slacki, Google Calendari, Google Sheetsi ja Cal.comi jaoks — lõpp-punkti pole vaja. Lisa MCP-server ja lase agendil selle tööriistu kutsuda. Korduskasutatavad REST-integratsioonid, mille saad agentidele lisada. Üks kontrolliabiline webhookide ja tööriistakutsete jaoks.