--- title: "Unda ujumuishaji wa zana (API)" description: "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. Dashibodi inashughulikia mahitaji mengi ya zana bila API hii: **Miunganisho → Programu** huunganisha Slack, HubSpot, Salesforce, Google Calendar, Google Sheets, na Cal.com kwa mibofyo michache ya OAuth; **Miunganisho → API** hubadilisha API yoyote ya HTTP kuwa kitendo cha ejenti (bandika amri ya cURL na kiratibu cha AI huandaa rasimu ya zana, kikiwa na Test Request iliyojengewa ndani); na **Miunganisho → MCP** huongeza seva za MCP. Tazama [Miunganisho](/sw/guides/concepts). Mwongozo huu unahusu API ya msingi iliyo chini ya kiolesura cha API. Mwongozo huu unaeleza jinsi ya kujenga zana ya kutafuta hali ya hewa kuanzia mwanzo hadi mwisho. ## Muundo wa zana Sehemu mbili: 1. **Schema** — ufafanuzi wa function wa mtindo wa OpenAI (`{type: "function", function: {name, description, parameters}}`) unaoieleza LLM zana hufanya nini na inachukua hoja zipi. 2. **Endpoint** — URL ambayo seva za ThunderPhone huiita wakati LLM inaamua kutumia zana. 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 ```bash 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). Tumia juhudi za kutosha kwenye `description` ya zana na ya kila kigezo. LLM hutumia tungo hizi wakati wa utekelezaji kuamua ikiwa na jinsi ya kuita zana. Maelezo yasiyo mahususi → miito ya zana isiyo mahususi. ### Tangaza `format: "email"` kwenye vigezo vya anwani Kigezo kinachopokea anwani ya barua pepe kinapaswa kueleza hivyo kwenye schema yake: ```json "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: ```bash 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 { "ok": true, "status": 200, "elapsed_ms": 187, "response_headers": { "content-type": "application/json" }, "response_preview": "{\"temperature_f\": 64, ...}" } ``` 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: ```bash 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: X-ThunderPhone-Call-ID: 987654321 Content-Type: application/json {"zip": "94110"} ``` Seva yako hujibu kwa JSON ambayo hurejeshwa kwa LLM: ```json {"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8} ``` LLM huchakata jibu hilo na kumwambia mpigaji muhtasari wa kawaida wa kibinadamu. Sahihi hukokotolewa kwa kutumia mwili ghafi wa ombi na `secret` ileile kama endpoint yako ya webhook. **Ithibitishe** — endpoint za zana zinapatikana kwenye intaneti na zinakabiliwa na hatari zilezile za kughushi kama webhook. Angalia [Thibitisha sahihi za webhook](/sw/guides/verify-webhook-signatures). ## 6. Jaribu mzunguko Endesha [kipindi cha maikrofoni](/api-reference/mic-sessions) dhidi ya ejenti na uulize swali linaloshughulikiwa na zana yako ("Hali ya hewa iko vipi katika 94110?"). Transkripti ya simu inaonyesha mzunguko kamili: ```json { "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`](/api-reference/calls#get-transcript); mtiririko ghafi wa matukio (wenye muda wa kila ingizo na mipangilio ya sauti) upo kwenye [`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history). ## Makosa ya kawaida 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`."). Majibu yanayozidi 6 kB hukatwa katika mwoneko wa awali wa transkripti. Rudisha sehemu zinazohitajika tu na LLM — si safu yako nzima. Endpoint za zana zina muda chaguomsingi wa kusubiri wa sekunde 10. Ikiwa unahitaji muda zaidi, shughulikia kwa njia isiyosawazishwa: rudisha `{"status": "pending", "request_id": "..."}` na onyesha matokeo kupitia mwito tofauti wa zana. Kila `PATCH` ya ujumuishaji huunda marekebisho mapya. Kagua [`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history) 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.