ટૂલ ઇન્ટિગ્રેશન (API) બનાવો

તમારા એજન્ટને વાતચીત દરમિયાન તમારા APIs કૉલ કરવા દો — ડેટાબેઝ શોધો, ટિકિટ બનાવો, ઓર્ડર શોધો.

ટૂલ ઇન્ટિગ્રેશન એ પુનઃઉપયોગ કરી શકાય તેવો HTTP એન્ડપૉઇન્ટ છે જેને એજન્ટ કૉલ દરમિયાન ઇન્વોક કરી શકે છે. તમે ThunderPhone ને ટૂલનું JSON-સ્કીમા વર્ણન અને એન્ડપૉઇન્ટ URL આપો છો; એજન્ટ વાતચીતના આધારે તેને ક્યારે કૉલ કરવું તે નક્કી કરે છે, અને ThunderPhone તેના સર્વર્સ પરથી આઉટબાઉન્ડ HTTP વિનંતી કરે છે તથા પ્રતિસાદ એજન્ટને પરત કરે છે.

આ માર્ગદર્શિકા વેધર-લુકઅપ ટૂલને શરૂઆતથી અંત સુધી બનાવવાની પ્રક્રિયા સમજાવે છે.

ટૂલની રચના#

બે ભાગો:

1. સ્કીમા — OpenAI-શૈલીની ફંક્શન વ્યાખ્યા ({type: "function", function: {name, description, parameters}}) જે LLM ને ટૂલ શું કરે છે અને તે કઈ દલીલો લે છે તે જણાવે છે.
2. એન્ડપૉઇન્ટ — જ્યારે LLM ટૂલનો ઉપયોગ કરવાનું નક્કી કરે ત્યારે ThunderPhone ના સર્વર્સ જે URL ને કૉલ કરે છે. વિનંતી JSON POST હોય છે, જેમાં LLM દ્વારા પસંદ કરેલી દલીલો બોડી તરીકે હોય છે.

1. એડિટર પસંદ કરો#

બંને માર્ગો સેવ કરેલી ઇન્ટિગ્રેશન બનાવે છે. ઇન્ટિગ્રેશન સેવ કર્યા પછી તેને એજન્ટ સાથે જોડો. Agents API માં લખી શકાય તેવું ઇનલાઇન tools ફીલ્ડ નથી. આ માર્ગદર્શિકા ઇન્ટિગ્રેશન્સ API માર્ગનો ઉપયોગ કરે છે.

2. ઇન્ટિગ્રેશન બનાવો#

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" }
    ]
  }'

પરત મળેલ id (એક UUID) સાચવો.

સરનામા પેરામીટરો પર format: "email" જાહેર કરો#

ઈમેઇલ સરનામું સ્વીકારતો પેરામીટર તેની સ્કીમામાં તેમ જણાવવો જોઈએ:

"email": { "type": "string", "format": "email", "description": "The caller's email address" }

format માત્ર સંકેત કરતાં વધુ છે. નિરાકરાયેલી ઈમેઇલ સ્કીમા માટે, તમારા એન્ડપોઇન્ટને કૉલ કરવામાં આવે તે પહેલાં ThunderPhone મૂલ્યની શરૂઆત અને અંતની ખાલી જગ્યાઓ દૂર કરે છે, ડોમેનને લોઅરકેસમાં ફેરવે છે, એકલાં અંગ્રેજી શબ્દો at, dot, underscore, dash, અને hyphen ને તેમના અક્ષરોમાં ફેરવે છે, અને @, ., _, અને - ની સીધી આસપાસની ખાલી જગ્યાઓ દૂર કરે છે. ટ્રાન્સક્રિપ્ટમાં પહેલેથી શાબ્દિક @ હોય કે ન હોય, આ શબ્દોનો અર્થ સમાન રહે છે: "john dot smith at gmail dot com" આમાં ફેરવાય છે john.smith@gmail.com.

અન્ય કોઈપણ આંતરિક ખાલી જગ્યાને મૌન રીતે જોડવાને બદલે નકારવામાં આવે છે. બોલાતા વિભાજક શબ્દો ફક્ત અંગ્રેજી માટે છે; બિન-અંગ્રેજી અથવા અજાણી ખાલી-જગ્યાવાળી રચનાઓ નિષ્ફળ થઈને નકારવામાં આવે છે. માન્ય આંતરરાષ્ટ્રીયકૃત ડોમેન્સ અને SMTPUTF8 લોકલ ભાગો સ્વીકારવામાં આવે છે. Punycode ઇનપુટ Punycode જ રહે છે અને Unicode ડોમેન ઇનપુટ પાર્સર નોર્મલાઇઝેશન પછી Unicode જ રહે છે, જેથી તમારી API ને કૉલર દ્વારા આપવામાં આવેલું પરંપરાગત પ્રતિનિધિત્વ મળે છે. અંતિમ મૂલ્ય અમાન્ય હોય, તો ટૂલને કૉલ કરવામાં આવતું નથી. એજન્ટને invalid_email_argument મળે છે, જે તેને કૉલર સાથે જોડણીની પુષ્ટિ કરવા અને શાબ્દિક સરનામું ફરી મોકલવા કહે છે.

છોડી દેવાયેલ વૈકલ્પિક ઈમેઇલને અસ્પૃશ્ય રાખવામાં આવે છે. પ્રોપર્ટી વૈકલ્પિક અથવા nullable હોય ત્યારે null, ખાલી સ્ટ્રિંગ, અથવા માત્ર ખાલી જગ્યાવાળી સ્ટ્રિંગને પણ અસ્પૃશ્ય રાખવામાં આવે છે; ફરજિયાત, non-nullable ઈમેઇલ માટે આ જ મૂલ્યો નકારવામાં આવે છે.

#/$defs/email અને #/definitions/email જેવા સ્થાનિક સ્કીમા રેફરન્સ, તેમજ anyOf, oneOf, અને allOf, ની ચક્ર અને ઊંડાઈ મર્યાદાઓ સાથે તપાસ કરવામાં આવે છે. બિન-સ્થાનિક અથવા ન ઉકેલી શકાય તેવું $ref જાણીતી અમલીકરણ મર્યાદા છે અને તેને કોઈ ફેરફાર વિના પસાર કરવામાં આવે છે; ઉપયોગી સ્કીમા વિનાનો ટૂલ સ્નેપશોટ ધરાવતા કૉલ સાથે પણ આવું જ થાય છે. ગેટ લાગુ કરાવવાની જરૂર હોય ત્યારે ઈમેઇલ સ્કીમાઓ સ્થાનિક રાખો.

લાગુ કરાયેલા ઈમેઇલ ફોર્મેટ વિનાના પેરામીટરોને મોડેલે ઉત્પન્ન કર્યા હોય તે જ રીતે પસાર કરવામાં આવે છે.

સમર્થિત ફોર્મેટ્સ date-time, time, date, duration, email, hostname, ipv4, ipv6, અને uuid છે; આજે માત્ર email નોર્મલાઇઝ અને લાગુ કરવામાં આવે છે.

3. એન્ડપોઇન્ટનું સેન્ડબૉક્સ-ટેસ્ટ કરો#

ઇન્ટિગ્રેશનને એજન્ટ સાથે લિંક કરતા પહેલાં, કનેક્ટિવિટીની પુષ્ટિ કરવા ThunderPhone ના સર્વર્સમાંથી સહી કરેલી વિનંતી મોકલો:

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, ...}"
}

આ ટેસ્ટ ThunderPhone ના SSRF રક્ષણોને પણ મજબૂત બનાવે છે — localhost અથવા ખાનગી IP રેન્જ માટેની વિનંતીઓ 400 code=url_not_allowed પરત આપે છે.

4. એજન્ટ સાથે ઇન્ટિગ્રેશન લિંક કરો#

તમે એજન્ટ બનાવો અથવા અપડેટ કરો ત્યારે integration_ids દ્વારા જોડો:

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-..."]
  }'

તમે એક એજન્ટ સાથે અનેક ઇન્ટિગ્રેશન લિંક કરી શકો છો. એજન્ટનો prompt નામ દ્વારા તેમનો ઉલ્લેખ કરી શકે છે — કૉલર પરિસ્થિતિ વિશે પૂછે ત્યારે get_weather નો ઉપયોગ કરો — અથવા તે સ્કીમા વર્ણનોમાંથી તેમને આડકતરી રીતે શોધી શકે છે.

5. એન્ડપૉઇન્ટ અમલમાં મૂકો#

જ્યારે એજન્ટ ટૂલ ચલાવે છે, ત્યારે ThunderPhone તમારા endpoint_url પર સહી કરેલ POST મોકલે છે:

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

તમારું સર્વર JSON સાથે પ્રતિસાદ આપે છે, જે LLM ને પાછો આપવામાં આવે છે:

{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}

LLM તે પ્રતિસાદને ગ્રહણ કરે છે અને કૉલરને માનવીય સારાંશ કહી સંભળાવે છે.

6. લૂપનું પરીક્ષણ કરો#

એજન્ટ સામે માઇક સેશન ચલાવો અને તમારા ટૂલ દ્વારા સંભાળવામાં આવતો પ્રશ્ન પૂછો ("94110 માં હવામાન કેવું છે?"). કૉલનું ટ્રાન્સક્રિપ્ટ સંપૂર્ણ રાઉન્ડ ટ્રિપ દર્શાવે છે:

{
  "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." }
  ]
}

તમે આને GET /v1/calls/{call_id}/transcript દ્વારા મેળવી શકો છો; કાચો ઇવેન્ટ સ્ટ્રીમ (દરેક એન્ટ્રીના સમય અને ઑડિયો ઑફસેટ સાથે) અહીં છે GET /v1/calls/{call_id}/history.

સામાન્ય સમસ્યાઓ#

આગળના પગલાં#