ٹول انٹیگریشن (API) بنائیں

ایک ٹول انٹیگریشن ایک دوبارہ استعمال ہونے والا HTTP اینڈ پوائنٹ ہے جسے ایک ایجنٹ کال کے دوران استعمال کر سکتا ہے۔ آپ ThunderPhone کو ٹول کی JSON-schema وضاحت اور ایک اینڈ پوائنٹ URL دیتے ہیں؛ ایجنٹ گفتگو کی بنیاد پر فیصلہ کرتا ہے کہ اسے کب کال کرنا ہے، اور ThunderPhone اپنے سرورز سے بیرونی HTTP درخواست کرتا ہے اور جواب ایجنٹ کو واپس کرتا ہے۔

یہ گائیڈ ابتدا سے انتہا تک موسم معلوم کرنے والا ٹول بنانے کا طریقہ بتاتی ہے۔

ٹول کی ساخت

دو حصے:

1. اسکیما — ایک OpenAI طرز کی فنکشن ڈیفینیشن ({type: "function", function: {name, description, parameters}}) جو LLM کو بتاتی ہے کہ ٹول کیا کرتا ہے اور اسے کون سے آرگیومنٹس درکار ہیں۔
2. اینڈ پوائنٹ — وہ URL جسے ThunderPhone کے سرورز اس وقت کال کرتے ہیں جب LLM ٹول استعمال کرنے کا فیصلہ کرتا ہے۔ درخواست 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 استعمال کریں" — یا schema کی تفصیلات سے انہیں ضمنی طور پر دریافت کر سکتا ہے۔

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 میں موسم کیسا ہے؟")۔ کال کا transcript مکمل رفت و آمد دکھاتا ہے:

{
  "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 پر موجود ہے۔

عام مسائل

اگلے مراحل