اے آئی ایجنٹس کے لیے APIs کیسے ڈیزائن کریں۔

API کو انسانی ڈویلپرز کے لیے ڈیزائن کیا گیا ہے۔ لوگ جانتے ہیں کہ دستاویزات کو کیسے پڑھنا ہے، اختتامی نقطوں کے پیچھے کی نیت کا اندازہ لگانا ہے، اور جب کوئی غیر متوقع واقعہ پیش آتا ہے تو کنارے کے معاملات کو ہینڈل کرنا ہے۔

AI ایجنٹوں کے پاس وہ سیاق و سباق اور سمجھ نہیں ہے۔

AI ایجنٹس آپ کے API کو اسکیموں، مثالوں، بے ترتیب ڈیٹا اور ریئل ٹائم جوابات کے ذریعے سمجھتے ہیں۔ جب کوئی عمل یا طریقہ مبہم یا متضاد ہوتا ہے، تو ماڈل ‘سوچنے’ کو توقف کیے بغیر خالی جگہوں کو پُر کرتا ہے۔

پیداواری ماحول میں، ان اندازوں کے نتیجے میں بلاکنگ، طوفانوں کی دوبارہ کوشش، نقلی ضمنی اثرات، یا ورک فلو میں خلل پڑ سکتا ہے۔

یہی وجہ ہے کہ ایسے APIs جو انسانوں کے لیے بالکل ٹھیک ہیں اکثر AI ایجنٹوں کا استعمال کرتے وقت ناکام ہو جاتے ہیں۔ مسئلہ یہ نہیں ہے کہ ایجنٹ کافی ہوشیار نہیں ہیں۔ APIs کو اکثر ایجنٹ/مشین صارفین کے لیے ڈیزائن نہیں کیا جاتا ہے جنہیں انسانی مداخلت کے بغیر منصوبے بنانے، ٹولز کال کرنے اور غلطیوں سے بازیافت کرنے کی ضرورت ہوتی ہے۔

اس گائیڈ میں، آپ ایک API ڈیزائن کرنے کا طریقہ سیکھیں گے جسے ایجنٹ قابل اعتماد طریقے سے استعمال کر سکیں۔ ہم تین عملی نظریات کے ساتھ بحث کی رہنمائی کریں گے:

فیصلہ کن اقدام: ایک ہی آدانوں اور ریاستوں کو متوقع نتائج اور شکلیں پیدا کرنی چاہئیں۔
طاقتور سکیما: ایک مکمل، وضاحتی، اور قابل امتحان معاہدہ۔
API باؤنڈری کے ارد گرد گارڈریلز: غیر محفوظ خودمختاری کو روکنے کے لیے تصدیق، تصدیق، اور محفوظ ڈیفالٹس۔

اس مضمون کا مقصد "AI-based” APIs بنانا نہیں ہے، بلکہ AI-based APIs بنانا ہے۔ واضح، سخت، اور قابل اعتماد، یہ سچ ہے یہاں تک کہ اگر کال کرنے والا کوئی ایجنٹ نہیں ہے بلکہ ایک ساتھی ڈویلپر ہے جو مختلف ٹولز کا استعمال کرتا ہے۔

انڈیکس

شرطیں

اس گائیڈ کو پڑھنے سے پہلے، درج ذیل کو جاننا مفید ہو گا:

HTTP API اور REST تصورات کی بنیادی تفہیم
JSON اور API کی درخواست/جواب کے نمونوں کا علم۔
عام API تصورات کی تفہیم، بشمول تصدیق، صفحہ بندی، اور دوبارہ کوششیں۔

کیوں "ڈویلپرز کے لیے کافی اچھا” ایجنٹوں کے لیے کافی اچھا نہیں ہے۔

انسانی ڈویلپر خاموش، سیاق و سباق کا علم لاتے ہیں۔ وہ سلیک تھریڈز پڑھتے ہیں، وہ بلاگ پوسٹس پڑھتے ہیں، اور انہیں احساس ہوتا ہے، "اس 404 کا عام طور پر مطلب ہے کہ آپ اپنی ورک اسپیس ID بھول گئے ہیں۔”

ایجنٹوں کو زیادہ تر تفصیلات، مثالوں اور حتمی جواب کے باڈی میں سب کچھ ملتا ہے۔

خلا خود کو پیشین گوئی کے طریقوں سے ظاہر کرتا ہے۔

مبہم معنی: غلط اختتامی نقطہ یا غلط پیرامیٹر مجموعہ۔
غیر دستاویزی شاخیں: ماڈل ایک فیلڈ ایجاد کرتا ہے یا اختیاری عمل کو غلط پڑھتا ہے۔
متضاد خرابی کا باڈی: یہ یا تو دوبارہ کوشش ہے جو نہیں ہونی چاہیے، یا دوبارہ کوشش نہیں ہو رہی ہے جب ایسا کرنا محفوظ ہو۔
غیر مقلد "کام کرتا ہے” اختتامی نقطہ: ڈپلیکیٹ چارجز، ڈپلیکیٹ ٹکٹ، ڈپلیکیٹ ای میلز۔

صنعت کی تفسیر اور پریکٹیشنر گائیڈز ایک ہی نکتے پر اکٹھے ہوتے ہیں۔ ایجنٹ API صارفین کی ایک بڑی کلاس بن رہے ہیں، اور مشین کی پڑھنے کی اہلیت اتنی ہی اہم ہے جتنی ڈویلپر کے تجربے کی ہے۔

اس دستاویز کے آخر میں درج وسائل میں ایجنٹوں، نئے ٹول پروٹوکولز، اور ٹریفک کے نمونوں کے بارے میں معلومات کے ذریعہ OpenAPI کے بارے میں بحث کی مثالیں دیکھیں جو انسانی کلائنٹس سے مختلف ہیں۔

اصول 1: تعییناتی رویہ

ایجنٹ کے عزم کا مطلب یہ نہیں ہے کہ یہ "ہمیشہ ایک ہی JSON کو ہمیشہ کے لیے واپس کرے گا”۔ اس کا مطلب ہے: ایک ہی درخواست اور ایک ہی سرور سائیڈ حالت کو دیکھتے ہوئے، API اس طرح برتاؤ کرتا ہے جس کا ایجنٹ ماڈل بنا سکتا ہے۔ اگر ریاست بدلتی ہے تو اسے واضح طور پر بیان کریں۔

پوشیدہ جادو پر واضح حالت کو ترجیح دیں۔

ایجنٹ "بعض اوقات سرور اندرونی پرچم کی بنیاد پر X کرتا ہے” کے ساتھ جدوجہد کرتے ہیں۔ جہاں انسان پروڈکٹ کاپی سے نیت کا اندازہ لگاتے ہیں، ایجنٹ پیٹرن سے اندازہ لگاتے ہیں۔ جب یہ نمونے بڑھتے ہیں تو خود مختاری ٹوٹ جاتی ہے۔

عملی عادات:

ماڈل لائف سائیکل کو واضح طور پر بیان کریں (draft → submitted → approved) ایک سنگل کو اوور لوڈ کرنے کے بجائے status غیر دستاویزی امتزاج کے ساتھ فیلڈز۔
تبدیلی کے بعد جو کچھ بدلا ہے وہ لوٹاتا ہے (اپ ڈیٹ کردہ وسائل، منسلک ID، اگلی اجازت شدہ کارروائی)۔
خودکار نفاذ سے گریز کریں (غلط شماروں کو خود بخود درست کرنا، نامعلوم فیلڈز کو خود بخود حذف کرنا) جب تک کہ دستاویزی اور سگنل نہ ہوں۔

لکھنے کو محفوظ بنانا: ادراک اور ارادے کی چابیاں

تمام اینڈ پوائنٹس کے لیے، بشمول بلنگ، میسجنگ، پروویژننگ انفراسٹرکچر وغیرہ۔ میں کچھ ایسا کر رہا ہوں جسے کالعدم نہیں کیا جا سکتافرض کریں کہ دوہری گذارشات ہوتی ہیں۔

تخلیق کی طرح کی کارروائیوں کے لیے آئیڈیمپوٹینٹ کیز (ہیڈر یا باڈی) کو سپورٹ کرتا ہے۔
واضح HTTP سیمنٹکس استعمال کریں۔ POST بنائیں PUT جہاں مناسب ہو تبدیل کریں؛ PATCH جزوی اپ ڈیٹس کے لیے، دستاویز کریں کہ تکرار کا کیا مطلب ہے۔
اگر اوورلیپ ممکن ہو تو کلائنٹ ریفرل کے ذریعے ریفرل پاتھ فراہم کریں تاکہ ایجنٹ ایڈجسٹمنٹ کر سکیں۔

صفحہ بندی اور چھانٹنا: ایک پیٹرن، ہر جگہ

ایجنٹ لوپ. اگر تمام وسائل کو مختلف طریقے سے صفحہ بندی کیا جاتا ہے، تو ماڈل حکمت عملیوں کو ملا دیتا ہے۔

اس مسئلے کو حل کرنے کے لیے، فی API سطح پر ایک صفحہ بندی کا انداز (کرسر بمقابلہ آفسیٹ) منتخب کریں اور اس پر قائم رہیں۔

یہ ہمیشہ واپس آتا ہے یا ایک مستحکم ترتیب کی ضرورت ہوتی ہے۔ sort واضح طور پر۔ آپ کو بھی شامل کرنا چاہئے۔ next مسلسل لفافے میں لنک یا کرسر۔

ٹائم آؤٹ، جزوی کامیابی، اور غیر مطابقت پذیر آپریشنز

ایجنٹوں کو نفرت ہے "جس نے شاید کام کیا۔” ایک طویل عرصے سے چلنے والے کام کو: واضح طور پر غیر مطابقت پذیر:

202 Accepted + جاب آئی ڈی + پولنگ یا ویب ہک۔
ٹرمینل کی حالت صاف کریں: succeeded، failed، canceledناکامی کے لیے ساختی خرابی کی تفصیلات پر مشتمل ہے۔

اصول 2: مضبوط اسکیما

اگر عزم رویے کے بارے میں ہے، تو اسکیما مواصلات کے بارے میں ہیں۔ ایجنٹوں کے لیے، OpenAPI (یا مساوی) رن ٹائم انٹرفیس کا حصہ ہے، کاغذی کارروائی کا نہیں۔

OpenAPI کو ایک معاہدے کے طور پر سمجھیں، نہ کہ ایک یادگار۔

ایک قیاس جو پیداوار میں تاخیر کرتا ہے وہ بغیر کسی قیاس سے بدتر ہے۔ یہ ایجنٹوں کو اعتماد کے ساتھ غلط ہونے کی تربیت دیتا ہے۔ ٹیمیں تیزی سے OpenAPI کو ایک مستند معاہدہ کے طور پر دیکھ رہی ہیں اور CI اور کنارے پر اس کے خلاف درخواستوں/جوابات کی توثیق کر رہی ہیں۔

ایجنٹ کے موافق OpenAPI کے لیے کم از کم معیار یہ ہیں:

تمام کاموں کے لیے summary اور description وضاحت جب نہ صرف آپ اسے استعمال کرتے ہیں۔ کیا یہ واپس آتا ہے۔
تمام درخواست جسم کی خصوصیات میں شامل ہیں description اور یہ حقیقت پسندانہ ہے۔ example قدر
تمام جوابات دستاویزی ہیں، بشمول مستحکم JSON فارمیٹ میں 4xx/5xx۔

فطری زبان میں ارادے کو درست طریقے سے بیان کریں۔

ایجنٹ لفظوں سے ناراض نہیں ہوتے۔ وہ مبہم فعل سے الجھ جاتے ہیں۔

بجائے:

’’میں حکم لیتا ہوں۔‘‘

ترجیح دیں:

"تصدیق شدہ فروخت کنندگان کے آرڈرز کی فہرست۔ فلٹرنگ کی حمایت کرتا ہے۔ status اور ٹائم ونڈو ہے۔ created_at. زیادہ سے زیادہ واپسی limit آئٹم استعمال کریں cursor اگلے صفحے کے لیے۔”

یہ اس سے مطابقت رکھتا ہے جسے متعدد رہنما کہتے ہیں۔ حالات سے متعلق آگاہی یا خود وضاحتی API: اسکیماس نہ صرف اقسام بلکہ معنوی ارادے کو بھی پہنچاتے ہیں۔

مثال معاہدے کا حصہ ہے۔

آپ کو فی اختتامی نقطہ کے ساتھ ایک مثال ہیپی پاتھ، معیاری ایرر آبجیکٹ کے ساتھ کم از کم ایک مثال کی توثیق کی غلطی (400)، اور رویے کو تبدیل کرتے وقت اختیاری فیلڈز کی مثال فراہم کرنی چاہیے۔

اس سے ‘شکل کا وہم’ کم ہو جاتا ہے، جہاں ماڈل فیلڈ کے ناموں یا اوورلیپ کا اندازہ لگاتا ہے، مثال کے طور پر۔

JSON اسکیما سختی ٹول کال اسٹیک کو سپورٹ کرتی ہے۔

اگر آپ کا ایجنٹ فنکشن کالز/سٹرکچرڈ آؤٹ پٹ استعمال کرتا ہے تو اپنے اسکیما کو سخت کریں۔

ترجیح دیتے ہیں enum چھوٹے بند سیٹوں کے لیے۔
فیلڈ ڈسپلے required ایماندار ہونا
استعمال کریں format (uuid، date-time) جہاں یہ حقیقی ہے۔
بچنا additionalProperties: true سیکورٹی کے لحاظ سے حساس پے لوڈز کے لیے جہاں سخت تصدیق کی ضرورت ہے۔

چیزوں کو مستقل طور پر نام دیں۔

userId ایک اختتامی نقطہ سے user_id دوسرا انسانی جھنجھلاہٹ اور ایجنٹ کا جال ہے۔ اپنے قوانین کا انتخاب کریں اور انہیں نافذ کریں۔

اصول 3: API حدود کے ارد گرد گارڈریلز

خود مختاری غلطیوں کو بڑھاتی ہے۔ گارڈریلز حادثات کی بجائے "افوہ” کو مسدود درخواستوں میں بدل دیتے ہیں۔

اختیارات کی گرانٹس تنگ اور واضح ہونی چاہئیں۔

ایجنٹوں کے پاس درج ذیل اسناد کا ہونا ضروری ہے: کم از کم استحقاق. مثال کے طور پر، واضح طور پر دستاویزی تازہ کاری کے ساتھ مختصر مدت کے ٹوکن استعمال کریں۔ ایک رینج کا استعمال کریں جو اصل کام کا نقشہ بناتا ہے (orders:read بڑا orders:write)۔ اور ایسے بہاؤ سے بچیں جو فرض کریں کہ کوئی انسان اسے حل کر سکتا ہے (CAPTCHA) یا اس پر کلک کر سکتا ہے (درمیان میں ای میل لنک)، یا یہ کہ آپ اسے انسانی مصروفیت والے ٹول سے الگ کر سکتے ہیں۔

سخت، فیل لاؤڈ، سٹرکچرڈ تصدیق

کنارے پر خراب ان پٹ کو مسترد کرنے کے لیے مستحکم کا استعمال کریں۔ error_code قدر (مشین کے ذریعے قابل عمل)، انسانی پڑھنے کے قابل message (لاگز اور UI کے لیے)، اختیاری field یا JSON پوائنٹر اور آپ کے مسئلے کے لیے آپ کے انتخاب doc_url دستاویز سے لنک کریں۔

یہ متعدد پریکٹیشنر مضامین سے رہنمائی کے مطابق ہے۔ مبہم 500s اور عام غلطیاں وہ ہیں جہاں خود مختار کلائنٹس سرپل ہوتے ہیں۔

RFC 7807 مسئلہ کی تفصیلات (application/problem+json) HTTP APIs کے لیے ایک اچھا اور وسیع پیمانے پر سمجھا جانے والا پیٹرن ہے، اور سٹرکچرڈ لفافے کے ایجنٹ اسے مستقل طور پر پارس کر سکتے ہیں۔

‘دنیا کو تبدیل کریں’ سے ‘دنیا کو پڑھیں’ کو الگ کریں۔

زیادہ اثر انداز ہونے والے آپریشنز (ریفنڈ، ڈیلیٹ، ٹرانسفر) کے لیے، ہم دو قدمی پیٹرن استعمال کرنے کی تجویز کرتے ہیں جہاں آپ پہلے ایک ارادہ بناتے ہیں اور پھر اس پر عمل درآمد کی تصدیق کرتے ہیں۔

متبادل کے طور پر، آپ ایک ٹیسٹ رن استفسار پیرامیٹر/ڈیڈیکیٹڈ اینڈ پوائنٹ استعمال کر سکتے ہیں جو بغیر ارتکاب کے توثیق کرتا ہے۔

اس بات کو بھی ذہن میں رکھیں کہ ریٹ کی حدیں اور کوٹہ برسٹی ایجنٹ کے رویے اور خود مختار لوپس کے مطابق انسانی ٹریفک کی حوصلہ شکنی کر سکتے ہیں۔

مشاہدہ ایک مصنوعات کی خصوصیت ہے۔

ارتباطی IDs کو ریکارڈ کریں، انہیں محفوظ جوابات میں نشان زد کریں، اور دوبارہ کوشش کرنے کی نگرانی کریں۔ ایک ایجنٹ 409 کو "مستقل دوبارہ کوشش” کے طور پر غلط پڑھتا ہے جس کے نتیجے میں سسٹم کے خلاف پرس کے حملے سے انکار ہوتا ہے۔

پیٹرن جو APIs اور ایجنٹ رن ٹائمز کو جوڑتے ہیں۔

ورک فلو دستاویزی: تسلسل، نہ صرف اختتامی نقطہ

ایجنٹ اس وقت بہتر ہوتے ہیں جب وہ کسی ترکیب پر عمل کر سکتے ہیں۔ عام ترتیب کو دستاویز کریں ("کسٹمر بنائیں → ادائیگی کا طریقہ شامل کریں → بل”) اور اگر آپ کے پروڈکٹ کی پیچیدگی اس کا جواز پیش کرتی ہے تو ملٹی سٹیپ API فلوز (جیسے Arazzo) کے معیارات پر غور کریں۔

ہائپر میڈیا اور "اگلا قدم”

ممکنہ اگلی کارروائیوں کے لنکس شامل کریں (جیسے صفحہ بندی) nextیا متعلقہ وسائل) بہتری کو کم کریں۔ یہ وہی جذبہ ہے جو HATEOAS ہے۔ جواب سرگوشی کرتا ہے کہ ماڈل کو URL کا اندازہ لگانے پر مجبور کرنے کے بجائے وہ آگے کیا کر سکتا ہے۔

ٹول سینٹرڈ سطح (جیسے MCP)

پروٹوکول جیسے ماڈل سیاق و سباق پروٹوکول (MCP) ایک اسکیما کے ذریعے کیوریٹڈ فنکشنلٹی ("ٹولز”) کو بے نقاب کرنے کے طریقے کے طور پر توجہ حاصل کر رہے ہیں جس سے ایجنٹ براہ راست پابند ہو سکتے ہیں۔

ایک عام عملی نمونہ تمام مائیکرو اینڈ پوائنٹس کو ٹولز کے طور پر پھینکنا نہیں ہے، بلکہ بنیادی REST API کو سخت اور صاف رکھتے ہوئے صارف کے نتائج کے مطابق بنائے گئے موٹے دانے والے ٹولز کو بے نقاب کرنا ہے۔

MCP اچھے API ڈیزائن کا متبادل نہیں ہے۔ فارورڈنگ اور بازیافت پرت۔ گندے API پر ایک پتلی چادر ڈالنا اب بھی آپ کو گندا نظام چھوڑ دیتا ہے۔ عوامی ہونا صرف آپ کو تیزی سے ناکام ہونے کا سبب بنے گا۔

تلاش کے لیے میٹا ڈیٹا (`llms.txt` اور دوست)

کچھ ٹیمیں پوسٹ کرتی ہیں۔ /llms.txt یا آرٹیکل سائٹس کے لیے اسی طرح کی ہلکی پھلکی سرچ فائل۔ اسے ایک اختیاری نشانی کے طور پر سمجھیں، نہ کہ OpenAPI کا متبادل۔

ماحولیاتی نظام کو اپنانا اب بھی تیار ہو رہا ہے، لیکن بنیادی خیال درست ہے۔ مقصد یہ ہے کہ معیاری، مشین سے پڑھنے کے قابل وضاحتیں تلاش کرنا آسان ہو۔

پہلے/بعد میں عملی

کمزور پیٹرن (ایجنٹ مخالف)

POST /do-stuff

جواب 200 OK:

{ "ok": true }

مسائل: کوئی آئیڈیمپوٹینسی نہیں، کوئی ساختی خامیاں نہیں، کوئی ہستی IDs نہیں، پولنگ کا کوئی طریقہ نہیں، ایجنٹ کو اندازہ لگانا ہوگا کہ "اوکے” کا مطلب ہے "تخلیق شدہ” یا "ڈپلیکیٹ نظر انداز”۔

زیادہ طاقتور پیٹرن (ایجنٹ دوستانہ)

POST /v1/invoices
Idempotency-Key: 7b3c-...

جواب 201 Created:

{
  "invoice": {
    "id": "inv_9Qz",
    "status": "draft",
    "total": { "amount": "120.00", "currency": "USD" }
  },
  "links": {
    "finalize": "/v1/invoices/inv_9Qz/finalize"
  }
}

تنازعہ کا جواب 409 Conflict مسئلہ کی تفصیلات پر مشتمل ہے:

{
  "type": "https://api.example.com/problems/duplicate-idempotency-key",
  "title": "Duplicate idempotency key",
  "status": 409,
  "detail": "A different request body was sent with the same Idempotency-Key.",
  "error_code": "IDEMPOTENCY_KEY_REUSE_BODY_MISMATCH"
}

یہ ایجنٹ کو بتاتا ہے کہ کیا ہوا اور کیا دوبارہ کوشش کرنا مناسب ہے۔

چیک لسٹ: کیا آپ کا API ایجنٹ تیار ہے؟

معاہدہ: OpenAPI 3.x شائع کیا گیا ہے، حقیقی ٹریفک کے خلاف تصدیق شدہ، پرچر وضاحتوں اور مثالوں کے ساتھ۔
عزم: دستاویزی ریاستی مشینیں، مسلسل صفحہ بندی، طویل آپریشنز کے لیے واضح async۔
محفوظ تحریر: ضمنی اثرات کے لیے قابلیت، اگر ضروری ہو تو اختتامی نکات کو ایڈجسٹ کریں۔
غلطی: مستحکم کوڈ، تشکیل شدہ باڈی، دستاویزی اصلاحی راستہ۔
سیکورٹی: کم سے کم استحقاق کا ٹوکن، "اسرار” سائیڈ ڈور ایجنٹ غلطی سے حملہ نہیں کر سکتا۔
کام: شرح کو محدود کرنے کے لیے ڈیش بورڈز، جہاں مناسب ہو بلک اینڈ پوائنٹس، ارتباطی IDs، اور غیر معمولی ایجنٹ ٹریفک۔

نتیجہ

AI ایجنٹ کے لیے ڈیزائن کرنا، زیادہ تر معاملات میں، منظم API ڈیزائن ہے۔ اس کا مطلب یہ ہے کہ مشینوں کو اس مقام پر دھکیل دیا جاتا ہے جہاں وہ بغیر کسی علم کی کمی کے معاہدوں پر انحصار کر سکتی ہیں۔

اگر آپ کو صرف تین چیزیں یاد ہیں۔

قابل قیاس: ظاہری شکل، حالت اور ضمنی اثرات۔
واضح طور پر: اسکیما، مثالیں، اور غلطیاں۔
حفاظت: جلد کوالیفائی کریں، دائرہ کار کو کم کریں، اور حادثاتی طور پر خطرناک رویے کو متحرک کرنا مشکل بنائیں۔