Izveidojiet rīka integrāciju (API)

Ļaujiet savam balss aģentam sarunas laikā izsaukt jūsu API — meklēt datubāzē, izveidot pieteikumu, atrast pasūtījumu.

Rīku integrācija ir atkārtoti izmantojams HTTP galapunkts, ko balss aģents var izsaukt zvana laikā. Jūs sniedzat ThunderPhone rīka JSON shēmas aprakstu un galapunkta URL; balss aģents, balstoties uz sarunu, nosaka, kad to izsaukt, un ThunderPhone no saviem serveriem nosūta izejošo HTTP pieprasījumu un atgriež atbildi balss aģentam.

Šajā rokasgrāmatā soli pa solim izveidosiet laikapstākļu pārbaudes rīku.

Rīka uzbūve#

Divas daļas:

1. Shēma — OpenAI tipa funkcijas definīcija ({type: "function", function: {name, description, parameters}}), kas LLM norāda, ko rīks dara un kādus argumentus tas pieņem.
2. Galapunkts — URL, ko ThunderPhone serveri izsauc, kad LLM nolemj izmantot rīku. Pieprasījums ir JSON POST ar LLM izvēlētajiem argumentiem pamattekstā.

1. Izvēlieties redaktoru#

Abos veidos tiek izveidota saglabāta integrācija. Pēc saglabāšanas pievienojiet šo integrāciju balss aģentam. Aģentu API nav rakstāma iekļauta tools lauka. Šajā rokasgrāmatā izmantots integrāciju API ceļš.

2. Izveidojiet integrāciju#

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

Saglabājiet atgriezto id (UUID). Galveņu vērtības ir tikai rakstīšanai: atbildēs tiek uzskaitīti tikai galveņu nosaukumi, un vēlākā PATCH pieprasījumā var nosūtīt galveni bez value, lai saglabātu esošo vērtību.

Adreses parametriem deklarējiet format: "email"#

Parametram, kas saņem e-pasta adresi, tas jānorāda tā shēmā:

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

format ir vairāk nekā tikai norāde. Atrisinātai e-pasta shēmai pirms jūsu galapunkta izsaukšanas ThunderPhone apgriež vērtību, domēnu pārveido par mazajiem burtiem, atsevišķos angļu vārdus at, dot, underscore, dash un hyphen pārvērš attiecīgajās rakstzīmēs, kā arī noņem atstarpes tieši ap @, ., _ un -. Vārdiem ir tāda pati nozīme neatkarīgi no tā, vai transkripts jau satur burtisku @: "john dot smith at gmail dot com" kļūst par john.smith@gmail.com.

Jebkuras citas iekšējās atstarpes tiek noraidītas, nevis klusi savienotas. Izrunātie atdalītāju vārdi ir pieejami tikai angļu valodā; citu valodu vai neatpazītas formas ar atstarpēm tiek droši noraidītas. Tiek pieņemti derīgi internacionalizēti domēni un SMTPUTF8 lokālās daļas. Punycode ievade pēc parsētāja normalizācijas paliek punycode, un Unicode domēna ievade paliek Unicode, tādēļ jūsu API saņem zvanītāja norādīto ierasto attēlojumu. Ja galīgā vērtība nav derīga, rīks netiek izsaukts. Balss aģents saņem invalid_email_argument, kas tam norāda apstiprināt pareizrakstību ar zvanītāju un atkārtoti nosūtīt burtisko adresi.

Izlaista neobligāta e-pasta adrese netiek mainīta. null, tukša virkne vai virkne, kurā ir tikai atstarpes, arī netiek mainīta, ja rekvizīts ir neobligāts vai pieļauj null vērtību; tās pašas vērtības tiek noraidītas obligātai e-pasta adresei, kas nepieļauj null vērtību.

Lokālās shēmu atsauces, piemēram, #/$defs/email un #/definitions/email, kā arī anyOf, oneOf un allOf, tiek pārbaudītas ar ciklu un dziļuma ierobežojumiem. Nelokāla vai neatrisināma $ref ir zināms izpildes ierobežojums un tiek nodota tālāk bez izmaiņām, tāpat kā izsaukums, kura rīka momentuzņēmumam nav izmantojamas shēmas. Ja vēlaties, lai tiktu piemērota pārbaude, saglabājiet e-pasta shēmas lokālas.

Parametri bez izpildāma e-pasta formāta tiek nodoti tālāk tieši tā, kā tos izveidoja modelis.

Atbalstītie formāti ir date-time, time, date, duration, email, hostname, ipv4, ipv6 un uuid; pašlaik tiek normalizēts un pārbaudīts tikai email.

3. Testējiet galapunktu smilškastē#

Pirms saistāt integrāciju ar balss aģentu, nosūtiet parakstītu pieprasījumu no ThunderPhone serveriem, lai apstiprinātu savienojamību:

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 tests arī nostiprina ThunderPhone SSRF aizsardzību — pieprasījumi uz localhost vai privātiem IP diapazoniem atgriež 400 code=url_not_allowed.

4. Saistiet integrāciju ar aģentu#

Pievienojiet, izmantojot integration_ids, kad veidojat vai atjaunināt aģentu:

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

Vienam aģentam varat saistīt vairākas integrācijas. Aģenta uzvednē var uz tām atsaukties pēc nosaukuma — "izmantojiet get_weather, kad zvanītājs jautā par laikapstākļiem" — vai arī aģents tās var netieši atpazīt pēc shēmas aprakstiem.

5. Ieviesiet galapunktu#

Kad aģents izsauc rīku, ThunderPhone nosūta parakstītu POST pieprasījumu uz jūsu 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ūsu serveris atbild ar JSON, kas tiek nodots atpakaļ LLM:

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

LLM apstrādā šo atbildi un sniedz zvanītājam saprotamu kopsavilkumu.

6. Pārbaudiet ciklu#

Palaidiet mikrofona sesiju ar aģentu un uzdodiet jautājumu, ko apstrādā jūsu rīks ("Kādi ir laikapstākļi 94110?"). Zvanu atšifrējumā redzams pilns pieprasījuma un atbildes cikls:

{
  "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 varat iegūt, izmantojot GET /v1/calls/{call_id}/transcript; neapstrādātā notikumu plūsma (ar katra ieraksta laika informāciju un audio nobīdēm) ir pieejama vietnē GET /v1/calls/{call_id}/history.

Zvanu sarakstu un analītikas sadaļās ThunderPhone tagad testa zvanus uzrāda atsevišķi no reālās datplūsmas. Browser Talk testi un simulācijas var atkārtoti izmantot īstu tālruņa numuru un var izskatīties kā ienākošie zvani, taču tie netiek ieskaitīti produkcijas zvanu kopsummās, vērtējumos vai problēmu rādītājos.

Biežākās kļūdas#

Nākamās darbības#