> ## Documentation Index > Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt > Use this file to discover all available pages before exploring further. # Rakenna työkalun integraatio (API) > Anna agenttisi kutsua API-rajapintojasi kesken keskustelun – hae tietoa tietokannasta, luo tukipyyntö tai etsi tilaus. **Työkalintegraatio** on uudelleenkäytettävä HTTP-päätepiste, jonka agentti voi kutsua puhelun aikana. Annat ThunderPhonelle työkalun JSON-skeemakuvauksen sekä päätepisteen URL-osoitteen; agentti päättää keskustelun perusteella, milloin sitä kutsutaan, ja ThunderPhone tekee lähtevän HTTP-pyynnön palvelimiltaan sekä palauttaa vastauksen agentille. Hallintapaneeli kattaa useimmat työkalutarpeet ilman tätä APIa: **Yhteydet → Sovellukset** yhdistää Slackin, HubSpotin, Salesforcen, Google Calendarin, Google Sheetsin ja Cal.comin muutamalla OAuth-klikkauksella; **Yhteydet → APIt** muuttaa minkä tahansa HTTP-APIn agentin toiminnoksi (liitä cURL-komento, niin AI-avustaja luonnostelee työkalun, jossa on sisäänrakennettu Testaa pyyntö -toiminto); ja **Yhteydet → MCP** lisää MCP-palvelimia. Katso [Yhteydet](/fi/guides/concepts). Tämä opas käsittelee API-näkymän taustalla olevaa raakaa APIa. Tässä oppaassa rakennetaan sääntarkistustyökalu alusta loppuun. ## Työkalun rakenne Kaksi osaa: 1. **Skeema** — OpenAI-tyylinen funktiomääritelmä (`{type: "function", function: {name, description, parameters}}`), joka kertoo LLM:lle, mitä työkalu tekee ja mitä argumentteja se ottaa. 2. **Päätepiste** — URL-osoite, jota ThunderPhonen palvelimet kutsuvat, kun LLM päättää käyttää työkalua. Pyyntö on JSON-muotoinen POST-pyyntö, jonka runkona ovat LLM:n valitsemat argumentit. ## 1. Valitse tallennusstrategia Liitä kertakäyttöinen työkalu agentin `tools`-taulukkoon. Yksinkertaista, mutta ei uudelleenkäytettävää. Tallenna työkalu uudelleenkäytettävänä [integraationa](/api-reference/integrations) ja linkitä se useisiin agentteihin. Suositellaan kaikkeen, mitä käytetään useammin kuin kerran. Tässä oppaassa käytetään tallennetun integraation polkua. ## 2. Luo integraatio ```bash theme={null} 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" } ] }' ``` Tallenna palautettu `id` (UUID). Panosta työkalun ja jokaisen parametrin `description`-kuvaukseen. LLM käyttää näitä merkkijonoja ajonaikaisesti päättääkseen, kutsuuko se työkalua ja miten. Epämääräiset kuvaukset → epämääräiset työkalukutsut. ## 3. Testaa päätepiste hiekkalaatikossa Ennen kuin linkität integraation agenttiin, lähetä allekirjoitettu pyyntö ThunderPhonen palvelimilta varmistaaksesi yhteyden: ```bash theme={null} 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 theme={null} { "ok": true, "status": 200, "elapsed_ms": 187, "response_headers": { "content-type": "application/json" }, "response_preview": "{\"temperature_f\": 64, ...}" } ``` Tämä testi myös vahvistaa ThunderPhonen SSRF-suojauksia — localhostiin tai yksityisiin IP-osoitealueisiin kohdistuvat pyynnöt palauttavat `400 code=url_not_allowed`. ## 4. Liitä integraatio agenttiin Liitä `integration_ids`-kentän kautta, kun luot tai päivität agentin: ```bash theme={null} 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-..."] }' ``` Voit liittää useita integraatioita yhteen agenttiin. Agentin kehotteessa voidaan viitata niihin nimellä — "use `get_weather` when the caller asks about conditions" — tai agentti voi tunnistaa ne epäsuorasti skeemakuvausten perusteella. ## 5. Toteuta päätepiste Kun agentti kutsuu työkalua, ThunderPhone lähettää allekirjoitetun POST-pyynnön `endpoint_url`-osoitteeseesi: ``` 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"} ``` Palvelimesi vastaa JSONilla, joka välitetään takaisin LLM:lle: ```json theme={null} {"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8} ``` LLM käsittelee vastauksen ja kertoo soittajalle selkokielisen yhteenvedon. Allekirjoitus lasketaan pyynnön raakasisällöstä käyttäen samaa `secret`-arvoa kuin webhook-päätepisteesi. **Vahvista se** — työkalujen päätepisteet ovat internetiin näkyviä ja niihin kohdistuu samoja väärentämisriskejä kuin webhookeihin. Katso [Webhook-allekirjoitusten vahvistaminen](/fi/guides/verify-webhook-signatures). ## 6. Testaa kokonaisuus Käynnistä [mikrofonisessio](/api-reference/mic-sessions) agenttia vasten ja esitä kysymys, jota työkalusi käsittelee ("What's the weather in 94110?"). Puhelun transkriptio näyttää koko kierroksen: ```json theme={null} { "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." } ] } ``` Voit hakea tämän [`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript)-kutsulla; raaka tapahtumavirta (merkintäkohtaisine ajoituksineen ja äänisiirtymineen) on saatavilla [`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history)-kutsulla. ## Yleiset sudenkuopat LLM tekee päätöksen työkalun kuvauksen perusteella. Jos soittajan kysymys ei vastaa kuvausta, malli ei kutsu työkalua. Tarkennna kuvausta (lisää yleisiä synonyymejä ja ilmaisutapoja) tai mainitse se nimenomaisesti agentin kehotteessa ("When the caller asks about weather, use `get_weather`."). Yli 6 kB:n vastaukset katkaistaan transkription esikatselussa. Palauta vain LLM:n tarvitsemat kentät — älä koko tietuettasi. Työkalujen päätepisteiden oletusaikakatkaisu on 10 sekuntia. Jos tarvitset enemmän aikaa, käsittele pyyntö asynkronisesti: palauta `{"status": "pending", "request_id": "..."}` ja tuo tulos esiin erillisellä työkalukutsulla. Jokainen integraation `PATCH` luo uuden revision. Tarkista [`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history) nähdäksesi, kuka muutti mitäkin. Jos rikot työkalun skeeman, voit palauttaa sen manuaalisesti tekemällä PATCH-pyynnön vanhemmällä tilannevedoksella. *** ## Seuraavat vaiheet CRUD, siirto, versiohistoria. Täydellinen JSON-skeemakielioppi ja allekirjoitettujen päätepisteiden sopimus. Käytä webhook-allekirjoitusmallia työkalujen päätepisteisiin. Tarkastele työkalukutsun koko edestakaista kulkua.