---
title: "Направите интеграцију алата (API)"
description: "Омогућите свом агенту да позива Ваше API-је усред разговора — претражује базу података, креира тикет, проверава поруџбину."
---
Интеграција алата је вишекратно употребљива HTTP крајња тачка коју агент може да позове током позива. ThunderPhone-у дајете опис алата у JSON шеми и URL крајње тачке; агент на основу разговора одлучује када да је позове, а ThunderPhone са својих сервера шаље одлазни HTTP захтев и враћа одговор агенту.
Контролна табла покрива већину потреба за алатима без овог API-ја: **Везе
→ Апликације** повезује Slack, HubSpot, Salesforce, Google Calendar,
Google Sheets и Cal.com у неколико OAuth кликова; **Везе →
API-ји** претвара било који HTTP API у радњу агента (налепите cURL команду,
а AI чаробњак креира нацрт алата, са уграђеном опцијом Тестирај захтев); и
**Везе → MCP** додаје MCP сервере. Погледајте
[Везе](/sr/guides/concepts). Овај водич се односи на основни
API испод интерфејса API-ја.
Овај водич приказује израду алата за проверу временске прогнозе од почетка до краја.
## Анатомија алата
Два дела:
1. **Шема** — дефиниција функције у OpenAI стилу
(`{type: "function", function: {name, description, parameters}}`)
која LLM-у говори шта алат ради и које аргументе прихвата.
2. **Крајња тачка** — URL који ThunderPhone сервери позивају када
LLM одлучи да користи алат. Захтев је JSON POST, са аргументима које је
LLM изабрао у телу захтева.
## 1. Изаберите уређивач
Отворите **Везе → API-ји**, креирајте или уредите API везу,
пребаците уређивач параметара на **JSON** и тамо додајте формат.
Креирајте спецификацију помоћу `POST /v1/integrations` или је ажурирајте помоћу
`PATCH /v1/integrations/{id}`.
Оба пута креирају сачувану интеграцију. Након чувања, повежите ту интеграцију са
агентом. API за агенте нема уписиво уграђено поље `tools`.
Овај водич користи пут API-ја за интеграције.
## 2. Креирајте интеграцију
```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" }
]
}'
```
Сачувајте враћени `id` (UUID).
Уложите стварни труд у `description` алата и сваког параметра.
LLM користи ове ниске током извршавања да одлучи да ли и како
да позове алат. Нејасни описи → нејасни позиви алата.
### Декларишите `format: "email"` за параметре адресе
Параметар који прима адресу е-поште треба то да наведе у својој
шеми:
```json
"email": { "type": "string", "format": "email", "description": "The caller's email address" }
```
`format` је више од наговештаја. За разрешену шему е-поште, пре него што
се позове Ваша крајња тачка, ThunderPhone уклања размаке са почетка и краја вредности, претвара
домен у мала слова, претвара самосталне енглеске речи `at`, `dot`, `underscore`,
`dash` и `hyphen` у одговарајуће знакове и уклања размаке
непосредно око `@`, `.`, `_` и `-`. Речи имају исто значење
без обзира на то да ли транскрипт већ садржи дослован знак `@`:
`"john dot smith at gmail dot com"` постаје
`john.smith@gmail.com`.
Сваки други унутрашњи размак се одбија уместо да се неприметно споји.
Изговорене речи за раздвајање подржане су само на енглеском; неенглески или непрепознати
облици са размацима се безбедно одбијају. Прихватају се важећи интернационализовани домени и SMTPUTF8
локални делови. Унос у паникоду остаје у паникоду, а унос домена у Уникоду остаје у Уникоду након нормализације парсера, тако да Ваш API
прима уобичајени приказ који је доставио позивалац. Ако је коначна
вредност неважећа, алат се **не позива**. Агент прима
`invalid_email_argument`, што му говори
да потврди правопис са позиваоцем и поново пошаље дословну адресу.
Изостављена опционална адреса е-поште остаје непромењена. `null`, празан ниска или
ниска која садржи само размаке такође остају непромењени када је својство опционо
или прихвата вредност null; исте вредности се одбијају за обавезну адресу е-поште која не прихвата null.
Локалне референце шеме као што су `#/$defs/email` и
`#/definitions/email`, као и `anyOf`, `oneOf` и `allOf`, проверавају се
уз ограничења циклуса и дубине. Нелокални или неразрешиви `$ref` је
познато ограничење спровођења и прослеђује се непромењен, као и позив
чији снимак алата нема употребљиву шему. Нека шеме е-поште буду локалне када
Вам је потребно да се примени провера.
Параметри без наметнутог формата е-поште прослеђују се тачно онако
како их је модел произвео.
Подржани формати су `date-time`, `time`, `date`, `duration`,
`email`, `hostname`, `ipv4`, `ipv6` и `uuid`; данас се нормализује и намеће само `email`.
## 3. Тестирајте крајњу тачку у изолованом окружењу
Пре него што повежете интеграцију са агентом, пошаљите потписани захтев
са ThunderPhone сервера да бисте потврдили повезивост:
```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, ...}"
}
```
Овај тест такође учвршћује ThunderPhone SSRF заштите — захтеви ка
localhost или опсезима приватних IP адреса враћају `400 code=url_not_allowed`.
## 4. Повежите интеграцију са агентом
Додајте је преко `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-..."]
}'
```
Можете повезати више интеграција са једним агентом. Упит агента може
да их наводи по имену — „користи `get_weather` када позивалац пита
о временским условима“ — или их може посредно открити из
описа шеме.
## 5. Имплементирајте крајњу тачку
Када агент позове алатку, ThunderPhone шаље потписани POST на
Ваш `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"}
```
Ваш сервер одговара JSON-ом који се враћа LLM-у:
```json
{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}
```
LLM обрађује тај одговор и позиваоцу изговара сажетак разумљив људима.
Потпис се израчунава преко необрађеног тела захтева користећи исти
`secret` као Ваша webhook крајња тачка. **Проверите га** — крајње тачке
алатки су доступне са интернета и подложне су истим ризицима од
лажирања као webhook-ови. Погледајте
[Проверите webhook потписе](/sr/guides/verify-webhook-signatures).
## 6. Тестирајте цео ток
Покрените [микрофонску сесију](/api-reference/mic-sessions) са агентом
и поставите питање које Ваша алатка обрађује („Какво је време у
94110?“). Транскрипт позива приказује цео ток:
```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." }
]
}
```
Ово можете преузети преко
[`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript);
необрађени ток догађаја (са временским ознакама за сваки унос и
померајима звука) налази се на
[`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history).
## Честе замке
LLM одлучује на основу описа алатке. Ако се питање позиваоца не
подудара са описом, модел неће позвати алатку. Прецизирајте опис
(додајте уобичајене синониме и формулације) или је изричито
наведите у упиту агента („Када позивалац пита о времену, користи
`get_weather`.“).
Одговори већи од 6 kB се скраћују у прегледу транскрипта. Вратите
само поља која су потребна LLM-у — не цео запис.
Крајње тачке алатки имају подразумевано ограничење времена од 10 секунди. Ако Вам је потребно више,
обрадите то асинхроно: вратите `{"status": "pending", "request_id": "..."}`
и прикажите резултат преко засебног позива алатке.
Сваки `PATCH` интеграције креира нову ревизију. Проверите
[`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history)
да бисте видели ко је шта изменио. Ако нарушите шему алатке, можете
је ручно вратити тако што ћете PATCH-овати старији снимак назад.
---
## Следећи кораци
CRUD, пренос, историја верзија.
Потпуна граматика JSON шеме и уговор за потписану крајњу тачку.
Примените образац потписа веб-куке на крајње тачке алатки.
Прегледајте целокупан ток позива алатке.