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:

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#

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

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

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

Makosa ya kawaida#

Hatua zinazofuata#