> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
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](/lv/guides/concepts). Šī 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:
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
Pievienojiet vienreizēju rīku balss aģenta `tools` masīvam. Vienkārši, taču
nav atkārtoti izmantojams.
Saglabājiet rīku kā atkārtoti izmantojamu [integrāciju](/api-reference/integrations)
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
```bash theme={null}
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:
```bash theme={null}
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" }
}'
```
```json Response theme={null}
{
"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:
```bash theme={null}
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:
X-ThunderPhone-Call-ID: 987654321
Content-Type: application/json
{"zip": "94110"}
```
Jūsu serveris atbild ar JSON, kas tiek nodots atpakaļ LLM:
```json theme={null}
{"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](/lv/guides/verify-webhook-signatures).
## 6. Pārbaudiet ciklu
Palaidiet [mikrofona sesiju](/api-reference/mic-sessions) 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:
```json theme={null}
{
"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`](/api-reference/calls#get-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`](/api-reference/calls#get-history).
## Biežākās kļūdas
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`.").
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.
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.
Katra integrācijas `PATCH` darbība izveido jaunu revīziju. Pārbaudiet
[`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history),
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
CRUD, pārsūtīšana, versiju vēsture.
Pilna JSON shēmas gramatika un parakstītā galapunkta līgums.
Lietojiet tīmekļa aizķeres paraksta modeli rīku galapunktiem.
Pārbaudiet rīka izsaukuma pilnu turp un atpakaļ plūsmu.