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

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

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

ટૂલની રચના

બે ભાગો:

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

1. સ્ટોરેજ સ્ટ્રેટેજી પસંદ કરો

આ માર્ગદર્શિકા સેવ કરેલ ઇન્ટિગ્રેશનનો માર્ગ વાપરે છે.

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) સાચવો.

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.

સામાન્ય ભૂલો

આગામી પગલાં