Open in
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:
- 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. - 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
Otvorte Prepojenia → Rozhrania API, vytvorte alebo upravte pripojenie API, prepnite editor parametrov na JSON a pridajte tam formát.
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" }
}'{
"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.