ThunderPhone v3 je zdaj na voljo.Začnite sami, že od 2 ¢/min.Preberite obvestilo

Developer cookbook

Izdelajte integracijo orodja (API)

Svojemu agentu omogočite klicanje API-jev med pogovorom — iskanje po zbirki podatkov, ustvarjanje zahtevka, preverjanje naročila.

Integracija orodja je končna točka HTTP za večkratno uporabo, ki jo lahko agent pokliče med klicem. ThunderPhone posredujete opis orodja v shemi JSON in URL končne točke; agent se glede na pogovor odloči, kdaj jo bo poklical, ThunderPhone pa s svojih strežnikov izvede odhodno zahtevo HTTP in odgovor vrne agentu.

Ta vodnik vas vodi skozi izdelavo orodja za preverjanje vremena od začetka do konca.

Zgradba orodja

Dva dela:

  1. Shema — definicija funkcije v slogu OpenAI ({type: "function", function: {name, description, parameters}}), ki modelu LLM pove, kaj orodje počne in katere argumente sprejema.
  2. Končna točka — URL, ki ga strežniki ThunderPhone pokličejo ob zagonu integracije. Pri orodjih, ki jih sproži agent, je zahteva JSON POST z argumenti, ki jih izbere model LLM, v telesu zahteve.

1. Izberite urejevalnik

Nadzorna plošča

Odprite Povezave → API-ji, ustvarite ali uredite povezavo API, urejevalnik parametrov preklopite na JSON in tam dodajte obliko.

API za integracije

Specifikacijo ustvarite z POST /v1/integrations ali jo posodobite z PATCH /v1/integrations/{id}.

Obe poti ustvarita shranjeno integracijo. Po shranjevanju integracijo pripnite agentu. API za agente nima zapisljivega vdelanega polja tools. Ta vodnik uporablja pot API-ja za integracije.

2. Ustvarite integracijo

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

Shranite vrnjeni id (UUID). Vrednosti glav so samo za zapisovanje: odgovori navedejo le imena glav, poznejši PATCH pa lahko pošlje glavo brez value, da ohrani shranjeno vrednost.

Pri parametrih naslovov navedite format: "email"

Parameter, ki prejme e-poštni naslov, mora to navesti v svoji shemi:

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

format je več kot le namig. Preden ThunderPhone pokliče vašo končno točko, pri razrešeni e-poštni shemi odstrani odvečne presledke iz vrednosti, domeno pretvori v male črke, samostojne angleške besede at, dot, underscore, dash in hyphen pretvori v ustrezne znake ter odstrani presledke neposredno okoli znakov @, ., _ in -. Besede imajo enak pomen ne glede na to, ali prepis že vsebuje dobesedni znak @: "john dot smith at gmail dot com" postane john.smith@gmail.com.

Vsak drug notranji presledek je zavrnjen, namesto da bi bil tiho združen. Izgovorjene besede za ločila so podprte samo v angleščini; neangleške ali neprepoznane oblike s presledki so varno zavrnjene. Veljavne internacionalizirane domene in lokalni deli SMTPUTF8 so sprejeti. Vnos v obliki Punycode po normalizaciji razčlenjevalnika ostane Punycode, vnos domene Unicode pa ostane Unicode, zato vaš API prejme običajno predstavitev, ki jo je navedel klicatelj. Če končna vrednost ni veljavna, orodje ni poklicano. Agent prejme invalid_email_argument, ki mu sporoča, naj s klicateljem potrdi črkovanje in znova pošlje dobesedni naslov.

Izpuščen izbirni e-poštni naslov ostane nespremenjen. null, prazen niz ali niz samo s presledki prav tako ostanejo nespremenjeni, kadar je lastnost izbirna ali dopušča vrednost null; enake vrednosti so zavrnjene za obvezen e-poštni naslov, ki ne dopušča vrednosti null.

Lokalne reference sheme, kot sta #/$defs/email in #/definitions/email, ter anyOf, oneOf in allOf so pregledani z omejitvami ciklov in globine. Nelokalni ali nerazrešljiv $ref je znana omejitev uveljavljanja in se posreduje nespremenjen, enako kot klic, katerega posnetek orodja nima uporabne sheme. Kadar potrebujete uporabo tega preverjanja, naj bodo e-poštne sheme lokalne.

Parametri brez uveljavljenega e-poštnega formata se posredujejo natančno tako, kot jih je ustvaril model.

Podprti formati so date-time, time, date, duration, email, hostname, ipv4, ipv6 in uuid; danes je normaliziran in uveljavljen samo email.

3. Preizkusite končno točko v peskovniku

Preden integracijo povežete z agentom, pošljite podpisano zahtevo s strežnikov ThunderPhone, da potrdite povezljivost:

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
}

Preizkus vključuje enake glave ThunderPhone kot klic orodja v živo in je podpisan s skrivnostjo spletnega kavlja vaše organizacije, zato preizkusi tudi preverjanje podpisa: X-ThunderPhone-Call-ID: test-request, X-ThunderPhone-Signature-V2 in X-ThunderPhone-Signature. body se pošlje kot JSON in podpiše v poslani obliki; pri GET argumente vnesite v URL. Telefonske številke klica se ne pošljejo, ker preizkus nima klica.

Ta preizkus tudi okrepi zaščito ThunderPhone pred SSRF — zahteve za localhost ali zasebne obsege IP vrnejo 400 code=url_not_allowed.

4. Povežite integracijo z agentom

Pri ustvarjanju ali posodabljanju agenta priložite prek 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-..."]
  }'

Z enim agentom lahko povežete več integracij. Poziv agenta se lahko nanje sklicuje po imenu — »uporabite get_weather, ko klicatelj vpraša o vremenskih razmerah« — ali pa jih lahko implicitno prepozna iz opisov shem.

5. Implementirajte končno točko

Ko agent prikliče orodje, ThunderPhone pošlje podpisano zahtevo POST na vaš 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"}

Vaš strežnik odgovori z JSON-om, ki se posreduje nazaj LLM-ju:

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

LLM obdela ta odgovor in klicatelju glasovno poda povzetek v naravnem jeziku.

6. Preizkusite potek

Zaženite sejo mikrofona z agentom in postavite vprašanje, ki ga vaše orodje obravnava (»Kakšno je vreme v 94110?«). Prepis klica prikazuje celoten potek:

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

To lahko pridobite prek GET /v1/calls/{call_id}/transcript; tok surovih dogodkov (s časovnimi podatki za posamezne vnose in odmiki zvoka) je na voljo na GET /v1/calls/{call_id}/history.

V Zeus dolgi prepisi klicev zdaj vključujejo začetek in konec klica, srednji del pa je po potrebi prikazan po straneh, zato lahko še vedno vidite, kako se je klic končal.

Na površinah za seznam klicev in analitiko ThunderPhone zdaj testne klice prikazuje ločeno od dejanskega prometa. Preizkusi in simulacije Browser Talk lahko ponovno uporabijo pravo telefonsko številko in so lahko videti kot dohodni klici, vendar se ne vštevajo v skupno število produkcijskih klicev, ocene ali meritve težav.

Pogoste težave

Agent nikoli ne pokliče orodja

LLM se odloči na podlagi opisa orodja. Če se vprašanje klicatelja ne ujema z opisom, model ne bo priklical orodja. Izboljšajte opis (dodajte pogoste sopomenke in fraze) ali ga izrecno navedite v pozivu agenta (»Ko klicatelj vpraša o vremenu, uporabite get_weather.«).

Orodje vrne preveč podatkov

Rezultat orodja ostane v pogovoru, agent pa ga znova prebere pri vsakem naslednjem koraku, zato velik rezultat poveča stroške in zakasnitev preostanka klica. Rezultat z več kot 100.000 znaki se skrajša na predogled, agent pa je obveščen, da ni popoln. Pri zelo dolgem klicu so lahko starejši rezultati orodja odstranjeni iz pomnilnika agenta; če jih potrebuje, lahko orodje znova pokliče.

Če želite ohraniti majhne rezultate:

  • Vrnite samo polja, ki jih agent potrebuje, ne celotne vrstice.
  • Dodajte parameter, da lahko agent hkrati poišče en element ali kategorijo, namesto da pridobi vse.
  • Veliko referenčno vsebino (menije, kataloge, pravilnike) namesto tega shranite v bazo znanja.

Pošlji preizkusno zahtevo na nadzorni plošči prikaže velikost rezultata in opozori, kadar je velik.

Časovne omejitve

Končne točke orodij imajo privzeto časovno omejitev 20 sekund. Nastavite spec.timeout, da omogočite do 180 sekund (glejte Orodja). Za orodje, ki čaka na osebo ali počasno opravilo, nastavite spec.wait_mode na "hold": klicatelj namesto govorjenih posodobitev sliši glasbo med čakanjem, spec.timeout pa lahko nastavite do 600 sekund. Vaša končna točka še vedno odgovori v 180 sekundah; za daljše čakanje takoj vrnite {"status": "pending", "request_id": "..."} in rezultat pozneje dostavite z POST /v1/calls/{call_id}/tool-results. Glejte Dolga čakanja.

Različice

Vsak PATCH integracije ustvari novo revizijo. Preverite GET /v1/integrations/{id}/versions, da vidite, kdo je kaj spremenil. Če pokvarite shemo orodja, lahko ročno povrnete starejši posnetek tako, da ga znova uporabite s PATCH.


Naslednji koraki