--- title: "Vytvorte integráciu nástroja (API)" description: "Umožnite svojmu agentovi volať vaše API počas konverzácie — vyhľadávať v databáze, vytvárať tikety, vyhľadávať objednávky." --- **Integrácia nástroja** je opakovane použiteľný koncový bod HTTP, ktorý môže hlasový agent vyvolať počas hovoru. ThunderPhone poskytnete opis nástroja v schéme JSON spolu s adresou URL koncového bodu; hlasový agent rozhodne, kedy ho vyvolať, na základe konverzácie a ThunderPhone odošle odchádzajúcu požiadavku HTTP zo svojich serverov a vráti odpoveď hlasovému agentovi. Panel pokrýva väčšinu potrieb nástrojov bez tohto rozhrania API: **Prepojenia → Aplikácie** pripojí Slack, HubSpot, Salesforce, Google Calendar, Google Sheets a Cal.com niekoľkými kliknutiami OAuth; **Prepojenia → Rozhrania API** zmení ľubovoľné rozhranie HTTP API na akciu hlasového agenta (vložíte príkaz cURL a sprievodca AI pripraví návrh nástroja so vstavanou funkciou **Testovať požiadavku**); a **Prepojenia → MCP** pridá servery MCP. Pozrite si [Prepojenia](/sk/guides/concepts). Táto príručka sa venuje základnému rozhraniu API pod rozhraním API. Táto príručka vás prevedie vytvorením nástroja na vyhľadávanie počasia od začiatku do konca. ## Štruktúra nástroja Dve časti: 1. **Schéma** — definícia funkcie v štýle OpenAI (`{type: "function", function: {name, description, parameters}}`), ktorá modelu LLM vysvetľuje, čo nástroj robí a aké argumenty prijíma. 2. **Koncový bod** — adresa URL, ktorú servery ThunderPhone volajú, keď sa model LLM rozhodne nástroj použiť. Požiadavka je JSON POST s argumentmi vybranými modelom LLM v tele požiadavky. ## 1. Vyberte editor Otvorte **Prepojenia → Rozhrania API**, vytvorte alebo upravte pripojenie API, prepnite editor parametrov na **JSON** a pridajte tam formát. Vytvorte špecifikáciu pomocou `POST /v1/integrations` alebo ju aktualizujte pomocou `PATCH /v1/integrations/{id}`. Obe cesty vytvoria uloženú integráciu. Po uložení túto integráciu pripojte k hlasovému agentovi. API agentov nemá zapisovateľné vložené pole `tools`. Táto príručka používa cestu API integrácií. ## 2. Vytvorte integráciu ```bash curl -X POST https://api.thunderphone.com/v1/integrations \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "display_name": "Weather API", "spec": { "type": "function", "function": { "name": "get_weather", "description": "Return the current weather for a zip code.", "parameters": { "type": "object", "properties": { "zip": { "type": "string", "description": "5-digit US ZIP code" } }, "required": ["zip"] } } }, "endpoint_url": "https://api.example.com/weather", "endpoint_method": "GET", "headers": [ { "key": "X-Api-Key", "value": "your-provider-key" } ] }' ``` Uložte vrátené `id` (UUID). Venujte skutočné úsilie `description` nástroja a každého parametra. LLM tieto reťazce používa za behu na rozhodnutie, či a ako nástroj zavolať. Nejasné popisy → nejasné volania nástroja. ### Pri parametroch adresy deklarujte `format: "email"` Parameter, ktorý prijíma e-mailovú adresu, to musí uvádzať vo svojej schéme: ```json "email": { "type": "string", "format": "email", "description": "The caller's email address" } ``` `format` je viac než len nápoveda. Pri vyhodnotenej e-mailovej schéme ThunderPhone pred zavolaním vášho endpointu odstráni medzery na okrajoch hodnoty, prevedie doménu na malé písmená, samostatné anglické slová `at`, `dot`, `underscore`, `dash` a `hyphen` nahradí ich znakmi a odstráni medzery priamo okolo `@`, `.`, `_` a `-`. Tieto slová majú rovnaký význam bez ohľadu na to, či prepis už obsahuje doslovné `@`: `"john dot smith at gmail dot com"` sa zmení na `john.smith@gmail.com`. Akékoľvek iné vnútorné medzery sa zamietnu namiesto toho, aby sa potichu spojili. Vyslovené slová oddeľovačov sú podporované iba v angličtine; neanglické alebo nerozpoznané formy s medzerami sa bezpečne zamietnu. Platné internacionalizované domény a lokálne časti SMTPUTF8 sú prijaté. Vstup v punycode zostáva po normalizácii parserom v punycode a vstup domény v Unicode zostáva v Unicode, takže vaše API dostane bežné zastúpenie poskytnuté volajúcim. Ak je výsledná hodnota neplatná, nástroj sa **nezavolá**. Agent dostane `invalid_email_argument`, ktoré mu oznámi, aby s volajúcim potvrdil pravopis a znovu odoslal doslovnú adresu. Vynechaný voliteľný e-mail zostane nezmenený. `null`, prázdny reťazec alebo reťazec obsahujúci iba medzery tiež zostanú nezmenené, keď je vlastnosť voliteľná alebo povoľuje hodnotu null; rovnaké hodnoty sa zamietnu pri povinnom e-maile, ktorý nepovoľuje null. Lokálne odkazy na schému, napríklad `#/$defs/email` a `#/definitions/email`, spolu s `anyOf`, `oneOf` a `allOf`, sa kontrolujú s limitmi cyklov a hĺbky. Nelokálny alebo nevyriešiteľný `$ref` je známy limit vynucovania a prechádza bez zmeny, rovnako ako volanie, ktorého snímka nástroja nemá použiteľnú schému. Keď potrebujete uplatniť túto kontrolu, ponechajte e-mailové schémy lokálne. Parametre bez vynucovaného formátu e-mailu prechádzajú presne tak, ako ich vytvoril model. Podporované formáty sú `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `ipv4`, `ipv6` a `uuid`; v súčasnosti sa normalizuje a vynucuje iba `email`. ## 3. Otestujte endpoint v sandboxe Pred prepojením integrácie s agentom odošlite podpísanú požiadavku zo serverov ThunderPhone na potvrdenie konektivity: ```bash curl -X POST https://api.thunderphone.com/v1/integrations/test-request \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://api.example.com/weather?zip=94110", "method": "GET", "headers": { "X-Api-Key": "your-provider-key" } }' ``` ```json Response { "ok": true, "status": 200, "elapsed_ms": 187, "response_headers": { "content-type": "application/json" }, "response_preview": "{\"temperature_f\": 64, ...}" } ``` Tento test tiež posilňuje ochrany ThunderPhone proti SSRF — požiadavky na localhost alebo súkromné rozsahy IP vrátia `400 code=url_not_allowed`. ## 4. Prepojte integráciu s agentom Pri vytváraní alebo aktualizácii hlasového agenta ju pripojte pomocou `integration_ids`: ```bash curl -X PATCH https://api.thunderphone.com/v1/agents/12 \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "integration_ids": ["f9b5a1a4-..."] }' ``` K jednému hlasovému agentovi môžete prepojiť viac integrácií. Výzva agenta na ne môže odkazovať podľa názvu — „použi `get_weather`, keď volajúci žiada informácie o počasí“ — alebo ich môže implicitne rozpoznať z popisov schémy. ## 5. Implementujte koncový bod Keď agent vyvolá nástroj, ThunderPhone odošle podpísanú požiadavku POST na váš `endpoint_url`: ``` POST /weather HTTP/1.1 Host: api.example.com X-Api-Key: your-provider-key X-ThunderPhone-Signature: X-ThunderPhone-Call-ID: 987654321 Content-Type: application/json {"zip": "94110"} ``` Váš server odpovie JSON-om, ktorý sa odovzdá späť LLM: ```json {"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8} ``` LLM túto odpoveď spracuje a volajúcemu ju zhrnie prirodzenou rečou. Podpis sa vypočítava z nespracovaného tela požiadavky pomocou rovnakého `secret` ako váš webhookový koncový bod. **Overte ho** — koncové body nástrojov sú dostupné z internetu a podliehajú rovnakým rizikám falšovania ako webhooky. Pozrite si [Overenie podpisov webhookov](/sk/guides/verify-webhook-signatures). ## 6. Otestujte celý cyklus Spustite [reláciu mikrofónu](/api-reference/mic-sessions) s agentom a položte otázku, ktorú váš nástroj spracúva („Aké je počasie v 94110?“). Prepis hovoru zobrazuje celý priebeh: ```json { "call_id": 987654321, "transcripts": [ { "role": "user", "content": "What's the weather in 94110?" }, { "role": "tool_call", "content": "{\"tool_call\": \"get_weather\", \"arguments\": {\"zip\": \"94110\"}}" }, { "role": "tool_response", "content": "{\"tool_name\": \"get_weather\", \"response\": {\"temperature_f\": 64, \"condition\": \"Partly cloudy\"}}" }, { "role": "agent", "content": "It's 64 degrees and partly cloudy." } ] } ``` Môžete ho načítať cez [`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript); tok nespracovaných udalostí (s časovaním jednotlivých záznamov a posunmi zvuku) nájdete na [`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history). ## Bežné problémy LLM rozhoduje na základe popisu nástroja. Ak otázka volajúceho nezodpovedá popisu, model nástroj nevyvolá. Spresnite popis (pridajte bežné synonymá a formulácie) alebo ho výslovne uveďte vo výzve agenta („Keď volajúci žiada informácie o počasí, použi `get_weather`.“). Odpovede väčšie ako 6 kB sa v náhľade prepisu skrátia. Vráťte iba polia, ktoré LLM potrebuje — nie celý váš záznam. Koncové body nástrojov majú predvolený časový limit 10 sekúnd. Ak potrebujete dlhší, spracujte požiadavku asynchrónne: vráťte `{"status": "pending", "request_id": "..."}` a výsledok zobrazte prostredníctvom samostatného volania nástroja. Každý `PATCH` integrácie vytvorí novú revíziu. Skontrolujte [`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history), aby ste zistili, kto čo zmenil. Ak poškodíte schému nástroja, môžete ju manuálne vrátiť späť opätovným PATCH-ovaním staršej snímky. --- ## Ďalšie kroky CRUD, prenos, história verzií. Úplná gramatika schémy JSON a kontrakt podpísaného koncového bodu. Použite vzor podpisu webhooku na koncové body nástrojov. Preskúmajte celý cyklus volania nástroja.