ThunderPhone v3 је сада доступан.Почните самостално, већ од 2 ¢/мин.Прочитајте објаву

Developer cookbook

Направите интеграцију алата (API)

Омогућите свом агенту да позива Ваше API-је усред разговора — претражује базу података, креира тикет, проверава поруџбину.

Интеграција алата је вишекратно употребљива HTTP крајња тачка коју агент може да позове током позива. ThunderPhone-у дајете опис алата у JSON шеми и URL крајње тачке; агент на основу разговора одлучује када да је позове, а ThunderPhone са својих сервера шаље одлазни HTTP захтев и враћа одговор агенту.

Овај водич приказује израду алата за проверу временске прогнозе од почетка до краја.

Анатомија алата

Два дела:

  1. Шема — дефиниција функције у стилу OpenAI-ја ({type: "function", function: {name, description, parameters}}) која LLM-у говори шта алат ради и које аргументе прихвата.
  2. Крајња тачка — URL који сервери ThunderPhone-а позивају када се интеграција покрене. За алате које покреће агент, захтев је JSON POST са аргументима које је LLM изабрао као телом захтева.

1. Изаберите уређивач

Контролна табла

Отворите Везе → API-ји, креирајте или уредите API везу, пребаците уређивач параметара на JSON и тамо додајте формат.

API за интеграције

Креирајте спецификацију помоћу POST /v1/integrations или је ажурирајте помоћу PATCH /v1/integrations/{id}.

Оба пута креирају сачувану интеграцију. Након чувања, повежите ту интеграцију са агентом. API за агенте нема уписиво уграђено поље tools. Овај водич користи пут API-ја за интеграције.

2. Креирајте интеграцију

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). Вредности заглавља су само за упис: одговори наводе само називе заглавља, а каснији PATCH може послати заглавље без value да би задржао сачувану вредност.

Декларишите format: "email" за параметре адресе

Параметар који прима адресу е-поште треба то да наведе у својој шеми:

"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 сервера да бисте потврдили повезивост:

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" }
  }'
Response
{
  "ok": true,
  "status_code": 200,
  "reason": "OK",
  "latency_ms": 187,
  "response_headers": { "content-type": "application/json" },
  "response_body_preview": "{\"temperature_f\": 64, ...}",
  "response_truncated": false
}

Тест садржи иста ThunderPhone заглавља као позив алатке уживо, потписана тајном веб-хука Ваше организације, па такође проверава проверу потписа: X-ThunderPhone-Call-ID: test-request, X-ThunderPhone-Signature-V2 и X-ThunderPhone-Signature. body се шаље као JSON и потписује онако како је послат; за GET, аргументе ставите у URL. Бројеви телефона позива се не шаљу, јер тест нема позив.

Овај тест такође учвршћује ThunderPhone SSRF заштите — захтеви ка localhost или опсезима приватних IP адреса враћају 400 code=url_not_allowed.

4. Повежите интеграцију са агентом

Додајте је преко integration_ids када креирате или ажурирате агента:

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-V2: t=<unix seconds>,v1=<HMAC-SHA256 hex>
X-ThunderPhone-Signature: <HMAC-SHA256 hex>
X-ThunderPhone-Call-ID: 987654321
Content-Type: application/json

{"zip": "94110"}

Ваш сервер одговара JSON-ом који се враћа LLM-у:

{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}

LLM обрађује тај одговор и позиваоцу изговара сажетак разумљив људима.

6. Тестирајте цео ток

Покрените микрофонску сесију са агентом и поставите питање које Ваша алатка обрађује („Какво је време у 94110?“). Транскрипт позива приказује цео ток:

{
  "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; необрађени ток догађаја (са временским ознакама за сваки унос и померајима звука) налази се на GET /v1/calls/{call_id}/history.

У систему Zeus, дуги транскрипти позива сада обухватају почетак и крај позива, док се средишњи део по потреби приказује по страницама, тако да и даље можете да видите како се позив завршио.

На површинама за листање позива и аналитику, ThunderPhone сада извештава о тест позивима одвојено од стварног саобраћаја. Тестови и симулације у Browser Talk-у могу поново да користе стварни број телефона и могу изгледати као долазни позиви, али се не рачунају у укупне производне позиве, оцене или показатеље проблема.

Честе замке

Агент никада не позива алатку

LLM одлучује на основу описа алатке. Ако се питање позиваоца не подудара са описом, модел неће позвати алатку. Прецизирајте опис (додајте уобичајене синониме и формулације) или је изричито наведите у упиту агента („Када позивалац пита о времену, користи get_weather.“).

Алат враћа превише података

Резултат алата остаје у разговору, а гласовни агент га поново чита при сваком наредном потезу, па велики резултат повећава трошкове и кашњење током остатка позива. Резултат већи од 100.000 знакова скраћује се на преглед, а гласовни агент добија обавештење да није потпун. Током веома дугог позива, старији резултати алата могу бити уклоњени из меморије гласовног агента; он може поново позвати алат ако су му потребни.

Да би резултати били мали:

  • Вратите само поља која су потребна гласовном агенту, а не цео ваш ред.
  • Додајте параметар како би гласовни агент могао да потражи једну ставку или категорију у исто време уместо да преузима све.
  • Велики референтни садржај (меније, каталоге, смернице) уместо тога ставите у базу знања.

Пошаљите пробни захтев на контролној табли приказује величину резултата и упозорава када је велики.

Временска ограничења

Крајње тачке алатки имају подразумевано временско ограничење од 20 секунди. Подесите spec.timeout да бисте дозволили до 180 секунди (погледајте Алатке). За алатку која чека особу или спор задатак, подесите spec.wait_mode на "hold": позивалац чује музику на чекању уместо говорних обавештења, а spec.timeout може бити до 600 секунди. Ваша крајња тачка и даље одговара у року од 180 секунди; да бисте чекали дуже, одмах вратите {"status": "pending", "request_id": "..."} и испоручите резултат касније помоћу POST /v1/calls/{call_id}/tool-results. Погледајте Дуга чекања.

Верзионисање

Сваки PATCH интеграције креира нову ревизију. Проверите GET /v1/integrations/{id}/versions да бисте видели ко је шта изменио. Ако нарушите шему алатке, можете је ручно вратити тако што ћете PATCH-овати старији снимак назад.


Следећи кораци