Open in
Алатке функција
Омогућите својим AI агентима алатке функција које позивају спољне API-је усред разговора — преузимају податке о клијентима, заказују термине, ажурирају евиденцију — са типизираним параметрима.
Алатке функција омогућавају Вашим AI агентима да позивају спољне API-је током телефонских позива. Користите их за проналажење података о клијентима, проверу доступности, заказивање термина или извршавање било које радње коју подржава Ваш позадински систем.
Како функционише
- Дефинишете алатке помоћу шеме (које аргументе алатка прихвата)
- Наводите конфигурацију
endpoint(где ThunderPhone позива Ваш API) — или је изостављате да бисте примали позиве алатки на webhook-у Ваше организације - Током позива, AI одлучује када да користи алатку на основу разговора
- ThunderPhone позива Ваш endpoint са аргументима алатке
- Одговор Вашег API-ја се враћа AI-ју ради наставка разговора
| Могућност | Где се извршава | Подешавање |
|---|---|---|
| Уграђене алатке | ThunderPhone | Упутства у prompt-у; неке алатке захтевају и подешавање агента |
| Повезивања са апликацијама | ThunderPhone и повезани добављач | Повежите налог и приложите одобрене радње |
| API повезивања и алатке функција | Ваш HTTP API | Дефинишите endpoint и шему или примајте позиве функција преко webhook-а |
| MCP сервери | Удаљени MCP сервер | Додајте сервер, откријте његове алатке и приложите га агенту |
Шема алатке
Свака алатка прати ову структуру:
{
"type": "function",
"function": {
"name": "search_appointments",
"description": "Find available appointment slots for a given date",
"parameters": {
"type": "object",
"properties": {
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format"
},
"service": {
"type": "string",
"description": "Type of service (e.g., 'consultation', 'follow-up')"
}
},
"required": ["date"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/search",
"method": "POST",
"headers": {
"X-Api-Key": "your-api-key"
}
},
"timeout": 120
}Конфигурација алатке
| Поље | Тип | Обавезно | Опис |
|---|---|---|---|
timeout | број | Не | Максимално време извршавања у секундама (подразумевано: 20, максимално: 180, или 600 са wait_mode: "hold") |
wait_mode | ниска | Не | Шта позивалац чује док се алат извршава: updates (подразумевано), кратка говорна обавештења; или hold, музика на чекању. Погледајте Дуга чекања: режим чекања и каснији одговор |
call_start | објекат | Не | Аутоматски покрените алат и на почетку сваког телефонског позива, пре поздрава. Погледајте Покретање алата на почетку позива |
Дефиниција функције
| Поље | Тип | Обавезно | Опис |
|---|---|---|---|
name | ниска | Да | Идентификатор алата, јединствен међу алатима једног позива. Различити агенти могу имати сопствени алат са истим именом |
description | ниска | Да | Објашњава AI-ју када да користи овај алат |
parameters | објекат | Да | JSON шема за аргументе алата |
Конфигурација endpoint-а
| Поље | Тип | Обавезно | Опис |
|---|---|---|---|
url | ниска | Да | URL endpoint-а Вашег API-ја |
method | ниска | Не | HTTP метода (подразумевано: POST) |
headers | објекат | Не | Прилагођена заглавља која треба укључити |
Два пута позивања
Који захтев ће Ваш сервер примити зависи од тога да ли алатка има
endpoint:
Алатка са endpoint | Алатка без endpoint | |
|---|---|---|
| Куда се захтев шаље | Директно на endpoint.url | Наслеђени Webhook URL ваше организације |
| Тело | Изабрани формат захтева (подразумевано сами аргументи) | Омотач telephony.tool / web.tool |
| Заглавља | Ваше endpoint.headers + X-ThunderPhone-Call-ID + X-ThunderPhone-Signature-V2 + X-ThunderPhone-Signature, као и бројеви позива у телефонским позивима | Content-Type + X-ThunderPhone-Signature-V2 + X-ThunderPhone-Signature |
| Кључ за потписивање | Тајна за Webhook организације | Тајна за Webhook организације |
Оба пута су блокирајућа — AI чека резултат усред реченице. Подразумевано временско ограничење је 20 s; подесите timeout на највишем нивоу алатке да бисте омогућили дуже извршавање, до максималних 180 s на платформи. Нека обрађивачи буду брзи. За чекање особе или спорог посла користите режим чекања. Комбинација је у реду: при позиву чија организација има URL веб-закачке, алатке са endpoint се позивају директно, а остале се враћају на веб-закачку.
Директни позиви крајњих тачака
Када AI позове алат који има endpoint, ThunderPhone шаље
захтев на Ваш URL:
Заглавља захтева
POST /appointments/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-ThunderPhone-Signature-V2: t=1767225600,v1=5f2c...
X-ThunderPhone-Signature: abc123...
X-ThunderPhone-Call-ID: 987654321
X-ThunderPhone-From-Number: +14155550199
X-ThunderPhone-To-Number: +14155550100
X-ThunderPhone-Call-Direction: inbound
X-Api-Key: your-api-keyПрилагођена заглавља из вашег endpoint.headers увек се укључују
дословно, као и следећа заглавља у ThunderPhone простору имена:
X-ThunderPhone-Signature-V2— HMAC-SHA256 са временском ознаком над методом, путањом, упитом и телом, са кључем који је ваша тајна вредност веб-куке организације. Проверите овај потпис и одбијте захтеве старије од 5 минута; погледајте Проверите потписе веб-кукеX-ThunderPhone-Signature— застарели HMAC-SHA256 тачних бајтова тела захтева, са истим кључем, који се и даље шаље за постојеће системе за проверуX-ThunderPhone-Call-ID— ИД тренутног позиваX-ThunderPhone-From-NumberиX-ThunderPhone-To-Number— бројеви пошиљаоца и примаоца позива у формату E.164. Имају исто значење каоfrom_numberиto_numberуtelephony.complete: код одлазног позива, број пошиљаоца је број вашег агента, а број примаоца је број позване особе. Број се изоставља када је идентификација позиваоца скривена или није телефонски бројX-ThunderPhone-Call-Direction—inboundилиoutbound, тако да можете одредити који је број корисников
Заглавља са бројевима позива шаљу се само за телефонске позиве. Тестови на вебу, у виџету,
у реалном времену и у прегледачу Talk немају телефонски број и изостављају их.
Пробни позиви из уређивача агента и AI симулације садрже број симулираног
позиваоца. Потписи не
обухватају заглавља: V2 потписује временску ознаку, метод, путању, упит и тело. Ако
вам је потребно да бројеви буду потписани, уместо тога их прочитајте из тела:
формат захтева retell садржи сва три, а vapi садржи број
корисника.
Content-Type: application/json је постављен осим ако га Ваш
endpoint.headers не замени — прилагођени Content-Type има предност.
Формат захтева
Свака API веза има подешавање request_format. Изаберите vapi или
retell када увезени алат треба да настави да позива крајњу тачку направљену за
ту платформу. Нове и постојеће везе подразумевано користе standard.
За POST / PUT / PATCH, ThunderPhone серијализује изабрани
омотач канонски (сортирани кључеви, компактни раздвајачи). Оба потписа
обухватају управо ове бајтове.
Standard
standard шаље само аргументе алата, без омотача. Ово је
подразумевано понашање и чува оригинално тело захтева ThunderPhone-а бајт по бајт:
{"date":"2025-01-02","service":"consultation"}Vapi
vapi шаље Vapi tool-calls серверску поруку
у облику који Vapi документује. call.id је ID ThunderPhone позива.
У телефонским позивима, call.customer.number је број друге стране, као у
Vapi објекту позива: позивалац код долазног позива, а особа која се позива
код одлазног позива. Изоставља се када је тај број сакривен или није
телефонски број. id позива алатке је јединствен за позивање и
поново се користи за повезивање са резултатом крајње тачке. Позив се појављује и у toolCallList и у
toolWithToolCallList, при чему је function.arguments JSON објекат:
{
"message": {
"type": "tool-calls",
"timestamp": 1725000000123,
"call": { "id": "987654321" },
"toolCallList": [
{
"id": "call_00112233445566778899aabbccddeeff",
"type": "function",
"function": {
"name": "search_appointments",
"arguments": { "date": "2025-01-02", "service": "consultation" }
}
}
],
"toolWithToolCallList": [
{
"type": "function",
"function": { "name": "search_appointments" },
"toolCall": {
"id": "call_00112233445566778899aabbccddeeff",
"type": "function",
"function": {
"name": "search_appointments",
"arguments": { "date": "2025-01-02", "service": "consultation" }
}
}
}
]
}
}Поља која су само за Vapi, као што су assistant, artifact и цео објекат
call, не шаљу се.
Вратите Vapi-јев омотач одговора са одговарајућим ID-јем позива алата:
{
"results": [
{
"toolCallId": "call_00112233445566778899aabbccddeeff",
"result": "{\"available_slots\":[\"9:00 AM\",\"2:00 PM\"]}"
}
]
}ThunderPhone прослеђује AI-ју распаковани ниску result. Прихвата и
JSON вредност ради компатибилности са крајњим тачкама које је већ враћају. Ако је
error враћен уместо result, AI-ју се враћа као грешка алата. Ако
крајња тачка врати неисправан или неусклађен Vapi омотач, ThunderPhone бележи
упозорење и враћа се на стандардно рашчлањивање одговора уместо да неуспешно
заврши позив.
Retell
retell шаље захтев документован за Retell прилагођену
функцију:
{
"name": "search_appointments",
"call": {
"call_id": "987654321",
"from_number": "+14155550199",
"to_number": "+14155550100",
"direction": "inbound"
},
"args": { "date": "2025-01-02", "service": "consultation" }
}У телефонским позивима објекат call садржи call_id, from_number,
to_number и direction (inbound или outbound), називе поља које
користи Retell-ов објекат телефонског позива. Они одговарају заглављима
броја позива и, за разлику од заглавља, обухваћени су обема потписима.
Број који је сакривен или није телефонски број се изоставља. У веб,
виџет, реалновременским и Talk тестовима у прегледачу садржи само
call_id. ThunderPhone не укључује поља специфична за Retell која не
може поуздано да достави при слању, као што су agent_id, transcript,
transcript_object, metadata или динамичке променљиве. Retell прихвата
било које тело одговора; ThunderPhone га прослеђује коришћењем стандардне
обраде одговора.
За GET / DELETE, аргументи се шаљу као параметри упита
а тело је празно без обзира на request_format. V2 потпис
обухвата ниску упита онако како је послата; застарели потпис се израчунава над
празном ниском бајтова. Погледајте
Верификација потписа webhook-а.
Одговор
Вратите JSON одговор са резултатом алата:
{
"available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"],
"timezone": "America/Los_Angeles"
}Одговор се форматира и доставља AI-ју да настави
разговор. Одговори који нису JSON умотавају се као {"data": "<text>"};
истеци времена и грешке везе пријављују се AI-ју као грешке, тако да
агент може да се извини и настави уместо да застане.
Отпремање у режиму вебхука
Алати без endpoint шаљу се на застарели URL вебхука Ваше
организације као потписани захтев telephony.tool (телефонски позиви) или web.tool
(веб позиви). За разлику од обавештења за ревизију
која се испоручују вебхук крајњим тачкама након извршавања, овај захтев јесте
извршавање — Ваш HTTP одговор је резултат алата.
{
"type": "telephony.tool",
"data": {
"call_id": 987654321,
"tool_name": "search_appointments",
"arguments": { "date": "2026-04-21" },
"from_number": "+14155550199",
"to_number": "+15551234567"
}
}web.tool садржи origin_domain уместо from_number /
to_number. Одговорите резултатом алата у JSON формату — према истом уговору о одговору као код директних позива крајње тачке. Захтев је потписан тајном webhook вредношћу организације, са оба заглавља потписа, као и сваки други webhook.
Дуга чекања: режим чекања и накнадни одговор
Неки алати чекају на особу: менаџера који одобрава попуст, власника
који одговара на питање у Slack-у. За те алате подесите wait_mode на "hold".
wait_mode: "updates" (подразумевано) | wait_mode: "hold" | |
|---|---|---|
| Шта позивалац чује | Ред при покретању алата, затим кратак ред „и даље радим“ након око 12 с и још један отприлике сваких 15 с | Ред при покретању алата, затим музика на чекању док не стигне резултат |
Максимално timeout | 180 с | 600 с |
| Одговори на чекању | Прослеђују се агенту као резултат | Алат остаје отворен док не доставите резултат |
У режиму чекања агент изговори један ред када се алат покрене (сопственим речима или ред при покретању алата подешен на агенту), а затим позивалац чује музику на чекању. Музика се постепено утишава пре него што агент изговори резултат. За алат који одговори у року од једне или две секунде музика се уопште не пушта. Када агент разговара са телефонским менијем или сандучетом говорне поште, уместо тога користи говорна обавештења, јер би се музика могла чути као одговор. То важи и за позив за који се усред чекања утврди да је мени или сандуче: музика се зауставља и преузимају говорна обавештења. Исто важи за позив у ком музика не може да се пусти.
Ако позивалац говори током чекања, музика наставља да се пушта и агент још не одговара. Он чује шта је позивалац рекао и одговара на то заједно са резултатом. Прекид позива завршава позив и отворени алат.
Накнадни одговор
Сопствени одговор Ваше крајње тачке и даље мора да стигне у року од 180 с. Да бисте позиваоца задржали дуже, одмах одговорите резултатом на чекању:
{ "status": "pending", "request_id": "ask-4471" }request_id је било који ниска од највише 200 знакова која идентификује овај
захтев на Вашој страни. Позивалац остаје на чекању док за њега не доставите
резултат путем
POST /v1/calls/{call_id}/tool-results.
call_id је заглавље X-ThunderPhone-Call-ID захтева алата.
curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_id": "ask-4471",
"result": { "answer": "Yes, book Tuesday at 10." }
}'Агент чита result као одговор алата, исто као да га је Ваша крајња тачка
вратила. Ако резултат не стигне пре timeout вредности алата, рачунато од
тренутка када је алат позван, агенту се саопштава да одговор није стигао и
позиваоцу нуди наредне кораке, као што је остављање поруке.
Резултат можете послати кад год желите, чак и пре него што је Ваш одговор на
чекању стигао до ThunderPhone-а. 202 значи да га је позив прихватио: преузео
га је отворен захтев или је сопствени захтев алата још у току па ће га преузети
његов одговор на чекању. Резултат који ниједан захтев никада не преузме (Ваша
крајња тачка је затим одговорила нечим другим уместо одговора на чекању за тај
request_id) се одбацује.
Ако веза има трансформацију одговора (код који преписује одговор Ваше крајње
тачке пре него што га агент види), трансформација се покреће над сопственим
одговором Ваше крајње тачке, пре него што ThunderPhone провери постоји ли
одговор на чекању, па у одговору на чекању мора да задржи status и
request_id. Не покреће се над резултатом који касније пошаљете: агент добија
тај резултат онако како га пошаљете.
Агент у пуном дуплексу нема музику на чекању ни редове са обавештењима, па се на
његовим позивима алат на чекању понаша као алат updates: одговор на чекању
стиже до агента као резултат алата.
Одговор на чекању алата у режиму updates не остаје отворен: агент га прима као
резултат алата.
Верификација потписа
Директни позиви алатки потписују се на исти начин као веб-хукови, помоћу тајне за веб-хукове Ваше организације:
X-ThunderPhone-Signature-V2потписује временску ознаку, метод, путању и упит онако како су послати, као и тачне бајтове тела. Одбијте захтеве чија је временска ознака удаљена више од 5 минута од Вашег сата.X-ThunderPhone-Signature(застарело) потписује само бајтове тела, односно празан низ бајтова заGET/DELETE. И даље се шаље, непромењено.
SDK помоћне функције проверавају V2 заглавље, укључујући период од 5 минута:
import json
from fastapi import FastAPI, HTTPException, Request
from thunderphone import verify_signature
app = FastAPI()
@app.post("/appointments/search")
async def search_appointments(request: Request):
body = await request.body()
query = request.scope.get("query_string", b"").decode("latin-1")
path = request.url.path + (f"?{query}" if query else "")
if not verify_signature(
request.headers.get("X-ThunderPhone-Signature-V2"),
secret=WEBHOOK_SECRET,
method=request.method,
path=path,
body=body,
):
raise HTTPException(status_code=401)
data = json.loads(body)
date = data["date"]
# Look up availability
slots = await get_available_slots(date)
return {"available_slots": slots}import express from "express";
import { verifySignature } from "@thunderphone/sdk";
app.post('/appointments/search', express.raw({type: 'application/json'}), (req, res) => {
const ok = verifySignature({
header: req.header('X-ThunderPhone-Signature-V2'),
secret: WEBHOOK_SECRET,
method: req.method,
path: req.originalUrl,
body: req.body,
});
if (!ok) return res.status(401).send('Invalid signature');
const { date, service } = JSON.parse(req.body);
// Look up availability
const slots = getAvailableSlots(date, service);
res.json({ available_slots: slots });
});Комплетни примери — потписани низ, разрађен пример, код без
SDK-а, случај GET / DELETE и напомена о одсуству тајне — налазе се у Провера потписа веб-хукова.
Пример: Комплетан ток заказивања
Ево скупа алата за комплетан систем заказивања термина:
{
"tools": [
{
"type": "function",
"function": {
"name": "search_appointments",
"description": "Find available appointment slots",
"parameters": {
"type": "object",
"properties": {
"date": { "type": "string", "description": "YYYY-MM-DD" },
"service": { "type": "string" }
},
"required": ["date"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/search",
"method": "POST",
"headers": { "X-Api-Key": "key" }
}
},
{
"type": "function",
"function": {
"name": "book_appointment",
"description": "Book an appointment at a specific time",
"parameters": {
"type": "object",
"properties": {
"date": { "type": "string", "description": "YYYY-MM-DD" },
"time": { "type": "string", "description": "HH:MM format" },
"customer_name": { "type": "string" },
"customer_phone": { "type": "string" }
},
"required": ["date", "time", "customer_name"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/book",
"method": "POST",
"headers": { "X-Api-Key": "key" }
}
},
{
"type": "function",
"function": {
"name": "cancel_appointment",
"description": "Cancel an existing appointment",
"parameters": {
"type": "object",
"properties": {
"confirmation_number": { "type": "string" }
},
"required": ["confirmation_number"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/cancel",
"method": "POST",
"headers": { "X-Api-Key": "key" }
}
}
]
}Покрените алат на почетку позива
Алат се такође може аутоматски покренути на почетку сваког телефонског позива, пре него што агент изговори прву реч, тако да поздрав може да користи резултат. Уобичајен случај је CRM претрага по броју позиваоца: „Добро дошли назад, Арти! Да ли желите своју уобичајену поруџбину?“
На контролној табли отворите API везу и подесите Када се покреће на
На почетку сваког телефонског позива, а затим унесите вредност коју добија сваки
параметар. Преко API-ја подесите trigger интеграције на
call_start и њене call_start_arguments
(API везе), или додајте блок call_start
у уграђени алат:
{
"type": "function",
"function": {
"name": "get_contact_by_phone",
"description": "Look up a customer by phone number.",
"parameters": {
"type": "object",
"properties": {
"business_id": {"type": "string"},
"phone_number": {"type": "string"}
},
"required": ["business_id", "phone_number"]
}
},
"endpoint": {"url": "https://crm.example.com/contacts/lookup"},
"call_start": {
"arguments": {
"business_id": "a0a81c23",
"phone_number": "{{caller_number}}"
}
}
}Аргументи морају имати вредност за сваки обавезни параметар, јер нико не уноси ништа на почетку позива. Вредности су ниске, бројеви или Булове вредности. Чувају се и враћају као обичан текст и агент их види, па тајне, као што су API кључеви, чувајте у заглављима везе, а не овде. Ниске могу користити ове чуваре места:
| Чувар места | Вредност |
|---|---|
{{caller_number}} | Друга особа у позиву у формату E.164, на пример +61402122887: позивалац код долазног позива, позвана особа код одлазног позива |
{{caller_number_national}} | Исти број у националном формату његове земље без размака, на пример 0402122887 |
{{agent_number}} | Број самог агента |
Начин рада:
- Захтев је исти као онај који шаљу позиви сопственог алата агента (иста крајња тачка, заглавља, формат захтева и потпис).
- Алат се покреће када позив започне и извршава се док се репродукује било који тон повезивања, увод или обавештење о снимању. Поздрав га чека до приближно 3 секунде од тог тренутка. Спорији резултат се прослеђује агенту чим стигне, за остатак позива. Код одлазног позива покреће се када се позив упути, па се извршава при сваком покушају, укључујући и оне на које нико не одговори.
- Код агента код којег позивалац први говори нема поздрава који треба чекати; агент добија резултат чим стигне.
- Резултат се даје агенту као контекст за цео позив. У упиту реците агенту како да га користи; у супротном се не чита наглас.
- Ако алат не успе или прекорачи временско ограничење, агент поздравља позиваоца као и обично и не говори ништа о томе.
- Агент и даље може сам да позове алат касније током позива.
- Покреће се за телефонске позиве, укључујући пробне позиве са контролне табле на ваш телефон, и за AI симулације, које шаљу број симулираног позиваоца вашој крајњој тачки. Не покреће се у тестовима Разговор у прегледачу нити у сесијама веб виџета, које немају број позиваоца, код позива код којих је идентификација позиваоца сакривена или код агената са корацима.
- Агент покреће највише три алата на почетку позива, све истовремено.
Помените резултат у свом упиту како би агент знао како да га користи, на пример: „Ако је претрага на почетку позива пронашла позиваоца, поздравите га именом.“
Најбоље праксе
Пишите јасне описе
Поље description помаже вештачкој интелигенцији да разуме када да користи алат. Наведите прецизно шта алат ради и када је прикладно да се користи.
Елегантно обрађујте грешке
Вратите поруке о грешци које вештачка интелигенција може да разуме: {"error": "No slots available for that date"} уместо генеричких грешака 500.
Нека одговори буду сажети
Вратите само оно што је AI потребно да настави разговор. Резултат алата остаје у разговору и поново се чита при сваком наредном потезу, па велики резултат повећава трошкове и кашњење до краја позива. Резултати дужи од 100.000 знакова скраћују се на преглед за који AI зна да је непотпун, а током веома дугог позива старији резултати могу бити одбачени (AI може поново да позове алат). Додајте параметар како би AI могао да потражи једну ставку или категорију одједном, а велики референтни садржај, као што су менији или каталози, ставите у базу знања. Пошаљите тест захтев на контролној табли приказује величину сваког резултата и упозорава када је велики.
Промишљено користите обавезна поља
Означите поља као required само када је то заиста неопходно. Вештачка интелигенција ће тражити од корисника обавезне информације пре позивања алата.
Повезано
Подстакните радње позива којима управља платформа без дефинисања крајње тачке.
Алатке којима управља платформа за HubSpot, Salesforce, Google Calendar, Google Sheets и Cal.com — није потребна крајња тачка.
Повежите MCP сервер и омогућите агенту да позива његове алатке.
Вишекратно употребљиве REST интеграције које можете повезати са агентима.
Један помоћник за верификацију веб-кука и позива алатки.