--- title: "Sukurkite įrankio integraciją (API)" description: "Leiskite savo agentui pokalbio metu kviesti jūsų API — ieškoti duomenų bazėje, sukurti užklausą, rasti užsakymą." --- **Įrankio integracija** yra pakartotinai naudojamas HTTP galinis punktas, kurį agentas gali iškviesti pokalbio metu. ThunderPhone pateikiate įrankio JSON schemos aprašą ir galinio punkto URL; agentas pagal pokalbį nusprendžia, kada jį iškviesti, o ThunderPhone iš savo serverių siunčia išeinančią HTTP užklausą ir grąžina atsakymą agentui. Valdymo skydelyje galima atlikti daugumą su įrankiais susijusių veiksmų nenaudojant šios API: **Ryšiai → Programos** keliais OAuth paspaudimais prijungia Slack, HubSpot, Salesforce, Google Calendar, Google Sheets ir Cal.com; **Ryšiai → API** paverčia bet kurią HTTP API agento veiksmu (įklijuokite cURL komandą, o DI vedlys parengs įrankio juodraštį su integruota funkcija „Išbandyti užklausą“); o **Ryšiai → MCP** prideda MCP serverius. Žr. [Ryšiai](/lt/guides/concepts). Šis vadovas skirtas bazinei API, kuria grindžiama API sąsaja. Šiame vadove nuo pradžios iki pabaigos aprašoma, kaip sukurti orų paieškos įrankį. ## Įrankio sandara Dvi dalys: 1. **Schema** — OpenAI tipo funkcijos apibrėžimas (`{type: "function", function: {name, description, parameters}}`), kuris nurodo LLM, ką įrankis daro ir kokius argumentus jis priima. 2. **Galinis punktas** — URL, kurį ThunderPhone serveriai iškviečia, kai LLM nusprendžia naudoti įrankį. Užklausa yra JSON POST užklausa, kurios turinyje pateikiami LLM pasirinkti argumentai. ## 1. Pasirinkite redaktorių Atidarykite **Ryšiai → API**, sukurkite arba redaguokite API ryšį, perjunkite parametrų redaktorių į **JSON** ir ten pridėkite formatą. Sukurkite specifikaciją naudodami `POST /v1/integrations` arba atnaujinkite ją naudodami `PATCH /v1/integrations/{id}`. Abiem būdais sukuriama išsaugota integracija. Išsaugoję susiekite tą integraciją su agentu. Agentų API neturi redaguojamo įterptinio `tools` lauko. Šiame vadove naudojamas integracijų API būdas. ## 2. Sukurkite integraciją ```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" } ] }' ``` Išsaugokite grąžintą `id` (UUID). Skirkite pakankamai dėmesio įrankio ir kiekvieno parametro `description`. LLM vykdymo metu naudoja šias eilutes, kad nuspręstų, ar ir kaip iškviesti įrankį. Neaiškūs aprašymai → neaiškūs įrankio iškvietimai. ### Adreso parametruose nurodykite `format: "email"` Parametras, gaunantis el. pašto adresą, savo schemoje turėtų tai nurodyti: ```json "email": { "type": "string", "format": "email", "description": "The caller's email address" } ``` `format` yra daugiau nei užuomina. Išspręstos el. pašto schemos atveju, prieš iškviečiant jūsų galinį tašką, ThunderPhone pašalina reikšmės kraštinius tarpus, domeną pakeičia mažosiomis raidėmis, pavienius angliškus žodžius `at`, `dot`, `underscore`, `dash` ir `hyphen` pakeičia atitinkamais simboliais bei pašalina tarpus tiesiogiai šalia `@`, `.`, `_` ir `-`. Šie žodžiai turi tą pačią reikšmę, nepaisant to, ar nuoraše jau yra pažodinis `@`: `"john dot smith at gmail dot com"` tampa `john.smith@gmail.com`. Bet kokie kiti vidiniai tarpai atmetami, užuot tyliai sujungiami. Ištarti skyriklių žodžiai palaikomi tik anglų kalba; neangliškos arba neatpažintos formos su tarpais yra saugiai atmetamos. Priimami galiojantys internacionalizuoti domenai ir SMTPUTF8 vietinės dalys. Punycode įvestis po analizatoriaus normalizavimo lieka punycode, o Unicode domeno įvestis lieka Unicode, todėl jūsų API gauna skambintojo pateiktą įprastą atvaizdavimą. Jei galutinė reikšmė netinkama, įrankis **neiškviečiamas**. Agentas gauna `invalid_email_argument`, nurodantį jam patvirtinti rašybą su skambintoju ir iš naujo išsiųsti pažodinį adresą. Praleistas pasirenkamas el. pašto adresas neliečiamas. `null`, tuščia eilutė arba eilutė, sudaryta tik iš tarpų, taip pat neliečiama, kai savybė yra pasirenkama arba leidžianti null reikšmę; tos pačios reikšmės atmetamos, kai el. pašto adresas yra privalomas ir neleidžiantis null reikšmės. Tikrinamos vietinės schemos nuorodos, pvz., `#/$defs/email` ir `#/definitions/email`, taip pat `anyOf`, `oneOf` ir `allOf`, taikant ciklų ir gylio ribas. Nevietinis arba neišsprendžiamas `$ref` yra žinomas tikrinimo apribojimas ir perduodamas nepakitęs, kaip ir iškvietimas, kurio įrankio momentinė kopija neturi tinkamos schemos. Kai reikia taikyti patikrą, el. pašto schemas laikykite vietines. Parametrai be priverstinai taikomo el. pašto formato perduodami tiksliai taip, kaip juos sukūrė modelis. Palaikomi formatai: `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `ipv4`, `ipv6` ir `uuid`; šiuo metu normalizuojamas ir tikrinamas tik `email`. ## 3. Išbandykite galinį tašką smėlio dėžėje Prieš susiedami integraciją su agentu, išsiųskite pasirašytą užklausą iš ThunderPhone serverių, kad patvirtintumėte ryšį: ```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, ...}" } ``` Šis testas taip pat sustiprina ThunderPhone SSRF apsaugą — užklausos į localhost arba privačius IP diapazonus grąžina `400 code=url_not_allowed`. ## 4. Susiekite integraciją su agentu Pridėkite naudodami `integration_ids`, kai kuriate arba atnaujinate agentą: ```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-..."] }' ``` Su vienu agentu galite susieti daug integracijų. Agento raginime galima nurodyti jas pagal pavadinimą — „naudokite `get_weather`, kai skambinantysis klausia apie oro sąlygas“ — arba agentas gali jas numanomai aptikti pagal schemos aprašus. ## 5. Įgyvendinkite galinį tašką Kai agentas iškviečia įrankį, ThunderPhone siunčia pasirašytą POST užklausą į jūsų `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"} ``` Jūsų serveris atsako JSON duomenimis, kurie perduodami atgal LLM: ```json {"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8} ``` LLM apdoroja šį atsakymą ir balsu pateikia skambinančiajam žmonėms suprantamą santrauką. Parašas apskaičiuojamas pagal neapdorotą užklausos turinį, naudojant tą patį `secret` kaip ir jūsų žiniatinklio kablio galiniame taške. **Patikrinkite jį** — įrankių galiniai taškai yra pasiekiami iš interneto ir jiems kyla tokia pati klastojimo rizika kaip žiniatinklio kabliams. Žr. [Žiniatinklio kablių parašų tikrinimas](/lt/guides/verify-webhook-signatures). ## 6. Išbandykite ciklą Paleiskite [mikrofono sesiją](/api-reference/mic-sessions) su agentu ir užduokite klausimą, kurį apdoroja jūsų įrankis („Koks oras 94110?“). Skambučio transkripte rodoma visa užklausos ir atsakymo eiga: ```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." } ] } ``` Tai galite gauti naudodami [`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript); neapdorotas įvykių srautas (su kiekvieno įrašo laiko žymomis ir garso poslinkiais) pateikiamas adresu [`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history). ## Dažnos klaidos LLM sprendžia pagal įrankio aprašą. Jei skambinančiojo klausimas neatitinka aprašo, modelis įrankio neiškvies. Patikslinkite aprašą (pridėkite dažnus sinonimus ir formuluotes) arba aiškiai paminėkite jį agento raginime („Kai skambinantysis klausia apie orą, naudokite `get_weather`.“). Atsakymai, didesni nei 6 kB, transkripto peržiūroje sutrumpinami. Grąžinkite tik LLM reikalingus laukus — ne visą įrašą. Įrankių galiniams taškams pagal numatytuosius nustatymus taikomas 10 sekundžių laiko limitas. Jei reikia daugiau laiko, apdorokite asinchroniškai: grąžinkite `{"status": "pending", "request_id": "..."}` ir pateikite rezultatą per atskirą įrankio iškvietimą. Kiekvienas integracijos `PATCH` sukuria naują peržiūrą. Peržiūrėkite [`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history), kad pamatytumėte, kas ką pakeitė. Jei sugadinate įrankio schemą, galite rankiniu būdu grąžinti ankstesnę būseną, naudodami PATCH ir atkurdami senesnę momentinę kopiją. --- ## Tolesni veiksmai CRUD, perkėlimas, versijų istorija. Visa JSON schemos gramatika ir pasirašyto galinio taško sutartis. Taikykite žiniatinklio kablio parašo šabloną įrankių galiniams taškams. Peržiūrėkite visą įrankio iškvietimo eigą nuo pradžios iki pabaigos.