--- title: "Loo tööriistaintegratsioon (API)" description: "Lase oma agendil vestluse ajal oma API-sid kutsuda — otsida andmebaasist, luua pilet, otsida tellimust." --- **Tööriistaintegratsioon** on korduskasutatav HTTP-lõpp-punkt, mida agent saab kõne ajal kasutada. Annad ThunderPhone'ile tööriista JSON-skeemi kirjelduse ja lõpp-punkti URL-i; agent otsustab vestluse põhjal, millal seda kasutada, ning ThunderPhone teeb oma serveritest väljuva HTTP-päringu ja tagastab vastuse agendile. Armatuurlaud katab enamiku tööriistavajadusi ilma selle API-ta: **Ühendused → Rakendused** ühendab mõne OAuth-klõpsuga Slacki, HubSpoti, Salesforce'i, Google Calendari, Google Sheetsi ja Cal.comi; **Ühendused → API-d** muudab mis tahes HTTP API agendi toiminguks (kleebi cURL-käsk ja AI-viisard koostab tööriista mustandi koos sisseehitatud päringu testimisega); ning **Ühendused → MCP** lisab MCP-servereid. Vaata [Ühendused](/et/guides/concepts). See juhend käsitleb API-de vaate aluseks olevat madaltaseme API-t. See juhend näitab ilmaandmete päringu tööriista loomist algusest lõpuni. ## Tööriista ülesehitus Kaks osa: 1. **Skeem** — OpenAI-stiilis funktsiooni definitsioon (`{type: "function", function: {name, description, parameters}}`), mis kirjeldab LLM-ile, mida tööriist teeb ja milliseid argumente see kasutab. 2. **Lõpp-punkt** — URL, mida ThunderPhone'i serverid kutsuvad, kui LLM otsustab tööriista kasutada. Päring on JSON POST, mille sisuks on LLM-i valitud argumendid. ## 1. Vali redaktor Ava **Ühendused → API-d**, loo või muuda API-ühendust, lülita parameetrite redaktor **JSON**-ile ja lisa sinna vorming. Loo spetsifikatsioon käsuga `POST /v1/integrations` või uuenda seda käsuga `PATCH /v1/integrations/{id}`. Mõlemad viisid loovad salvestatud integratsiooni. Pärast salvestamist lisa see integratsioon agendile. Agentide API-s ei ole kirjutatavat reasisest `tools` välja. See juhend kasutab integratsioonide API varianti. ## 2. Loo integratsioon ```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" } ] }' ``` Salvesta tagastatud `id` (UUID). Pühenda aega tööriista ja iga parameetri `description`-ile. LLM kasutab neid stringe käitusajal, et otsustada, kas ja kuidas tööriista kutsuda. Ebamäärased kirjeldused → ebamäärased tööriistakutsed. ### Määra aadressiparameetritele `format: "email"` Parameeter, mis võtab vastu e-posti aadressi, peab seda oma skeemis märkima: ```json "email": { "type": "string", "format": "email", "description": "The caller's email address" } ``` `format` on rohkem kui vihje. Lahendatud e-posti skeemi korral kärbib ThunderPhone enne sinu lõpp-punkti kutsumist väärtuse, muudab domeeni väiketähtedeks, teisendab eraldiseisvad ingliskeelsed sõnad `at`, `dot`, `underscore`, `dash` ja `hyphen` nende märkideks ning eemaldab tühimärgid otse märkide `@`, `.`, `_` ja `-` ümbert. Sõnadel on sama tähendus olenemata sellest, kas transkript juba sisaldab sõnasõnalist märki `@`: `"john dot smith at gmail dot com"` muutub väärtuseks `john.smith@gmail.com`. Kõik muud sisemised tühimärgid lükatakse tagasi, mitte ei ühendata vaikselt. Öeldud eraldussõnad toimivad ainult inglise keeles; muukeelsed või tuvastamata tühikutega vormid nurjuvad suletult. Kehtivad rahvusvahelised domeenid ja SMTPUTF8 lokaalosad on lubatud. Punycode'i sisend jääb punycode'iks ning Unicode'i domeenisisend jääb pärast parseri normaliseerimist Unicode'iks, seega saab sinu API helistaja esitatud tavapärase esituse. Kui lõppväärtus on vigane, tööriista **ei kutsuta**. Agent saab väärtuse `invalid_email_argument`, mis juhendab teda kinnitama helistajaga õigekirja ja saatma sõnasõnalise aadressi uuesti. Välja jäetud valikulist e-posti aadressi ei muudeta. `null`, tühi string või ainult tühimärkidest koosnev string jäetakse samuti muutmata, kui atribuut on valikuline või nullitav; nõutud, mittenullitava e-posti aadressi puhul lükatakse samad väärtused tagasi. Kohalikke skeemiviiteid, näiteks `#/$defs/email` ja `#/definitions/email`, ning `anyOf`, `oneOf` ja `allOf` kontrollitakse tsükli- ja sügavuspiirangutega. Mittekohalik või lahendamatu `$ref` on teadaolev jõustamispiirang ning see edastatakse muutmata kujul, nagu ka kutse, mille tööriista hetktõmmisel puudub kasutatav skeem. Kui vajad selle kontrolli rakendumist, hoia e-posti skeemid kohalikud. Parameetrid, millel puudub jõustatud e-posti vorming, edastatakse täpselt sellisena, nagu mudel need koostas. Toetatud vormingud on `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `ipv4`, `ipv6` ja `uuid`; praegu normaliseeritakse ja jõustatakse ainult `email`. ## 3. Testi lõpp-punkti liivakastis Enne integratsiooni agendiga ühendamist saada ThunderPhone'i serveritest allkirjastatud päring, et kinnitada ühenduvust: ```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, ...}" } ``` See test tugevdab ka ThunderPhone'i SSRF-kaitseid — localhosti või privaatsete IP-vahemike päringud tagastavad `400 code=url_not_allowed`. ## 4. Seo integratsioon häälagendiga Lisa `integration_ids`, kui lood või uuendad häälagenti: ```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-..."] }' ``` Ühe häälagendiga saab siduda mitu integratsiooni. Häälagendi viip võib neile nime järgi viidata — „kasuta `get_weather`, kui helistaja küsib ilmaolude kohta” — või saab häälagent need skeemikirjelduste põhjal kaudselt tuvastada. ## 5. Rakenda lõpp-punkt Kui häälagent tööriista käivitab, saadab ThunderPhone sinu `endpoint_url`-ile allkirjastatud POST-päringu: ``` 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"} ``` Sinu server vastab JSON-iga, mis edastatakse tagasi LLM-ile: ```json {"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8} ``` LLM töötleb vastust ja ütleb helistajale inimkeelse kokkuvõtte. Allkiri arvutatakse töötlemata päringu sisu põhjal, kasutades sama `secret`-it nagu sinu veebikonksu lõpp-punkt. **Kontrolli seda** — tööriista lõpp-punktid on internetist ligipääsetavad ja neile kehtivad samad võltsimisega seotud ohud nagu veebikonksudele. Vaata [Veebikonksu allkirjade kontrollimine](/et/guides/verify-webhook-signatures). ## 6. Testi tsüklit Käivita häälagendi vastu [mikrofoniseanss](/api-reference/mic-sessions) ja esita küsimus, mida sinu tööriist käsitleb („Milline on ilm sihtnumbriga 94110 piirkonnas?”). Kõne transkriptsioon näitab täielikku edasi-tagasi päringut: ```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." } ] } ``` Selle saad pärida kaudu [`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript); töötlemata sündmuste voog (iga kirje ajastuse ja heli nihetega) asub siin: [`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history). ## Levinud probleemid LLM otsustab tööriista kirjelduse põhjal. Kui helistaja küsimus ei vasta kirjeldusele, ei käivita mudel tööriista. Täpsusta kirjeldust (lisa levinud sünonüüme ja sõnastusi) või maini seda häälagendi viibas selgesõnaliselt („Kui helistaja küsib ilma kohta, kasuta `get_weather`.”). Üle 6 kB vastused kärbitakse transkriptsiooni eelvaates. Tagasta ainult väljad, mida LLM vajab — mitte kogu andmerida. Tööriista lõpp-punktidel on vaikimisi 10-sekundiline ajalõpp. Kui vajad pikemat aega, käsitle seda asünkroonselt: tagasta `{"status": "pending", "request_id": "..."}` ja kuva tulemus eraldi tööriistakutse kaudu. Iga integratsiooni `PATCH` loob uue redaktsiooni. Vaata [`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history), et näha, kes mida muutis. Kui rikud tööriista skeemi, saad käsitsi tagasi pöörduda, PATCH-ides vanema hetkepildi tagasi. --- ## Järgmised sammud CRUD, ülekanne, versiooniajalugu. Täielik JSON-skeemi grammatika ja allkirjastatud lõpp-punkti leping. Rakenda veebikonksu allkirja mustrit tööriistade lõpp-punktidele. Vaata üle tööriistakutse täielik edasi-tagasi voog.