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á modelu LLM vysvetľuje, čo nástroj robí a aké argumenty prijíma.
2. Koncový bod — adresa URL, ktorú servery ThunderPhone volajú, keď sa model LLM rozhodne nástroj použiť. Požiadavka je JSON POST s argumentmi vybranými modelom LLM v tele požiadavky.

1. Vyberte editor#

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": 200,
  "elapsed_ms": 187,
  "response_headers": { "content-type": "application/json" },
  "response_preview": "{\"temperature_f\": 64, ...}"
}

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 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#

Ďalšie kroky#