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

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

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

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

Два дела:

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

1. Изаберите стратегију чувања

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

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

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. Тестирајте циклус

Покрените mic сесију са агентом и поставите питање које ваша алатка обрађује („Какво је време у 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.

Честе замке

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