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

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

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

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

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

Два дела:

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

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

Оба пута креирају сачувану интеграцију. Након чувања, повежите ту интеграцију са агентом. 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).

Декларишите 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" }
  }'

{
  "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 када креирате или ажурирате агента:

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: <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.

Честе замке#

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