ThunderPhone v3 હવે લાઇવ છે.સેલ્ફ-સર્વ, 2¢/મિનિટથી.જાહેરાત વાંચો

Developer cookbook

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

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

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

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

ટૂલની રચના

બે ભાગો:

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

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

ડેશબોર્ડ

કનેક્શન્સ → APIs ખોલો, API કનેક્શન બનાવો અથવા સંપાદિત કરો, પેરામીટર એડિટરને JSON પર બદલો અને ત્યાં ફોર્મેટ ઉમેરો.

ઇન્ટિગ્રેશન્સ API

POST /v1/integrations સાથે સ્પેસિફિકેશન બનાવો અથવા તેને PATCH /v1/integrations/{id} સાથે અપડેટ કરો.

બંને માર્ગો સેવ કરેલી ઇન્ટિગ્રેશન બનાવે છે. ઇન્ટિગ્રેશન સેવ કર્યા પછી તેને એજન્ટ સાથે જોડો. 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) સાચવો. હેડર મૂલ્યો માત્ર લખવા માટે છે: પ્રતિસાદોમાં ફક્ત હેડર નામો સૂચિબદ્ધ થાય છે, અને પછીનો PATCH સંગ્રહિત મૂલ્ય જાળવી રાખવા માટે value વગર હેડર મોકલી શકે છે.

સરનામા પેરામીટરો પર 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" }
  }'
Response
{
  "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
}

આ ટેસ્ટમાં લાઇવ ટૂલ કૉલ જેવા જ ThunderPhone હેડર્સ હોય છે અને તે તમારી સંસ્થાના વેબહૂક સિક્રેટથી સહી કરાયેલો હોય છે, તેથી તે તમારી સિગ્નેચર ચકાસણી પણ પરીક્ષે છે: X-ThunderPhone-Call-ID: test-request, X-ThunderPhone-Signature-V2 અને X-ThunderPhone-Signature. body JSON તરીકે મોકલવામાં આવે છે અને જેમ મોકલવામાં આવે છે તેમ સહી કરવામાં આવે છે; GET સાથે, આર્ગ્યુમેન્ટ્સ URLમાં મૂકો. કૉલના ફોન નંબર મોકલવામાં આવતા નથી, કારણ કે ટેસ્ટમાં કોઈ કૉલ હોતો નથી.

આ ટેસ્ટ 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-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"}

તમારું સર્વર 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.

Zeus માં, લાંબા કૉલ ટ્રાન્સક્રિપ્ટમાં હવે કૉલની શરૂઆત અને અંત સામેલ હોય છે, અને જરૂર પડે ત્યારે વચ્ચેનો ભાગ પેજમાં વિભાજિત થાય છે, જેથી તમે કૉલ કેવી રીતે પૂર્ણ થયો તે હજી પણ જોઈ શકો.

કૉલ-લિસ્ટિંગ અને એનાલિટિક્સ સપાટીઓમાં, ThunderPhone હવે ટેસ્ટ કૉલને વાસ્તવિક ટ્રાફિકથી અલગ રીતે રિપોર્ટ કરે છે. Browser Talk ટેસ્ટ અને સિમ્યુલેશન વાસ્તવિક ફોન નંબરનો ફરીથી ઉપયોગ કરી શકે છે અને ઇનબાઉન્ડ જેવા દેખાઈ શકે છે, પરંતુ તેઓ પ્રોડક્શન કૉલના કુલ, ગ્રેડ અથવા સમસ્યા મેટ્રિક્સમાં ગણાતા નથી.

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

એજન્ટ ક્યારેય ટૂલ ચલાવતો નથી

LLM ટૂલના વર્ણનના આધારે નિર્ણય લે છે. જો કૉલરનો પ્રશ્ન વર્ણન સાથે મેળ ખાતો ન હોય, તો મોડેલ ટૂલ ચલાવશે નહીં. વર્ણન વધુ ચોક્કસ બનાવો (સામાન્ય સમાનાર્થી અને શબ્દપ્રયોગ ઉમેરો) અથવા એજન્ટના prompt માં તેનો સ્પષ્ટ ઉલ્લેખ કરો ("જ્યારે કૉલર હવામાન વિશે પૂછે, ત્યારે get_weather નો ઉપયોગ કરો.").

ટૂલ ખૂબ વધુ ડેટા પરત કરે છે

ટૂલનું પરિણામ વાતચીતમાં રહે છે અને એજન્ટ તેને દરેક પછીના વારમાં ફરી વાંચે છે, તેથી મોટું પરિણામ કૉલના બાકીના ભાગમાં ખર્ચ અને વિલંબ ઉમેરે છે. 100,000 અક્ષરોથી વધુનું પરિણામ પૂર્વાવલોકન સુધી ટૂંકાવવામાં આવે છે અને એજન્ટને જણાવવામાં આવે છે કે તે અધૂરું છે. ખૂબ લાંબા કૉલમાં, જૂનાં ટૂલ પરિણામો એજન્ટની મેમરીમાંથી દૂર થઈ શકે છે; જરૂર હોય તો એજન્ટ ટૂલને ફરી કૉલ કરી શકે છે.

પરિણામો નાના રાખવા માટે:

  • એજન્ટને જરૂરી હોય તેવા ફીલ્ડ્સ જ પરત કરો, તમારી સંપૂર્ણ પંક્તિ નહીં.
  • પેરામીટર ઉમેરો જેથી એજન્ટ બધું મેળવવાને બદલે એક સમયે એક આઇટમ અથવા શ્રેણી શોધી શકે.
  • મોટી સંદર્ભ સામગ્રી (મેનુ, કેટલોગ, નીતિઓ) તેના બદલે જ્ઞાન આધારમાં મૂકો.

ડૅશબોર્ડમાં ટેસ્ટ વિનંતી મોકલો દર્શાવે છે કે પરિણામ કેટલું મોટું છે અને તે મોટું હોય ત્યારે ચેતવણી આપે છે.

સમયસમાપ્તિઓ

ટૂલ એન્ડપોઇન્ટ્સમાં 20 સેકન્ડની ડિફૉલ્ટ સમયમર્યાદા હોય છે. 180 સેકન્ડ સુધી મંજૂરી આપવા માટે spec.timeout સેટ કરો (ટૂલ્સ જુઓ). વ્યક્તિ અથવા ધીમા કાર્યની રાહ જોતી ટૂલ માટે spec.wait_mode ને "hold" પર સેટ કરો: કૉલરને બોલીને અપડેટ આપવાને બદલે હોલ્ડ સંગીત સંભળાશે, અને spec.timeout 600 સેકન્ડ સુધી જઈ શકે છે. તમારું એન્ડપોઇન્ટ હજી પણ 180 સેકન્ડની અંદર જવાબ આપે છે; વધુ સમય રાહ જોવા માટે, તરત {"status": "pending", "request_id": "..."} પરત કરો અને પછી POST /v1/calls/{call_id}/tool-results દ્વારા પરિણામ પહોંચાડો. લાંબી રાહ જુઓ.

આવૃત્તિ વ્યવસ્થાપન

દરેક ઇન્ટિગ્રેશન PATCH નવી રિવિઝન બનાવે છે. કોણે શું બદલ્યું તે જોવા માટે GET /v1/integrations/{id}/versions તપાસો. જો તમે ટૂલની સ્કીમા તોડી નાખો, તો તમે જૂના સ્નેપશૉટને ફરી PATCH કરીને મેન્યુઅલી રોલ બૅક કરી શકો છો.


આગળના પગલાં