Developer cookbook

Izveidojiet rīku integrāciju (API)

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

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

Šajā rokasgrāmatā ir aprakstīta laikapstākļu meklēšanas rīka izveide no sākuma līdz beigām.

Rīka uzbūve#

Divas daļas:

1. Shēma — OpenAI stila 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, kura pamattekstā ir LLM izvēlētie argumenti.

1. Izvēlieties glabāšanas stratēģiju#

Šajā rokasgrāmatā izmantots saglabātās integrācijas 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).

3. Pārbaudiet 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, ...}"
}

Šī pārbaude 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 balss aģentu#

Pievienojiet to, izmantojot integration_ids, kad veidojat vai atjaunināt balss 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 balss aģentam varat saistīt vairākas integrācijas. Balss aģenta uzvednē tās var norādīt pēc nosaukuma — "izmantojiet get_weather, kad zvanītājs jautā par laikapstākļiem" — vai arī tas var tās netieši noteikt pēc shēmu aprakstiem.

5. Ieviesiet galapunktu#

Kad balss 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: <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 zvanītājam sniedz cilvēkam saprotamu kopsavilkumu.

6. Pārbaudiet ciklu#

Palaidiet mikrofona sesiju pret balss aģentu un uzdodiet jautājumu, ko apstrādā jūsu rīks ("Kādi ir laikapstākļi 94110?"). Zvana transkripts parāda pilnu pieprasījuma un atbildes ciklu:

{
  "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 laikiem un audio nobīdēm) ir pieejama vietnē GET /v1/calls/{call_id}/history.

Biežākās kļūdas#

Nākamās darbības#