Izveidojiet rīku integrāciju (API)

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.

Informācijas panelis aptver lielāko daļu rīku vajadzību arī bez šīs API: Savienojumi → Lietotnes ar dažiem OAuth klikšķiem savieno Slack, HubSpot, Salesforce, Google Calendar, Google Sheets un Cal.com; Savienojumi → API pārvērš jebkuru HTTP API par balss aģenta darbību (ielīmējiet cURL komandu, un MI vednis izveidos rīka melnrakstu ar iebūvētu Pārbaudīt pieprasījumu funkciju); un Savienojumi → MCP pievieno MCP serverus. Skatiet Savienojumi. Šī rokasgrāmata aptver neapstrādāto API, kas ir API sadaļas pamatā.

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

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

Iekļauts balss aģentā

Pievienojiet vienreizēju rīku balss aģenta tools masīvam. Vienkārši, taču nav atkārtoti izmantojams.

Saglabāta integrācija

Saglabājiet rīku kā atkārtoti izmantojamu integrāciju un saistiet to ar vairākiem balss aģentiem. Ieteicams visam, ko izmantojat vairāk nekā vienu reizi.

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

Veltiet nopietnu uzmanību rīka un katra parametra description. LLM izpildlaikā izmanto šīs virknes, lai noteiktu, vai un kā izsaukt rīku. Neskaidri apraksti → neskaidri rīku izsaukumi.

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

Response

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

Paraksts tiek aprēķināts no neapstrādātā pieprasījuma pamatteksta, izmantojot to pašu secret, ko izmanto jūsu tīmekļa aizķeres galapunkts. Pārbaudiet to — rīku galapunkti ir pieejami internetā un ir pakļauti tādiem pašiem viltošanas riskiem kā tīmekļa aizķeres. Skatiet Tīmekļa aizķeres parakstu pārbaude.

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

Balss aģents nekad neizsauc rīku

LLM pieņem lēmumu, pamatojoties uz rīka aprakstu. Ja zvanītāja jautājums neatbilst aprakstam, modelis rīku neizsauks. Precizējiet aprakstu (pievienojiet bieži lietotus sinonīmus un formulējumus) vai skaidri norādiet to balss aģenta uzvednē (“Kad zvanītājs jautā par laikapstākļiem, izmantojiet get_weather.”).

Rīks atgriež pārāk daudz datu

Atbildes, kas pārsniedz 6 kB, transkripta priekšskatījumā tiek saīsinātas. Atgrieziet tikai tos laukus, kas nepieciešami LLM — nevis visu datu ierakstu.

Noildzes

Rīku galapunktiem noklusējuma noildze ir 10 sekundes. Ja nepieciešams ilgāks laiks, apstrādājiet to asinhroni: atgrieziet {"status": "pending", "request_id": "..."} un padariet rezultātu pieejamu, izmantojot atsevišķu rīka izsaukumu.

Versiju veidošana

Katra integrācijas PATCH darbība izveido jaunu revīziju. Pārbaudiet GET /v1/integrations/{id}/versions, lai redzētu, kurš ko mainīja. Ja sabojājat rīka shēmu, varat manuāli atgriezt iepriekšējo versiju, ar PATCH pieprasījumu atjaunojot vecāku momentuzņēmumu.

Nākamās darbības

Integrāciju atsauce

CRUD, pārsūtīšana, versiju vēsture.

Function Tools specifikācija

Pilna JSON shēmas gramatika un parakstītā galapunkta līgums.

Pārbaudīt parakstus

Lietojiet tīmekļa aizķeres paraksta modeli rīku galapunktiem.

Transkripcijas + vēstures API

Pārbaudiet rīka izsaukuma pilnu turp un atpakaļ plūsmu.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Izveidojiet rīku integrāciju (API)

Rīka uzbūve

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

Iekļauts balss aģentā

Saglabāta integrācija

2. Izveidojiet integrāciju

3. Pārbaudiet galapunktu smilškastē

4. Saistiet integrāciju ar balss aģentu

5. Ieviesiet galapunktu

6. Pārbaudiet ciklu

Biežākās kļūdas

Nākamās darbības

Integrāciju atsauce

Function Tools specifikācija

Pārbaudīt parakstus

Transkripcijas + vēstures API

​Rīka uzbūve

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

Iekļauts balss aģentā

Saglabāta integrācija

​2. Izveidojiet integrāciju

​3. Pārbaudiet galapunktu smilškastē

​4. Saistiet integrāciju ar balss aģentu

​5. Ieviesiet galapunktu

​6. Pārbaudiet ciklu

​Biežākās kļūdas

​Nākamās darbības

Integrāciju atsauce

Function Tools specifikācija

Pārbaudīt parakstus

Transkripcijas + vēstures API

Rīka uzbūve

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

2. Izveidojiet integrāciju

3. Pārbaudiet galapunktu smilškastē

4. Saistiet integrāciju ar balss aģentu

5. Ieviesiet galapunktu

6. Pārbaudiet ciklu

Biežākās kļūdas

Nākamās darbības