ThunderPhone v3 jau veikia.Viską atlikite savarankiškai – nuo 2 ct/min.Skaityti pranešimą

Developer cookbook

Sukurkite įrankio integraciją (API)

Leiskite savo agentui pokalbio metu kviesti jūsų API — ieškoti duomenų bazėje, sukurti užklausą, rasti užsakymą.

Įrankio integracija yra pakartotinai naudojamas HTTP galinis punktas, kurį agentas gali iškviesti pokalbio metu. ThunderPhone pateikiate įrankio JSON schemos aprašą ir galinio punkto URL; agentas pagal pokalbį nusprendžia, kada jį iškviesti, o ThunderPhone iš savo serverių siunčia išeinančią HTTP užklausą ir grąžina atsakymą agentui.

Šiame vadove nuo pradžios iki pabaigos aprašoma, kaip sukurti orų paieškos įrankį.

Įrankio sandara

Dvi dalys:

  1. Schema — OpenAI stiliaus funkcijos apibrėžimas ({type: "function", function: {name, description, parameters}}), nurodantis LLM, ką įrankis daro ir kokius argumentus priima.
  2. Galinis taškas — URL, kurį ThunderPhone serveriai iškviečia vykdant integraciją. Agento suaktyvinamiems įrankiams užklausa yra JSON POST, kurio turinį sudaro LLM pasirinkti argumentai.

1. Pasirinkite redaktorių

Valdymo skydelis

Atidarykite Ryšiai → API, sukurkite arba redaguokite API ryšį, perjunkite parametrų redaktorių į JSON ir ten pridėkite formatą.

Integracijų API

Sukurkite specifikaciją naudodami POST /v1/integrations arba atnaujinkite ją naudodami PATCH /v1/integrations/{id}.

Abiem būdais sukuriama išsaugota integracija. Išsaugoję susiekite tą integraciją su agentu. Agentų API neturi redaguojamo įterptinio tools lauko. Šiame vadove naudojamas integracijų API būdas.

2. Sukurkite integraciją

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

Išsaugokite grąžintą id (UUID). Antraščių reikšmės yra tik įrašomos: atsakymuose pateikiami tik antraščių pavadinimai, o vėlesnė PATCH užklausa gali siųsti antraštę be value, kad būtų išsaugota saugoma reikšmė.

Adreso parametruose nurodykite format: "email"

Parametras, gaunantis el. pašto adresą, savo schemoje turėtų tai nurodyti:

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

format yra daugiau nei užuomina. Išspręstos el. pašto schemos atveju, prieš iškviečiant jūsų galinį tašką, ThunderPhone pašalina reikšmės kraštinius tarpus, domeną pakeičia mažosiomis raidėmis, pavienius angliškus žodžius at, dot, underscore, dash ir hyphen pakeičia atitinkamais simboliais bei pašalina tarpus tiesiogiai šalia @, ., _ ir -. Šie žodžiai turi tą pačią reikšmę, nepaisant to, ar nuoraše jau yra pažodinis @: "john dot smith at gmail dot com" tampa john.smith@gmail.com.

Bet kokie kiti vidiniai tarpai atmetami, užuot tyliai sujungiami. Ištarti skyriklių žodžiai palaikomi tik anglų kalba; neangliškos arba neatpažintos formos su tarpais yra saugiai atmetamos. Priimami galiojantys internacionalizuoti domenai ir SMTPUTF8 vietinės dalys. Punycode įvestis po analizatoriaus normalizavimo lieka punycode, o Unicode domeno įvestis lieka Unicode, todėl jūsų API gauna skambintojo pateiktą įprastą atvaizdavimą. Jei galutinė reikšmė netinkama, įrankis neiškviečiamas. Agentas gauna invalid_email_argument, nurodantį jam patvirtinti rašybą su skambintoju ir iš naujo išsiųsti pažodinį adresą.

Praleistas pasirenkamas el. pašto adresas neliečiamas. null, tuščia eilutė arba eilutė, sudaryta tik iš tarpų, taip pat neliečiama, kai savybė yra pasirenkama arba leidžianti null reikšmę; tos pačios reikšmės atmetamos, kai el. pašto adresas yra privalomas ir neleidžiantis null reikšmės.

Tikrinamos vietinės schemos nuorodos, pvz., #/$defs/email ir #/definitions/email, taip pat anyOf, oneOf ir allOf, taikant ciklų ir gylio ribas. Nevietinis arba neišsprendžiamas $ref yra žinomas tikrinimo apribojimas ir perduodamas nepakitęs, kaip ir iškvietimas, kurio įrankio momentinė kopija neturi tinkamos schemos. Kai reikia taikyti patikrą, el. pašto schemas laikykite vietines.

Parametrai be priverstinai taikomo el. pašto formato perduodami tiksliai taip, kaip juos sukūrė modelis.

Palaikomi formatai: date-time, time, date, duration, email, hostname, ipv4, ipv6 ir uuid; šiuo metu normalizuojamas ir tikrinamas tik email.

3. Išbandykite galinį tašką smėlio dėžėje

Prieš susiedami integraciją su agentu, išsiųskite pasirašytą užklausą iš ThunderPhone serverių, kad patvirtintumėte ryšį:

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
}

Testas siunčia tas pačias ThunderPhone antraštes kaip tiesioginis įrankio iškvietimas, pasirašytas jūsų organizacijos webhook paslaptimi, todėl jis taip pat patikrina jūsų parašo tikrinimą: X-ThunderPhone-Call-ID: test-request, X-ThunderPhone-Signature-V2 ir X-ThunderPhone-Signature. body siunčiamas kaip JSON ir pasirašomas toks, koks išsiųstas; naudojant GET, argumentus pateikite URL. Skambučio telefono numeriai nesiunčiami, nes testas neturi skambučio.

Šis testas taip pat sustiprina ThunderPhone SSRF apsaugą — užklausos į localhost arba privačius IP diapazonus grąžina 400 code=url_not_allowed.

4. Susiekite integraciją su agentu

Pridėkite naudodami integration_ids, kai kuriate arba atnaujinate agentą:

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

Su vienu agentu galite susieti daug integracijų. Agento raginime galima nurodyti jas pagal pavadinimą — „naudokite get_weather, kai skambinantysis klausia apie oro sąlygas“ — arba agentas gali jas numanomai aptikti pagal schemos aprašus.

5. Įgyvendinkite galinį tašką

Kai agentas iškviečia įrankį, ThunderPhone siunčia pasirašytą POST užklausą į jūsų 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"}

Jūsų serveris atsako JSON duomenimis, kurie perduodami atgal LLM:

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

LLM apdoroja šį atsakymą ir balsu pateikia skambinančiajam žmonėms suprantamą santrauką.

6. Išbandykite ciklą

Paleiskite mikrofono sesiją su agentu ir užduokite klausimą, kurį apdoroja jūsų įrankis („Koks oras 94110?“). Skambučio transkripte rodoma visa užklausos ir atsakymo eiga:

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

Tai galite gauti naudodami GET /v1/calls/{call_id}/transcript; neapdorotas įvykių srautas (su kiekvieno įrašo laiko žymomis ir garso poslinkiais) pateikiamas adresu GET /v1/calls/{call_id}/history.

Zeus aplinkoje ilguose skambučių nuorašuose dabar pateikiama skambučio pradžia ir pabaiga, o prireikus vidurinė dalis rodoma puslapiais, todėl vis tiek galite matyti, kaip skambutis baigėsi.

Skambučių sąrašo ir analizės rodiniuose ThunderPhone dabar bandomuosius skambučius pateikia atskirai nuo tikro srauto. Browser Talk testai ir simuliacijos gali pakartotinai naudoti tikrą telefono numerį ir atrodyti kaip įeinantys skambučiai, tačiau jie neįskaičiuojami į gamybinių skambučių sumas, įvertinimus ar problemų metriką.

Dažnos klaidos

Agentas niekada neiškviečia įrankio

LLM sprendžia pagal įrankio aprašą. Jei skambinančiojo klausimas neatitinka aprašo, modelis įrankio neiškvies. Patikslinkite aprašą (pridėkite dažnus sinonimus ir formuluotes) arba aiškiai paminėkite jį agento raginime („Kai skambinantysis klausia apie orą, naudokite get_weather.“).

Įrankis grąžina per daug duomenų

Įrankio rezultatas išlieka pokalbyje, o agentas jį perskaito iš naujo kiekviename vėlesniame pokalbio žingsnyje, todėl didelis rezultatas didina likusios skambučio dalies kainą ir delsą. Daugiau nei 100 000 simbolių rezultatas sutrumpinamas iki peržiūros, o agentui pranešama, kad jis neišsamus. Labai ilgo skambučio metu senesni įrankio rezultatai gali būti pašalinti iš agento atminties; jei jų reikia, jis gali dar kartą iškviesti įrankį.

Kad rezultatai būtų nedideli:

  • Grąžinkite tik agentui reikalingus laukus, o ne visą įrašo eilutę.
  • Pridėkite parametrą, kad agentas galėtų vienu metu rasti vieną elementą ar kategoriją, užuot gavęs viską.
  • Didelės apimties informacinį turinį (meniu, katalogus, politiką) pateikite žinių bazėje.

Valdymo skydelyje Siųsti bandomąją užklausą rodoma, kokio dydžio yra rezultatas, ir įspėjama, kai jis didelis.

Laiko limitai

Įrankių galiniams taškams numatytasis laiko limitas yra 20 sekundžių. Nustatykite spec.timeout, kad leistumėte iki 180 sekundžių (žr. Įrankiai). Įrankiui, kuris laukia žmogaus arba lėtai vykdomos užduoties, nustatykite spec.wait_mode į "hold": skambintojas girdės laukimo muziką vietoje sakytinių pranešimų, o spec.timeout gali būti iki 600 sekundžių. Jūsų galinis taškas vis tiek turi atsakyti per 180 sekundžių; jei reikia laukti ilgiau, nedelsdami grąžinkite {"status": "pending", "request_id": "..."} ir pateikite rezultatą vėliau naudodami POST /v1/calls/{call_id}/tool-results. Žr. Ilgas laukimas.

Versijavimas

Kiekvienas integracijos PATCH sukuria naują peržiūrą. Peržiūrėkite GET /v1/integrations/{id}/versions, kad pamatytumėte, kas ką pakeitė. Jei sugadinate įrankio schemą, galite rankiniu būdu grąžinti ankstesnę būseną, naudodami PATCH ir atkurdami senesnę momentinę kopiją.


Tolesni veiksmai