Open in
Unda ujumuishaji wa zana (API)
Ruhusu ejenti wako kuita API zako katikati ya mazungumzo — kutafuta kwenye hifadhidata, kuunda tiketi, kutafuta oda.
Muunganisho wa zana ni endpoint ya HTTP inayoweza kutumika tena ambayo ejenti anaweza kuiita wakati wa simu. Unaipa ThunderPhone maelezo ya JSON-schema ya zana pamoja na URL ya endpoint; ejenti huamua wakati wa kuiita kulingana na mazungumzo, kisha ThunderPhone hutuma ombi la HTTP linalotoka kutoka kwenye seva zake na kurejesha jibu kwa ejenti.
Mwongozo huu unaeleza jinsi ya kujenga zana ya kutafuta hali ya hewa kuanzia mwanzo hadi mwisho.
Muundo wa zana
Sehemu mbili:
- Schema — ufafanuzi wa function wa mtindo wa OpenAI
(
{type: "function", function: {name, description, parameters}}) unaoiambia LLM zana hufanya nini na inachukua hoja zipi. - Endpoint — URL ambayo seva za ThunderPhone hupigia wakati ujumuishaji unaendeshwa. Kwa zana zinazoanzishwa na ejenti, ombi ni JSON POST lenye hoja zilizochaguliwa na LLM kama mwili wa ombi.
1. Chagua kihariri
Fungua Miunganisho → API, unda au hariri muunganisho wa API, badilisha kihariri cha vigezo kuwa JSON, kisha ongeza umbizo humo.
Unda spec kwa POST /v1/integrations, au isasishe kwa
PATCH /v1/integrations/{id}.
Njia zote mbili huunda muunganisho uliohifadhiwa. Ambatisha muunganisho huo kwenye
ejenti baada ya kuuhifadhi. API ya Agents haina sehemu ya ndani ya tools
inayoweza kuandikwa. Mwongozo huu unatumia njia ya API ya miunganisho.
2. Unda ujumuishaji
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" }
]
}'Hifadhi id iliyorejeshwa (UUID). Thamani za header zinaandikwa tu: majibu
huorodhesha majina ya header pekee, na PATCH ya baadaye inaweza kutuma header bila
value ili kuhifadhi ile iliyohifadhiwa.
Tangaza format: "email" kwenye vigezo vya anwani
Kigezo kinachopokea anwani ya barua pepe kinapaswa kueleza hivyo kwenye schema yake:
"email": { "type": "string", "format": "email", "description": "The caller's email address" }format ni zaidi ya kidokezo. Kwa schema ya barua pepe iliyotatuliwa, kabla
endpoint yako haijaitwa ThunderPhone huondoa nafasi zisizohitajika kwenye thamani, hubadilisha
kikoa kuwa herufi ndogo, hubadilisha maneno huru ya Kiingereza at, dot, underscore,
dash, na hyphen kuwa herufi zake, na huondoa nafasi zilizo
moja kwa moja karibu na @, ., _, na -. Maneno hayo yana maana sawa
iwe transcript tayari ina @ halisi au la:
"john dot smith at gmail dot com" hubadilika kuwa
john.smith@gmail.com.
Nafasi nyingine yoyote ya ndani hukataliwa badala ya kuunganishwa kimya kimya.
Maneno yanayotamkwa ya vitenganishi ni ya Kiingereza pekee; miundo yenye nafasi
isiyo ya Kiingereza au isiyotambuliwa hukataliwa. Vikoa halali vya kimataifa
na sehemu za ndani za SMTPUTF8 zinakubaliwa. Ingizo la punycode hubaki punycode
na ingizo la kikoa cha Unicode hubaki Unicode baada ya usanifishaji wa kichanganuzi,
hivyo API yako hupokea uwakilishi wa kawaida uliotolewa na mpigaji simu. Ikiwa thamani
ya mwisho si halali, zana haitaitwa. Ejenti hupokea
invalid_email_argument ikiiambia
ithibitishe tahajia na mpigaji simu na kutuma tena anwani halisi.
Barua pepe ya hiari iliyoachwa hutoguswa. null, mfuatano tupu, au
mfuatano wenye nafasi pekee pia hutoguswa wakati sifa ni ya hiari
au inaruhusu null; thamani hizo hizo hukataliwa kwa barua pepe inayohitajika,
isiyoruhusu null.
Marejeleo ya ndani ya schema kama vile #/$defs/email na
#/definitions/email, pamoja na anyOf, oneOf, na allOf, hukaguliwa
kwa vikomo vya mzunguko na kina. $ref isiyo ya ndani au isiyoweza kutatuliwa ni
kikomo kinachojulikana cha utekelezaji na hupitishwa bila kubadilishwa, kama ilivyo mwito
ambao snapshot ya zana yake haina schema inayoweza kutumika. Weka schema za barua pepe
ziwe za ndani unapohitaji kizuizi kitekelezwe.
Vigezo visivyo na muundo wa barua pepe unaotekelezwa hupitishwa sawasawa na jinsi modeli ilivyovitengeneza.
Miundo inayotumika ni date-time, time, date, duration,
email, hostname, ipv4, ipv6, na uuid; ni email pekee
inayosanifishwa na kutekelezwa kwa sasa.
3. Jaribu endpoint kwenye sandbox
Kabla hujaunganisha ujumuishaji na ejenti, tuma ombi lililotiwa saini kutoka kwenye seva za ThunderPhone ili kuthibitisha muunganisho:
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_code": 200,
"reason": "OK",
"latency_ms": 187,
"response_headers": { "content-type": "application/json" },
"response_body_preview": "{\"temperature_f\": 64, ...}",
"response_truncated": false
}Jaribio hutuma vichwa vya HTTP vya ThunderPhone sawa na wito halisi wa zana, vilivyotiwa sahihi kwa siri ya webhook ya shirika lako, kwa hivyo pia hujaribu ukaguzi wako wa sahihi: X-ThunderPhone-Call-ID: test-request, X-ThunderPhone-Signature-V2 na X-ThunderPhone-Signature. body hutumwa kama JSON na kutiwa sahihi jinsi inavyotumwa; ukiwa na GET, weka hoja kwenye URL. Nambari za simu za wito hazitumwi, kwa kuwa jaribio halina wito.
Jaribio hili pia huimarisha vizuizi vya SSRF vya ThunderPhone — maombi kwa
localhost au safu za IP za faragha hurejesha 400 code=url_not_allowed.
4. Unganisha ujumuishaji na ejenti
Ambatisha kupitia integration_ids unapounda au kusasisha ejenti:
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-..."]
}'Unaweza kuunganisha ujumuishaji mwingi na ejenti mmoja. Prompt ya ejenti inaweza
kuyarejelea kwa jina — "tumia get_weather wakati mpigaji anauliza
kuhusu hali ya hewa" — au inaweza kuyagundua kwa njia isiyo ya moja kwa moja kutoka kwenye
maelezo ya schema.
5. Tekeleza endpoint
Ejenti inapoita zana, ThunderPhone hutuma POST yenye sahihi kwa
endpoint_url yako:
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"}
Seva yako hujibu kwa JSON ambayo hurejeshwa kwa LLM:
{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}LLM huchakata jibu hilo na kumwambia mpigaji muhtasari wa kawaida wa kibinadamu.
6. Jaribu mzunguko
Endesha kipindi cha maikrofoni dhidi ya ejenti na uulize swali linaloshughulikiwa na zana yako ("Hali ya hewa iko vipi katika 94110?"). Transkripti ya simu inaonyesha mzunguko kamili:
{
"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." }
]
}Unaweza kupata hii kupitia
GET /v1/calls/{call_id}/transcript;
mtiririko ghafi wa matukio (wenye muda wa kila ingizo na mipangilio ya sauti) upo kwenye
GET /v1/calls/{call_id}/history.
Katika Zeus, manukuu marefu ya simu sasa yanajumuisha mwanzo na mwisho wa simu, huku sehemu ya katikati ikigawanywa kwa kurasa inapohitajika, hivyo bado unaweza kuona jinsi simu ilivyomalizika.
Katika nyuso za orodha ya simu na uchanganuzi, ThunderPhone sasa huripoti simu za majaribio kando na trafiki halisi. Majaribio na uigaji wa Browser Talk yanaweza kutumia tena nambari halisi ya simu na yanaweza kuonekana kama simu zinazoingia, lakini hayahesabiwi katika jumla za simu za uzalishaji, alama, au vipimo vya matatizo.
Makosa ya kawaida
Ejenti haiiti zana
LLM huamua kulingana na maelezo ya zana. Ikiwa swali la mpigaji
halilingani na maelezo, modeli haitaita
zana. Fanya maelezo yawe mahususi zaidi (ongeza visawe vya kawaida na
miundo ya maneno) au itaje wazi katika prompt ya ejenti ("Wakati
mpigaji anauliza kuhusu hali ya hewa, tumia get_weather.").
Zana inarudisha data nyingi sana
Matokeo ya zana hubaki kwenye mazungumzo, na ejenti huyasoma tena katika kila zamu inayofuata, kwa hivyo matokeo makubwa huongeza gharama na ucheleweshaji kwa sehemu iliyosalia ya simu. Matokeo yenye zaidi ya vibambo 100,000 hupunguzwa kuwa muhtasari, na ejenti huambiwa kuwa hayajakamilika. Kwenye simu ndefu sana, matokeo ya zamani ya zana yanaweza kuondolewa kutoka kwenye kumbukumbu ya ejenti; inaweza kuita zana tena ikiyahitaji.
Ili kuweka matokeo madogo:
- Rudisha sehemu ambazo ejenti inahitaji pekee, si safu yako nzima.
- Ongeza kigezo ili ejenti iweze kutafuta kipengee au kategoria moja kwa wakati badala ya kuleta kila kitu.
- Weka maudhui makubwa ya marejeleo (menyu, katalogi, sera) katika msingi wa maarifa badala yake.
Tuma Ombi la Jaribio kwenye dashibodi huonyesha ukubwa wa matokeo na huonya yanapokuwa makubwa.
Muda wa kuisha
Endpointi za zana zina muda chaguomsingi wa kuisha wa sekunde 20. Weka spec.timeout
ili kuruhusu hadi sekunde 180 (tazama Zana). Kwa zana
inayosubiri mtu au kazi inayochelewa, weka spec.wait_mode kuwa
"hold": mpigaji husikia muziki wa kusubiri badala ya masasisho ya sauti, na
spec.timeout inaweza kufikia sekunde 600. Endpointi yako bado hujibu
ndani ya sekunde 180; ili kusubiri kwa muda mrefu zaidi, rudisha
{"status": "pending", "request_id": "..."} mara moja na uwasilishe
matokeo baadaye kwa kutumia
POST /v1/calls/{call_id}/tool-results.
Tazama Kusubiri kwa muda mrefu.
Uwekaji wa matoleo
Kila PATCH ya ujumuishaji huunda marekebisho mapya. Kagua
GET /v1/integrations/{id}/versions
ili kuona nani alibadilisha nini. Ukiharibu schema ya zana, unaweza
kurejesha nyuma mwenyewe kwa kutuma PATCH ya snapshot ya zamani tena.
Hatua zinazofuata
CRUD, uhamisho, historia ya matoleo.
Sarufi kamili ya JSON schema na mkataba wa endpoint iliyotiwa saini.
Tumia muundo wa sahihi ya webhook kwenye endpoint za zana.
Kagua mzunguko kamili wa kwenda na kurudi wa wito wa zana.