--- title: "Funkčné nástroje" description: "Poskytnite svojim AI agentom funkčné nástroje, ktoré počas konverzácie volajú externé API — načítajú údaje o zákazníkoch, rezervujú termíny, aktualizujú záznamy — s typovanými parametrami." --- Funkčné nástroje umožňujú vašim AI agentom počas telefonických hovorov volať externé API. Použite ich na vyhľadávanie údajov o zákazníkoch, kontrolu dostupnosti, rezervovanie termínov alebo vykonanie ľubovoľnej akcie, ktorú váš backend podporuje. ## Ako to funguje 1. Definujete nástroje pomocou schémy (aké argumenty nástroj prijíma) 2. Poskytnete konfiguráciu `endpoint` (kam ThunderPhone volá vaše API) — alebo ju vynecháte, aby ste prijímali volania nástrojov na webhooku organizácie 3. Počas hovoru sa AI na základe konverzácie rozhodne, kedy použiť nástroj 4. ThunderPhone zavolá váš endpoint s argumentmi nástroja 5. Odpoveď vášho API sa odošle späť AI na pokračovanie v konverzácii | Funkcia | Kde sa spúšťa | Nastavenie | | --- | --- | --- | | [Vstavané nástroje](/sk/guides/built-in-tools) | ThunderPhone | Pokyny v prompte; niektoré nástroje vyžadujú aj nastavenie agenta | | [Pripojenia aplikácií](/sk/guides/connect-apps) | ThunderPhone a pripojený poskytovateľ | Pripojte účet a priraďte schválené akcie | | [Pripojenia API](/sk/guides/api-connections) a funkčné nástroje | Vaše HTTP API | Definujte endpoint a schému alebo prijímajte volania funkcií cez webhook | | [Servery MCP](/sk/guides/mcp-servers) | Vzdialený server MCP | Pridajte server, zistite jeho nástroje a priraďte ho agentovi | --- ## Schéma nástroja Každý nástroj má nasledujúcu štruktúru: ```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 } ``` ### Konfigurácia nástroja | Pole | Typ | Povinné | Popis | |-------|------|----------|-------------| | `timeout` | číslo | Nie | Maximálny čas vykonávania v sekundách (predvolené: `20`, maximum: `180`) | ### Definícia funkcie | Pole | Typ | Povinné | Popis | |-------|------|----------|-------------| | `name` | reťazec | Áno | Jedinečný identifikátor nástroja | | `description` | reťazec | Áno | Vysvetľuje AI, kedy má tento nástroj použiť | | `parameters` | objekt | Áno | Schéma JSON pre argumenty nástroja | ### Konfigurácia endpointu | Pole | Typ | Povinné | Popis | |-------|------|----------|-------------| | `url` | reťazec | Áno | URL endpointu vášho API | | `method` | reťazec | Nie | Metóda HTTP (predvolené: `POST`) | | `headers` | objekt | Nie | Vlastné hlavičky, ktoré sa majú zahrnúť | Konfigurácia `endpoint` sa **neodosiela** modelu AI — ThunderPhone ju používa iba na vykonanie volania nástroja. --- ## Dva spôsoby volania Požiadavka, ktorú váš server prijme, závisí od toho, či nástroj obsahuje `endpoint`: | | Nástroj **s** `endpoint` | Nástroj **bez** `endpoint` | |---|---|---| | Kam smeruje požiadavka | Priamo na `endpoint.url` | Na [staršiu URL webhooku](/api-reference/organizations#legacy-single-url-webhook) vašej organizácie | | Telo | **Samotné argumenty nástroja** | Obálka `telephony.tool` / `web.tool` | | Hlavičky | Vaše `endpoint.headers` + `X-ThunderPhone-Call-ID` + `X-ThunderPhone-Signature` | `Content-Type` + `X-ThunderPhone-Signature` | | Podpisovací kľúč | Tajný kľúč webhooku organizácie | Tajný kľúč webhooku organizácie | Oba spôsoby sú **blokujúce** — AI uprostred vety čaká na výsledok. Predvolený časový limit je **20 s**; nastavením `timeout` na najvyššej úrovni nástroja povolíte dlhšie vykonávanie, až do maxima platformy **180 s**. Handlery udržiavajte rýchle. Kombinácia je možná: pri hovore, ktorého organizácia má URL webhooku, sa nástroje s `endpoint` volajú priamo a ostatné sa vrátia k webhooku. ## Priame volania koncových bodov Keď AI vyvolá nástroj, ktorý má `endpoint`, ThunderPhone odošle požiadavku na vašu URL adresu: ### Hlavičky požiadavky ```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 ``` Vlastné hlavičky z vášho `endpoint.headers` sú vždy zahrnuté doslovne spolu s dvoma hlavičkami v mennom priestore ThunderPhone: - `X-ThunderPhone-Signature` — HMAC-SHA256 z presných bajtov tela požiadavky s kľúčom **tajomstvo webhooku vašej organizácie** - `X-ThunderPhone-Call-ID` — ID aktuálneho hovoru `Content-Type: application/json` sa nastaví, pokiaľ ho váš `endpoint.headers` neprepíše — vlastný `Content-Type` má prednosť. Podpis používa ako kľúč tajomstvo webhooku na úrovni organizácie z [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook). Ak vaša organizácia nikdy nenakonfigurovala starší webhook, nemá žiadne tajomstvo a volania nástrojov obsahujú **iba** `X-ThunderPhone-Call-ID` — obslužná rutina, ktorá zlyhá pri chýbajúcom podpise, by ich odmietla. Buď nakonfigurujte starší webhook, aby ste získali tajomstvo, alebo vložte vlastné zdieľané tajomstvo do `endpoint.headers`. ### Telo požiadavky Pre `POST` / `PUT` / `PATCH` telo obsahuje **iba** argumenty nástroja (bez obálky), kanonicky serializované (zoradené kľúče, kompaktné oddeľovače): ```json {"date":"2025-01-02","service":"consultation"} ``` Pre `GET` / `DELETE` sa argumenty odosielajú ako **parametre dopytu** a telo je prázdne — podpis sa potom vypočíta nad prázdnym reťazcom bajtov. Pozrite si [Overenie podpisov webhookov](/sk/guides/verify-webhook-signatures). ### Odpoveď Vráťte odpoveď JSON s výsledkom nástroja: ```json { "available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"], "timezone": "America/Los_Angeles" } ``` Odpoveď sa naformátuje a poskytne AI, aby mohla pokračovať v konverzácii. Odpovede iné než JSON sa zabalia ako `{"data": ""}`; časové limity a zlyhania pripojenia sa AI nahlásia ako chyby, takže sa agent môže ospravedlniť a pokračovať namiesto zaseknutia. ## Odosielanie v režime webhooku Nástroje **bez** `endpoint` sa odosielajú na staršiu webhookovú URL vašej organizácie ako podpísaná požiadavka `telephony.tool` (telefonické hovory) alebo `web.tool` (webové volania). Na rozdiel od [notifikácií auditu](/sk/webhooks/events), ktoré sa doručujú na koncové body webhookov po vykonaní, táto požiadavka **je** samotným vykonaním — vaša odpoveď HTTP je výsledkom nástroja. ```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` obsahuje `origin_domain` namiesto `from_number` / `to_number`. Odpovedzte výsledkom nástroja vo formáte JSON — platí rovnaký kontrakt odpovede ako pri priamych volaniach koncových bodov. Požiadavka je podpísaná tajomstvom webhooku organizácie nad nespracovaným telom, rovnako ako každý iný webhook. Odoberané [koncové body webhookov](/sk/webhooks/endpoints) navyše prijímajú neblokujúce `telephony.tool` / `web.tool` **oznámenie po** vykonaní každého nástroja (bez ohľadu na cestu, ktorá ho spustila), vrátane odpovede nástroja — užitočné pre auditné stopy. Pozrite si [katalóg udalostí](/sk/webhooks/events). --- ## Overenie podpisu Priame volania nástrojov sú podpisované rovnako ako webhooky: - HMAC-SHA256 nad presnými bajtmi tela požiadavky (kanonický JSON — zoradené kľúče, bez nadbytočných medzier) - S použitím tajného kľúča webhooku vašej organizácie - Nástroje `GET` / `DELETE` podpisujú prázdny bajtový reťazec ```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 }); }); ``` Úplné postupy — vrátane prípadu s prázdnym telom a upozornenia na chýbajúci tajný kľúč — nájdete v časti [Overenie podpisov webhookov](/sk/guides/verify-webhook-signatures). --- ## Príklad: Kompletný proces rezervácie Tu je súbor nástrojov pre kompletný systém rezervácie termínov: ```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" } } } ] } ``` --- ## Osvedčené postupy Pole `description` pomáha AI pochopiť, **kedy** má nástroj použiť. Presne uveďte, čo robí a kedy je vhodné ho použiť. Vrátte chybové správy, ktorým AI rozumie: `{"error": "No slots available for that date"}` namiesto všeobecných chýb 500. Vráťte iba to, čo AI potrebuje na pokračovanie v konverzácii. Veľké dátové payloady spomaľujú časy odpovedí. Polia označte ako `required` iba vtedy, keď je to skutočne potrebné. Pred volaním nástroja AI požiada používateľa o povinné informácie. --- ## Súvisiace Spúšťajte akcie hovorov spravované platformou bez definovania koncového bodu. Nástroje spravované platformou pre HubSpot, Salesforce, Slack, Google Calendar, Google Sheets a Cal.com — bez potreby koncového bodu. Pripojte server MCP a umožnite agentovi volať jeho nástroje. Opakovane použiteľné integrácie REST, ktoré môžete pripojiť k agentom. Jeden pomocný nástroj na overenie webhookov a volaní nástrojov.