ThunderPhone v3 je tu.Začnite sami, už od 2 ¢/min.Prečítať oznámenie

Developer cookbook

Vytvorte integráciu nástroja (API)

Umožnite svojmu agentovi volať vaše API počas konverzácie — vyhľadávať v databáze, vytvárať tikety, vyhľadávať objednávky.

Integrácia nástroja je opakovane použiteľný koncový bod HTTP, ktorý môže hlasový agent vyvolať počas hovoru. ThunderPhone poskytnete opis nástroja v schéme JSON spolu s adresou URL koncového bodu; hlasový agent rozhodne, kedy ho vyvolať, na základe konverzácie a ThunderPhone odošle odchádzajúcu požiadavku HTTP zo svojich serverov a vráti odpoveď hlasovému agentovi.

Táto príručka vás prevedie vytvorením nástroja na vyhľadávanie počasia od začiatku do konca.

Štruktúra nástroja

Dve časti:

  1. Schéma — definícia funkcie v štýle OpenAI ({type: "function", function: {name, description, parameters}}), ktorá LLM informuje o tom, čo nástroj robí a aké argumenty prijíma.
  2. Koncový bod — adresa URL, ktorú servery ThunderPhone volajú pri spustení integrácie. Pri nástrojoch spúšťaných agentom je požiadavka JSON POST s argumentmi vybranými LLM v tele požiadavky.

1. Vyberte editor

Panel

Otvorte Prepojenia → Rozhrania API, vytvorte alebo upravte pripojenie API, prepnite editor parametrov na JSON a pridajte tam formát.

API integrácií

Vytvorte špecifikáciu pomocou POST /v1/integrations alebo ju aktualizujte pomocou PATCH /v1/integrations/{id}.

Obe cesty vytvoria uloženú integráciu. Po uložení túto integráciu pripojte k hlasovému agentovi. API agentov nemá zapisovateľné vložené pole tools. Táto príručka používa cestu API integrácií.

2. Vytvorte integráciu

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" }
    ]
  }'

Uložte vrátené id (UUID). Hodnoty hlavičiek sú určené iba na zápis: odpovede uvádzajú len názvy hlavičiek a neskorší PATCH môže odoslať hlavičku bez value, aby sa zachovala uložená hodnota.

Pri parametroch adresy deklarujte format: "email"

Parameter, ktorý prijíma e-mailovú adresu, to musí uvádzať vo svojej schéme:

"email": { "type": "string", "format": "email", "description": "The caller's email address" }

format je viac než len nápoveda. Pri vyhodnotenej e-mailovej schéme ThunderPhone pred zavolaním vášho endpointu odstráni medzery na okrajoch hodnoty, prevedie doménu na malé písmená, samostatné anglické slová at, dot, underscore, dash a hyphen nahradí ich znakmi a odstráni medzery priamo okolo @, ., _ a -. Tieto slová majú rovnaký význam bez ohľadu na to, či prepis už obsahuje doslovné @: "john dot smith at gmail dot com" sa zmení na john.smith@gmail.com.

Akékoľvek iné vnútorné medzery sa zamietnu namiesto toho, aby sa potichu spojili. Vyslovené slová oddeľovačov sú podporované iba v angličtine; neanglické alebo nerozpoznané formy s medzerami sa bezpečne zamietnu. Platné internacionalizované domény a lokálne časti SMTPUTF8 sú prijaté. Vstup v punycode zostáva po normalizácii parserom v punycode a vstup domény v Unicode zostáva v Unicode, takže vaše API dostane bežné zastúpenie poskytnuté volajúcim. Ak je výsledná hodnota neplatná, nástroj sa nezavolá. Agent dostane invalid_email_argument, ktoré mu oznámi, aby s volajúcim potvrdil pravopis a znovu odoslal doslovnú adresu.

Vynechaný voliteľný e-mail zostane nezmenený. null, prázdny reťazec alebo reťazec obsahujúci iba medzery tiež zostanú nezmenené, keď je vlastnosť voliteľná alebo povoľuje hodnotu null; rovnaké hodnoty sa zamietnu pri povinnom e-maile, ktorý nepovoľuje null.

Lokálne odkazy na schému, napríklad #/$defs/email a #/definitions/email, spolu s anyOf, oneOf a allOf, sa kontrolujú s limitmi cyklov a hĺbky. Nelokálny alebo nevyriešiteľný $ref je známy limit vynucovania a prechádza bez zmeny, rovnako ako volanie, ktorého snímka nástroja nemá použiteľnú schému. Keď potrebujete uplatniť túto kontrolu, ponechajte e-mailové schémy lokálne.

Parametre bez vynucovaného formátu e-mailu prechádzajú presne tak, ako ich vytvoril model.

Podporované formáty sú date-time, time, date, duration, email, hostname, ipv4, ipv6 a uuid; v súčasnosti sa normalizuje a vynucuje iba email.

3. Otestujte endpoint v sandboxe

Pred prepojením integrácie s agentom odošlite podpísanú požiadavku zo serverov ThunderPhone na potvrdenie konektivity:

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
}

Test obsahuje rovnaké hlavičky ThunderPhone ako ostré volanie nástroja a je podpísaný tajným kľúčom webhooku vašej organizácie, takže zároveň otestuje vašu kontrolu podpisu: X-ThunderPhone-Call-ID: test-request, X-ThunderPhone-Signature-V2 a X-ThunderPhone-Signature. body sa odosiela ako JSON a podpisuje sa v odoslanej podobe; pri GET uveďte argumenty v adrese URL. Telefónne čísla hovoru sa neodosielajú, pretože test nemá žiadny hovor.

Tento test tiež posilňuje ochrany ThunderPhone proti SSRF — požiadavky na localhost alebo súkromné rozsahy IP vrátia 400 code=url_not_allowed.

4. Prepojte integráciu s agentom

Pri vytváraní alebo aktualizácii hlasového agenta ju pripojte pomocou 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-..."]
  }'

K jednému hlasovému agentovi môžete prepojiť viac integrácií. Výzva agenta na ne môže odkazovať podľa názvu — „použi get_weather, keď volajúci žiada informácie o počasí“ — alebo ich môže implicitne rozpoznať z popisov schémy.

5. Implementujte koncový bod

Keď agent vyvolá nástroj, ThunderPhone odošle podpísanú požiadavku POST na váš 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"}

Váš server odpovie JSON-om, ktorý sa odovzdá späť LLM:

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

LLM túto odpoveď spracuje a volajúcemu ju zhrnie prirodzenou rečou.

6. Otestujte celý cyklus

Spustite reláciu mikrofónu s agentom a položte otázku, ktorú váš nástroj spracúva („Aké je počasie v 94110?“). Prepis hovoru zobrazuje celý priebeh:

{
  "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." }
  ]
}

Môžete ho načítať cez GET /v1/calls/{call_id}/transcript; tok nespracovaných udalostí (s časovaním jednotlivých záznamov a posunmi zvuku) nájdete na GET /v1/calls/{call_id}/history.

V Zeus teraz dlhé prepisy hovorov obsahujú začiatok aj koniec hovoru, pričom stredná časť sa podľa potreby stránkuje, takže stále vidíte, ako sa hovor skončil.

V rozhraniach na výpis hovorov a v analytike ThunderPhone teraz uvádza testovacie hovory oddelene od reálnej prevádzky. Testy a simulácie Browser Talk môžu opätovne použiť skutočné telefónne číslo a môžu vyzerať ako prichádzajúce hovory, nezapočítavajú sa však do celkového počtu produkčných hovorov, hodnotení ani metrík problémov.

Bežné problémy

Agent nikdy nevolá nástroj

LLM rozhoduje na základe popisu nástroja. Ak otázka volajúceho nezodpovedá popisu, model nástroj nevyvolá. Spresnite popis (pridajte bežné synonymá a formulácie) alebo ho výslovne uveďte vo výzve agenta („Keď volajúci žiada informácie o počasí, použi get_weather.“).

Nástroj vracia príliš veľa údajov

Výsledok nástroja zostáva v konverzácii a agent ho pri každom ďalšom kroku znova načíta, takže veľký výsledok zvyšuje náklady a predlžuje zvyšok hovoru. Výsledok s viac ako 100 000 znakmi sa skráti na ukážku a agent dostane informáciu, že nie je úplný. Pri veľmi dlhom hovore môžu byť staršie výsledky nástroja odstránené z pamäte agenta; ak ich potrebuje, môže nástroj zavolať znova.

Ak chcete výsledky udržať malé:

  • Vráťte iba polia, ktoré agent potrebuje, nie celý riadok.
  • Pridajte parameter, aby agent mohol vyhľadať jednu položku alebo kategóriu naraz namiesto načítania všetkého.
  • Veľký referenčný obsah (ponuky, katalógy, pravidlá) radšej vložte do vedomostnej databázy.

Odoslať testovaciu požiadavku na ovládacom paneli zobrazuje veľkosť výsledku a upozorní vás, keď je veľký.

Časové limity

Koncové body nástrojov majú predvolený časový limit 20 sekúnd. Nastavte spec.timeout na hodnotu až 180 sekúnd (pozrite si Nástroje). Pre nástroj, ktorý čaká na osobu alebo pomalú úlohu, nastavte spec.wait_mode na "hold": volajúci namiesto hovorených aktualizácií počuje hudbu počas čakania a spec.timeout môže byť až 600 sekúnd. Váš koncový bod stále odpovie do 180 sekúnd; ak chcete čakať dlhšie, okamžite vráťte {"status": "pending", "request_id": "..."} a výsledok doručte neskôr pomocou POST /v1/calls/{call_id}/tool-results. Pozrite si Dlhé čakania.

Verziovanie

Každý PATCH integrácie vytvorí novú revíziu. Skontrolujte GET /v1/integrations/{id}/versions, aby ste zistili, kto čo zmenil. Ak poškodíte schému nástroja, môžete ju manuálne vrátiť späť opätovným PATCH-ovaním staršej snímky.


Ďalšie kroky