--- title: "Izradite integraciju alata (API)" description: "Omogućite svojem agentu da tijekom razgovora poziva vaše API-je — pretražuje bazu podataka, stvara tiket, provjerava narudžbu." --- **Integracija alata** višekratno je upotrebljiva HTTP krajnja točka koju agent može pozvati tijekom poziva. ThunderPhoneu dajete opis alata u JSON shemi i URL krajnje točke; agent na temelju razgovora odlučuje kada je pozvati, a ThunderPhone sa svojih poslužitelja šalje odlazni HTTP zahtjev i vraća odgovor agentu. Nadzorna ploča pokriva većinu potreba za alatima bez ovog API-ja: **Povezivanja → Aplikacije** povezuje Slack, HubSpot, Salesforce, Google Calendar, Google Sheets i Cal.com u nekoliko OAuth klikova; **Povezivanja → API-ji** pretvara bilo koji HTTP API u radnju agenta (zalijepite cURL naredbu, a AI čarobnjak izrađuje nacrt alata s ugrađenim testnim zahtjevom); i **Povezivanja → MCP** dodaje MCP poslužitelje. Pogledajte [Povezivanja](/hr/guides/concepts). Ovaj vodič obuhvaća osnovni API ispod sučelja API-ja. Ovaj vodič vodi Vas kroz izradu alata za dohvaćanje vremenske prognoze od početka do kraja. ## Anatomija alata Dva dijela: 1. **Shema** — definicija funkcije u stilu OpenAI-ja (`{type: "function", function: {name, description, parameters}}`) koja LLM-u govori što alat radi i koje argumente prihvaća. 2. **Krajnja točka** — URL koji poslužitelji ThunderPhonea pozivaju kada LLM odluči upotrijebiti alat. Zahtjev je JSON POST, a tijelo sadrži argumente koje je odabrao LLM. ## 1. Odaberite uređivač Otvorite **Povezivanja → API-ji**, izradite ili uredite API vezu, prebacite uređivač parametara na **JSON** i tamo dodajte format. Izradite specifikaciju pomoću `POST /v1/integrations` ili je ažurirajte pomoću `PATCH /v1/integrations/{id}`. Oba načina stvaraju spremljenu integraciju. Nakon spremanja priložite tu integraciju agentu. API za agente nema upisivo ugrađeno polje `tools`. Ovaj vodič koristi put API-ja za integracije. ## 2. Izradite integraciju ```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" } ] }' ``` Spremite vraćeni `id` (UUID). Posvetite stvarnu pažnju `description` polju alata i svakog parametra. LLM koristi te nizove tijekom izvođenja kako bi odlučio treba li i kako pozvati alat. Nejasni opisi → nejasni pozivi alata. ### Navedite `format: "email"` za parametre adrese Parametar koji prima adresu e-pošte trebao bi to navesti u svojoj shemi: ```json "email": { "type": "string", "format": "email", "description": "The caller's email address" } ``` `format` je više od naznake. Za razriješenu shemu e-pošte, prije poziva vaše krajnje točke ThunderPhone uklanja razmake s početka i kraja vrijednosti, pretvara domenu u mala slova, samostalne engleske riječi `at`, `dot`, `underscore`, `dash` i `hyphen` pretvara u njihove znakove te uklanja razmake neposredno oko znakova `@`, `.`, `_` i `-`. Riječi imaju isto značenje bez obzira na to sadrži li transkript već doslovni znak `@`: `"john dot smith at gmail dot com"` postaje `john.smith@gmail.com`. Svaki drugi unutarnji razmak odbija se umjesto da se tiho spoji. Izgovorene riječi za razdjelnike podržane su samo na engleskom; oblici s razmacima na drugim jezicima ili neprepoznati oblici sigurno ne prolaze. Prihvaćaju se valjane internacionalizirane domene i lokalni dijelovi SMTPUTF8. Unos u punycodeu ostaje u punycodeu, a Unicode unos domene ostaje Unicode nakon normalizacije parsera, tako da vaš API prima uobičajeni prikaz koji je naveo pozivatelj. Ako je konačna vrijednost nevaljana, alat se **ne poziva**. Agent prima `invalid_email_argument`, što mu govori da s pozivateljem potvrdi način pisanja i ponovno pošalje doslovnu adresu. Izostavljena neobavezna e-pošta ostaje nepromijenjena. `null`, prazan niz ili niz koji sadrži samo razmake također ostaju nepromijenjeni kada je svojstvo neobavezno ili dopušta null; iste se vrijednosti odbijaju za obaveznu e-poštu koja ne dopušta null. Lokalne reference sheme kao što su `#/$defs/email` i `#/definitions/email`, kao i `anyOf`, `oneOf` i `allOf`, provjeravaju se uz ograničenja ciklusa i dubine. Nelokalni ili nerazrješivi `$ref` poznato je ograničenje provedbe i prosljeđuje se nepromijenjen, kao i poziv čija snimka alata nema upotrebljivu shemu. Zadržite sheme e-pošte lokalnima kada trebate primijeniti provjeru. Parametri bez provedbenog formata e-pošte prosljeđuju se točno onako kako ih je model proizveo. Podržani formati su `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `ipv4`, `ipv6` i `uuid`; danas se normalizira i provodi samo `email`. ## 3. Testirajte krajnju točku u sandboxu Prije nego što povežete integraciju s agentom, pošaljite potpisani zahtjev s ThunderPhone poslužitelja kako biste potvrdili povezivost: ```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, ...}" } ``` Ovaj test također učvršćuje ThunderPhone SSRF zaštite — zahtjevi za localhost ili privatne IP raspone vraćaju `400 code=url_not_allowed`. ## 4. Povežite integraciju s agentom Priložite putem `integration_ids` kada stvarate ili ažurirate agenta: ```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-..."] }' ``` Možete povezati više integracija s jednim agentom. Uputa agenta može ih navesti po nazivu — „upotrijebi `get_weather` kada pozivatelj pita o vremenskim uvjetima” — ili ih može implicitno otkriti iz opisa sheme. ## 5. Implementirajte krajnju točku Kada agent pozove alat, ThunderPhone šalje potpisani POST na vaš `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"} ``` Vaš poslužitelj odgovara JSON-om koji se prosljeđuje natrag LLM-u: ```json {"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8} ``` LLM obrađuje taj odgovor i pozivatelju izgovara sažetak prirodnim jezikom. Potpis se izračunava nad neobrađenim tijelom zahtjeva pomoću istog `secret` kao i za vašu krajnju točku webhooka. **Provjerite ga** — krajnje točke alata dostupne su s interneta i podložne istim rizicima lažiranja kao webhookovi. Pogledajte [Provjera potpisa webhooka](/hr/guides/verify-webhook-signatures). ## 6. Testirajte cijeli tijek Pokrenite [mikrofonsku sesiju](/api-reference/mic-sessions) prema agentu i postavite pitanje kojim se vaš alat bavi („Kakvo je vrijeme u 94110?”). Transkript poziva prikazuje cijeli tijek: ```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." } ] } ``` Ovo možete dohvatiti putem [`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript); tok neobrađenih događaja (s vremenom svake stavke i pomacima zvuka) nalazi se na [`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history). ## Uobičajene poteškoće LLM odlučuje na temelju opisa alata. Ako pitanje pozivatelja ne odgovara opisu, model neće pozvati alat. Precizirajte opis (dodajte uobičajene sinonime i formulacije) ili ga izričito navedite u uputi agenta („Kada pozivatelj pita o vremenu, upotrijebi `get_weather`.”). Odgovori veći od 6 kB skraćuju se u pregledu transkripta. Vratite samo polja koja su potrebna LLM-u — ne cijeli svoj redak. Krajnje točke alata imaju zadano vremensko ograničenje od 10 sekundi. Ako vam treba više vremena, obradite zahtjev asinkrono: vratite `{"status": "pending", "request_id": "..."}` i prikažite rezultat putem zasebnog poziva alata. Svaki `PATCH` integracije stvara novu reviziju. Pregledajte [`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history) kako biste vidjeli tko je što promijenio. Ako pokvarite shemu alata, možete je ručno vratiti slanjem PATCH zahtjeva sa starijom snimkom. --- ## Sljedeći koraci CRUD, prijenos, povijest verzija. Potpuna gramatika JSON sheme i ugovor o potpisanoj krajnjoj točki. Primijenite obrazac potpisa webhooka na krajnje točke alata. Pregledajte cijeli tijek poziva alata.