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 tipo funkcijos apibrėžimas ({type: "function", function: {name, description, parameters}}), kuris nurodo LLM, ką įrankis daro ir kokius argumentus jis priima.
2. Galinis punktas — URL, kurį ThunderPhone serveriai iškviečia, kai LLM nusprendžia naudoti įrankį. Užklausa yra JSON POST užklausa, kurios turinyje pateikiami LLM pasirinkti argumentai.

1. Pasirinkite redaktorių#

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).

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

{
  "ok": true,
  "status": 200,
  "elapsed_ms": 187,
  "response_headers": { "content-type": "application/json" },
  "response_preview": "{\"temperature_f\": 64, ...}"
}

Š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: <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.

Dažnos klaidos#

Tolesni veiksmai#