---
title: "Izdelajte integracijo orodja (API)"
description: "Svojemu agentu omogočite klicanje API-jev med pogovorom — iskanje po zbirki podatkov, ustvarjanje zahtevka, preverjanje naročila."
---
**Integracija orodja** je končna točka HTTP za večkratno uporabo, ki jo lahko agent
pokliče med klicem. ThunderPhone posredujete opis orodja v shemi JSON
in URL končne točke; agent se glede na pogovor odloči, kdaj jo bo poklical,
ThunderPhone pa s svojih strežnikov izvede odhodno zahtevo HTTP in odgovor
vrne agentu.
Nadzorna plošča pokriva večino potreb po orodjih brez tega API-ja: **Povezave
→ Aplikacije** z nekaj kliki OAuth poveže Slack, HubSpot, Salesforce, Google Calendar,
Google Sheets in Cal.com; **Povezave →
API-ji** spremeni kateri koli API HTTP v dejanje agenta (prilepite ukaz cURL,
čarovnik z umetno inteligenco pa pripravi osnutek orodja z vgrajeno možnostjo Preskus zahteve);
**Povezave → MCP** doda strežnike MCP. Oglejte si
[Povezave](/sl/guides/concepts). Ta vodnik opisuje osnovni
API pod vmesnikom API-jev.
Ta vodnik vas vodi skozi izdelavo orodja za preverjanje vremena od začetka do konca.
## Zgradba orodja
Dva dela:
1. **Shema** — definicija funkcije v slogu OpenAI
(`{type: "function", function: {name, description, parameters}}`),
ki LLM-ju pove, kaj orodje počne in katere argumente sprejema.
2. **Končna točka** — URL, ki ga strežniki ThunderPhone pokličejo, ko se
LLM odloči uporabiti orodje. Zahteva je JSON POST, telo pa vsebuje
argumente, ki jih izbere LLM.
## 1. Izberite urejevalnik
Odprite **Povezave → API-ji**, ustvarite ali uredite povezavo API,
urejevalnik parametrov preklopite na **JSON** in tam dodajte obliko.
Specifikacijo ustvarite z `POST /v1/integrations` ali jo posodobite z
`PATCH /v1/integrations/{id}`.
Obe poti ustvarita shranjeno integracijo. Po shranjevanju integracijo
pripnite agentu. API za agente nima zapisljivega vdelanega polja `tools`.
Ta vodnik uporablja pot API-ja za integracije.
## 2. Ustvarite integracijo
```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" }
]
}'
```
Shranite vrnjeni `id` (UUID).
Resno se posvetite `description` orodja in vsakega parametra. LLM te nize med izvajanjem uporablja za odločanje, ali in kako naj pokliče orodje. Nejasni opisi → nejasni klici orodja.
### Pri parametrih naslovov navedite `format: "email"`
Parameter, ki prejme e-poštni naslov, mora to navesti v svoji shemi:
```json
"email": { "type": "string", "format": "email", "description": "The caller's email address" }
```
`format` je več kot le namig. Preden ThunderPhone pokliče vašo končno točko, pri razrešeni e-poštni shemi odstrani odvečne presledke iz vrednosti, domeno pretvori v male črke, samostojne angleške besede `at`, `dot`, `underscore`, `dash` in `hyphen` pretvori v ustrezne znake ter odstrani presledke neposredno okoli znakov `@`, `.`, `_` in `-`. Besede imajo enak pomen ne glede na to, ali prepis že vsebuje dobesedni znak `@`:
`"john dot smith at gmail dot com"` postane
`john.smith@gmail.com`.
Vsak drug notranji presledek je zavrnjen, namesto da bi bil tiho združen. Izgovorjene besede za ločila so podprte samo v angleščini; neangleške ali neprepoznane oblike s presledki so varno zavrnjene. Veljavne internacionalizirane domene in lokalni deli SMTPUTF8 so sprejeti. Vnos v obliki Punycode po normalizaciji razčlenjevalnika ostane Punycode, vnos domene Unicode pa ostane Unicode, zato vaš API prejme običajno predstavitev, ki jo je navedel klicatelj. Če končna vrednost ni veljavna, orodje **ni poklicano**. Agent prejme
`invalid_email_argument`, ki mu sporoča,
naj s klicateljem potrdi črkovanje in znova pošlje dobesedni naslov.
Izpuščen izbirni e-poštni naslov ostane nespremenjen. `null`, prazen niz ali niz samo s presledki prav tako ostanejo nespremenjeni, kadar je lastnost izbirna ali dopušča vrednost null; enake vrednosti so zavrnjene za obvezen e-poštni naslov, ki ne dopušča vrednosti null.
Lokalne reference sheme, kot sta `#/$defs/email` in
`#/definitions/email`, ter `anyOf`, `oneOf` in `allOf` so pregledani
z omejitvami ciklov in globine. Nelokalni ali nerazrešljiv `$ref` je
znana omejitev uveljavljanja in se posreduje nespremenjen, enako kot klic,
katerega posnetek orodja nima uporabne sheme. Kadar potrebujete uporabo tega preverjanja, naj bodo e-poštne sheme lokalne.
Parametri brez uveljavljenega e-poštnega formata se posredujejo natančno tako, kot jih je ustvaril model.
Podprti formati so `date-time`, `time`, `date`, `duration`,
`email`, `hostname`, `ipv4`, `ipv6` in `uuid`; danes je normaliziran in uveljavljen samo `email`.
## 3. Preizkusite končno točko v peskovniku
Preden integracijo povežete z agentom, pošljite podpisano zahtevo
s strežnikov ThunderPhone, da potrdite povezljivost:
```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, ...}"
}
```
Ta preizkus tudi okrepi zaščito ThunderPhone pred SSRF — zahteve za localhost ali zasebne obsege IP vrnejo `400 code=url_not_allowed`.
## 4. Povežite integracijo z agentom
Pri ustvarjanju ali posodabljanju agenta priložite prek `integration_ids`:
```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-..."]
}'
```
Z enim agentom lahko povežete več integracij. Poziv agenta se lahko
nanje sklicuje po imenu — »uporabite `get_weather`, ko klicatelj vpraša
o vremenskih razmerah« — ali pa jih lahko implicitno prepozna iz
opisov shem.
## 5. Implementirajte končno točko
Ko agent prikliče orodje, ThunderPhone pošlje podpisano zahtevo 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š strežnik odgovori z JSON-om, ki se posreduje nazaj LLM-ju:
```json
{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}
```
LLM obdela ta odgovor in klicatelju glasovno poda povzetek v naravnem jeziku.
Podpis se izračuna iz surovega telesa zahteve z uporabo istega
`secret` kot vaša končna točka webhooka. **Preverite ga** — končne točke
orodij so javno dostopne prek interneta in izpostavljene enakim tveganjem
ponarejanja kot webhooki. Glejte
[Preverjanje podpisov webhookov](/sl/guides/verify-webhook-signatures).
## 6. Preizkusite potek
Zaženite [sejo mikrofona](/api-reference/mic-sessions) z agentom
in postavite vprašanje, ki ga vaše orodje obravnava (»Kakšno je vreme
v 94110?«). Prepis klica prikazuje celoten potek:
```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 lahko pridobite prek
[`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript);
tok surovih dogodkov (s časovnimi podatki za posamezne vnose in odmiki zvoka) je na voljo na
[`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history).
## Pogoste težave
LLM se odloči na podlagi opisa orodja. Če se vprašanje klicatelja
ne ujema z opisom, model ne bo priklical orodja. Izboljšajte opis
(dodajte pogoste sopomenke in fraze) ali ga izrecno navedite v pozivu
agenta (»Ko klicatelj vpraša o vremenu, uporabite `get_weather`.«).
Odgovori, večji od 6 kB, so v predogledu prepisa skrajšani. Vrnite
samo polja, ki jih LLM potrebuje — ne celotne vrstice.
Končne točke orodij imajo privzeto časovno omejitev 10 sekund. Če potrebujete več časa,
to obravnavajte asinhrono: vrnite `{"status": "pending", "request_id": "..."}`
in rezultat prikažite prek ločenega klica orodja.
Vsak `PATCH` integracije ustvari novo revizijo. Preverite
[`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history),
da vidite, kdo je kaj spremenil. Če pokvarite shemo orodja, lahko
ročno povrnete starejši posnetek tako, da ga znova uporabite s PATCH.
---
## Naslednji koraki
CRUD, prenos, zgodovina različic.
Celotna slovnica sheme JSON in pogodba podpisane končne točke.
Vzorec podpisov webhookov uporabite za končne točke orodij.
Preglejte celoten potek klica orodja.