--- title: "Izveidojiet rīka integrāciju (API)" description: "Ļaujiet savam balss aģentam sarunas laikā izsaukt jūsu API — meklēt datubāzē, izveidot pieteikumu, atrast pasūtījumu." --- Rīku integrācija ir atkārtoti izmantojams HTTP galapunkts, ko balss aģents var izsaukt zvana laikā. Jūs sniedzat ThunderPhone rīka JSON shēmas aprakstu un galapunkta URL; balss aģents, balstoties uz sarunu, nosaka, kad to izsaukt, un ThunderPhone no saviem serveriem nosūta izejošo HTTP pieprasījumu un atgriež atbildi balss aģentam. Vairumu rīku vajadzību var nodrošināt vadības panelī bez šīs API: **Savienojumi → Lietotnes** ar dažiem OAuth klikšķiem savieno Slack, HubSpot, Salesforce, Google Calendar, Google Sheets un Cal.com; **Savienojumi → API** pārvērš jebkuru HTTP API par balss aģenta darbību (ielīmējiet cURL komandu, un AI vednis izveidos rīka melnrakstu ar iebūvētu **Pārbaudīt pieprasījumu**); un **Savienojumi → MCP** pievieno MCP serverus. Skatiet [Savienojumi](/lv/guides/concepts). Šajā rokasgrāmatā aprakstīta pamata API zem API saskarnes. Šajā rokasgrāmatā soli pa solim izveidosiet laikapstākļu pārbaudes rīku. ## Rīka uzbūve Divas daļas: 1. **Shēma** — OpenAI tipa funkcijas definīcija (`{type: "function", function: {name, description, parameters}}`), kas LLM norāda, ko rīks dara un kādus argumentus tas pieņem. 2. **Galapunkts** — URL, ko ThunderPhone serveri izsauc, kad LLM nolemj izmantot rīku. Pieprasījums ir JSON POST ar LLM izvēlētajiem argumentiem pamattekstā. ## 1. Izvēlieties redaktoru Atveriet **Savienojumi → API**, izveidojiet vai rediģējiet API savienojumu, pārslēdziet parametru redaktoru uz **JSON** un pievienojiet tur formātu. Izveidojiet specifikāciju ar `POST /v1/integrations` vai atjauniniet to ar `PATCH /v1/integrations/{id}`. Abos veidos tiek izveidota saglabāta integrācija. Pēc saglabāšanas pievienojiet šo integrāciju balss aģentam. Aģentu API nav rakstāma iekļauta `tools` lauka. Šajā rokasgrāmatā izmantots integrāciju API ceļš. ## 2. Izveidojiet integrāciju ```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" } ] }' ``` Saglabājiet atgriezto `id` (UUID). Galveņu vērtības ir tikai rakstīšanai: atbildēs tiek uzskaitīti tikai galveņu nosaukumi, un vēlākā `PATCH` pieprasījumā var nosūtīt galveni bez `value`, lai saglabātu esošo vērtību. Pievērsiet īpašu uzmanību rīka un katra parametra `description`. LLM izpildlaikā izmanto šīs virknes, lai noteiktu, vai un kā izsaukt rīku. Neskaidri apraksti → neskaidri rīka izsaukumi. ### Adreses parametriem deklarējiet `format: "email"` Parametram, kas saņem e-pasta adresi, tas jānorāda tā shēmā: ```json "email": { "type": "string", "format": "email", "description": "The caller's email address" } ``` `format` ir vairāk nekā tikai norāde. Atrisinātai e-pasta shēmai pirms jūsu galapunkta izsaukšanas ThunderPhone apgriež vērtību, domēnu pārveido par mazajiem burtiem, atsevišķos angļu vārdus `at`, `dot`, `underscore`, `dash` un `hyphen` pārvērš attiecīgajās rakstzīmēs, kā arī noņem atstarpes tieši ap `@`, `.`, `_` un `-`. Vārdiem ir tāda pati nozīme neatkarīgi no tā, vai transkripts jau satur burtisku `@`: `"john dot smith at gmail dot com"` kļūst par `john.smith@gmail.com`. Jebkuras citas iekšējās atstarpes tiek noraidītas, nevis klusi savienotas. Izrunātie atdalītāju vārdi ir pieejami tikai angļu valodā; citu valodu vai neatpazītas formas ar atstarpēm tiek droši noraidītas. Tiek pieņemti derīgi internacionalizēti domēni un SMTPUTF8 lokālās daļas. Punycode ievade pēc parsētāja normalizācijas paliek punycode, un Unicode domēna ievade paliek Unicode, tādēļ jūsu API saņem zvanītāja norādīto ierasto attēlojumu. Ja galīgā vērtība nav derīga, rīks **netiek izsaukts**. Balss aģents saņem `invalid_email_argument`, kas tam norāda apstiprināt pareizrakstību ar zvanītāju un atkārtoti nosūtīt burtisko adresi. Izlaista neobligāta e-pasta adrese netiek mainīta. `null`, tukša virkne vai virkne, kurā ir tikai atstarpes, arī netiek mainīta, ja rekvizīts ir neobligāts vai pieļauj null vērtību; tās pašas vērtības tiek noraidītas obligātai e-pasta adresei, kas nepieļauj null vērtību. Lokālās shēmu atsauces, piemēram, `#/$defs/email` un `#/definitions/email`, kā arī `anyOf`, `oneOf` un `allOf`, tiek pārbaudītas ar ciklu un dziļuma ierobežojumiem. Nelokāla vai neatrisināma `$ref` ir zināms izpildes ierobežojums un tiek nodota tālāk bez izmaiņām, tāpat kā izsaukums, kura rīka momentuzņēmumam nav izmantojamas shēmas. Ja vēlaties, lai tiktu piemērota pārbaude, saglabājiet e-pasta shēmas lokālas. Parametri bez izpildāma e-pasta formāta tiek nodoti tālāk tieši tā, kā tos izveidoja modelis. Atbalstītie formāti ir `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `ipv4`, `ipv6` un `uuid`; pašlaik tiek normalizēts un pārbaudīts tikai `email`. ## 3. Testējiet galapunktu smilškastē Pirms saistāt integrāciju ar balss aģentu, nosūtiet parakstītu pieprasījumu no ThunderPhone serveriem, lai apstiprinātu savienojamību: ```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 tests arī nostiprina ThunderPhone SSRF aizsardzību — pieprasījumi uz localhost vai privātiem IP diapazoniem atgriež `400 code=url_not_allowed`. ## 4. Saistiet integrāciju ar aģentu Pievienojiet, izmantojot `integration_ids`, kad veidojat vai atjaunināt aģentu: ```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-..."] }' ``` Vienam aģentam varat saistīt vairākas integrācijas. Aģenta uzvednē var uz tām atsaukties pēc nosaukuma — "izmantojiet `get_weather`, kad zvanītājs jautā par laikapstākļiem" — vai arī aģents tās var netieši atpazīt pēc shēmas aprakstiem. ## 5. Ieviesiet galapunktu Kad aģents izsauc rīku, ThunderPhone nosūta parakstītu POST pieprasījumu uz jūsu `endpoint_url`: ``` POST /weather HTTP/1.1 Host: api.example.com X-Api-Key: your-provider-key X-ThunderPhone-Signature-V2: t=,v1= X-ThunderPhone-Signature: X-ThunderPhone-Call-ID: 987654321 Content-Type: application/json {"zip": "94110"} ``` Jūsu serveris atbild ar JSON, kas tiek nodots atpakaļ LLM: ```json {"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8} ``` LLM apstrādā šo atbildi un sniedz zvanītājam saprotamu kopsavilkumu. Paraksts tiek aprēķināts no neapstrādātā pieprasījuma pamatteksta, izmantojot to pašu `secret`, ko jūsu tīmekļa aizķeres galapunkts. **Pārbaudiet to** — rīku galapunkti ir pieejami internetā un pakļauti tiem pašiem viltošanas riskiem kā tīmekļa aizķeres. Skatiet [Tīmekļa aizķeru parakstu pārbaude](/lv/guides/verify-webhook-signatures). ## 6. Pārbaudiet ciklu Palaidiet [mikrofona sesiju](/api-reference/mic-sessions) ar aģentu un uzdodiet jautājumu, ko apstrādā jūsu rīks ("Kādi ir laikapstākļi 94110?"). Zvanu atšifrējumā redzams pilns pieprasījuma un atbildes cikls: ```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." } ] } ``` To varat iegūt, izmantojot [`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript); neapstrādātā notikumu plūsma (ar katra ieraksta laika informāciju un audio nobīdēm) ir pieejama vietnē [`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history). Zvanu sarakstu un analītikas sadaļās ThunderPhone tagad testa zvanus uzrāda atsevišķi no reālās datplūsmas. Browser Talk testi un simulācijas var atkārtoti izmantot īstu tālruņa numuru un var izskatīties kā ienākošie zvani, taču tie netiek ieskaitīti produkcijas zvanu kopsummās, vērtējumos vai problēmu rādītājos. ## Biežākās kļūdas LLM pieņem lēmumu, pamatojoties uz rīka aprakstu. Ja zvanītāja jautājums neatbilst aprakstam, modelis rīku neizsauks. Precizējiet aprakstu (pievienojiet bieži lietotus sinonīmus un formulējumus) vai skaidri norādiet to aģenta uzvednē ("Kad zvanītājs jautā par laikapstākļiem, izmantojiet `get_weather`."). Atbildes, kas pārsniedz 6 kB, atšifrējuma priekšskatījumā tiek saīsinātas. Atgrieziet tikai LLM nepieciešamos laukus — ne visu ierakstu. Rīku galapunktiem noklusējuma noildze ir 10 sekundes. Ja nepieciešams ilgāks laiks, apstrādājiet to asinhroni: atgrieziet `{"status": "pending", "request_id": "..."}` un parādiet rezultātu, izmantojot atsevišķu rīka izsaukumu. Katrs integrācijas `PATCH` izveido jaunu pārskatījumu. Pārbaudiet [`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history), lai redzētu, kurš ko mainīja. Ja sabojājat rīka shēmu, varat manuāli atgriezt iepriekšējo versiju, ar PATCH atjaunojot vecāku momentuzņēmumu. --- ## Nākamās darbības CRUD, pārsūtīšana, versiju vēsture. Pilna JSON shēmas gramatika un parakstītā galapunkta līgums. Lietojiet tīmekļa aizķeres paraksta modeli rīku galapunktiem. Pārbaudiet pilnu rīka izsaukuma ciklu.