ThunderPhone v3 اب لائیو ہے۔سیلف سرو، قیمت 2¢ فی منٹ سے شروع۔اعلان پڑھیں

Developer cookbook

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

اپنے ایجنٹ کو گفتگو کے دوران آپ کے APIs کال کرنے دیں — ڈیٹابیس میں تلاش کریں، ٹکٹ بنائیں، آرڈر دیکھیں۔

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

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

ٹول کی ساخت

دو حصے:

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

ای میل ایڈریس وصول کرنے والے پیرامیٹر کو اپنے schema میں یہ واضح کرنا چاہیے:

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

format صرف ایک اشارہ نہیں ہے۔ حل شدہ ای میل schema کے لیے، آپ کے endpoint کو کال کرنے سے پہلے ThunderPhone قدر کے آغاز اور اختتام کی خالی جگہ ہٹاتا ہے، ڈومین کو چھوٹے حروف میں تبدیل کرتا ہے، الگ موجود انگریزی الفاظ at، dot، underscore، dash اور hyphen کو ان کے متعلقہ حروف میں بدلتا ہے، اور @، .، _ اور - کے عین اطراف کی خالی جگہ ہٹا دیتا ہے۔ ان الفاظ کا مطلب یکساں رہتا ہے، چاہے transcript میں پہلے سے لفظی @ موجود ہو یا نہ ہو: "john dot smith at gmail dot com" تبدیل ہو کر john.smith@gmail.com بن جاتا ہے۔

کسی بھی دوسری اندرونی خالی جگہ کو خاموشی سے جوڑنے کے بجائے مسترد کر دیا جاتا ہے۔ بولے گئے جداکار الفاظ صرف انگریزی کے لیے ہیں؛ غیر انگریزی یا غیر شناخت شدہ فاصلے والے فارمز ناکامی کی صورت میں بند رہتے ہیں۔ درست بین الاقوامی ڈومینز اور SMTPUTF8 مقامی حصے قبول کیے جاتے ہیں۔ parser کی نارملائزیشن کے بعد Punycode ان پٹ Punycode ہی رہتا ہے اور Unicode ڈومین ان پٹ Unicode ہی رہتا ہے، اس لیے آپ کی API کو کالر کی فراہم کردہ روایتی نمائندگی موصول ہوتی ہے۔ اگر حتمی قدر غلط ہو تو ٹول کو کال نہیں کیا جاتا۔ ایجنٹ کو invalid_email_argument موصول ہوتا ہے، جو اسے کالر سے ہجے کی تصدیق کرنے اور لفظی ایڈریس دوبارہ بھیجنے کی ہدایت دیتا ہے۔

چھوڑی گئی اختیاری ای میل میں کوئی تبدیلی نہیں کی جاتی۔ اگر پراپرٹی اختیاری یا nullable ہو تو null، خالی اسٹرنگ، یا صرف خالی جگہوں والی اسٹرنگ میں بھی کوئی تبدیلی نہیں کی جاتی؛ لازمی، non-nullable ای میل کے لیے یہی قدریں مسترد کر دی جاتی ہیں۔

مقامی schema حوالہ جات، مثلاً #/$defs/email اور #/definitions/email، نیز anyOf، oneOf اور allOf کو cycle اور گہرائی کی حدود کے ساتھ جانچا جاتا ہے۔ غیر مقامی یا ناقابل حل $ref ایک معلوم نفاذی حد ہے اور اسے بغیر تبدیلی کے آگے بھیج دیا جاتا ہے، بالکل ایسے ہی جیسے وہ کال جس کے ٹول snapshot میں قابل استعمال schema نہ ہو۔ جب آپ کو اس گیٹ کے اطلاق کی ضرورت ہو تو ای میل schemas کو مقامی رکھیں۔

نافذ شدہ ای میل format کے بغیر پیرامیٹرز کو عین اسی طرح آگے بھیجا جاتا ہے جیسے ماڈل نے انہیں تیار کیا ہو۔

معاون formats یہ ہیں: date-time، time، date، duration، email، hostname، ipv4، ipv6 اور uuid؛ آج صرف email کو نارملائز اور نافذ کیا جاتا ہے۔

3. endpoint کا sandbox ٹیسٹ کریں

انٹیگریشن کو کسی ایجنٹ سے لنک کرنے سے پہلے، کنیکٹیویٹی کی تصدیق کے لیے 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 استعمال کریں" — یا schema کی وضاحتوں سے انہیں بالواسطہ طور پر دریافت کر سکتا ہے۔

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 حروف سے زیادہ کے نتیجے کو مختصر پیش منظر تک محدود کر دیا جاتا ہے، اور ایجنٹ کو بتایا جاتا ہے کہ یہ نامکمل ہے۔ بہت طویل کال میں، پرانے ٹول کے نتائج ایجنٹ کی یادداشت سے ہٹائے جا سکتے ہیں؛ اگر اسے ان کی ضرورت ہو تو وہ ٹول کو دوبارہ کال کر سکتا ہے۔

نتائج کو مختصر رکھنے کے لیے:

  • صرف وہ فیلڈز واپس کریں جن کی ایجنٹ کو ضرورت ہے، پوری قطار نہیں۔
  • ایک parameter شامل کریں تاکہ ایجنٹ سب کچھ حاصل کرنے کے بجائے ایک وقت میں ایک آئٹم یا زمرہ تلاش کر سکے۔
  • بڑا حوالہ جاتی مواد (مینو، کیٹلاگ، پالیسیاں) اس کے بجائے نالج بیس میں رکھیں۔

ڈیش بورڈ میں ٹیسٹ ریکویسٹ بھیجیں یہ دکھاتا ہے کہ نتیجہ کتنا بڑا ہے اور بڑا ہونے پر تنبیہ کرتا ہے۔

ٹائم آؤٹس

ٹول اینڈ پوائنٹس کا ڈیفالٹ ٹائم آؤٹ 20 سیکنڈ ہے۔ 180 سیکنڈ تک کی اجازت دینے کے لیے spec.timeout سیٹ کریں (ٹولز دیکھیں)۔ ایسے ٹول کے لیے جو کسی شخص یا سست جاب کا انتظار کرتا ہے، spec.wait_mode کو "hold" پر سیٹ کریں: بولی جانے والی اپ ڈیٹس کے بجائے کالر کو ہولڈ میوزک سنائی دے گا، اور spec.timeout 600 سیکنڈ تک ہو سکتا ہے۔ آپ کا اینڈ پوائنٹ پھر بھی 180 سیکنڈ کے اندر جواب دیتا ہے؛ زیادہ دیر انتظار کرنے کے لیے، فوراً {"status": "pending", "request_id": "..."} واپس کریں اور نتیجہ بعد میں POST /v1/calls/{call_id}/tool-results کے ذریعے فراہم کریں۔ طویل انتظار دیکھیں۔

ورژننگ

ہر انٹیگریشن PATCH ایک نیا revision بناتا ہے۔ یہ دیکھنے کے لیے کہ کس نے کیا تبدیل کیا، GET /v1/integrations/{id}/versions کا جائزہ لیں۔ اگر آپ کسی ٹول کا schema خراب کر دیں، تو آپ پرانے snapshot کو دوبارہ PATCH کر کے دستی طور پر واپس جا سکتے ہیں۔


اگلے مراحل