AI Agent Gateway کے ساتھ AI ایجنٹس تعینات اور محفوظ کریں

AI ایجنٹ گیٹ وے کیا ہے؟

AI ایجنٹ گیٹ وے ایک اوپن سورس سروس ہے جو AI ایجنٹس اور ان کے زیرِ استعمال سسٹمز کے درمیان کام کرتی ہے۔ یہ MCP ٹول سرورز اور معاون LLM فراہم کنندگان، بشمول Anthropic Claude، AWS Bedrock، OpenAI، اور Gemini، کے لیے ایک مستند اور قابلِ مشاہدہ داخلی نقطہ فراہم کرتی ہے۔

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

سروس تین لسنرز فراہم کرتی ہے:

• پورٹ 8080 پر MCP طیارہ: ایجنٹس سے MCP درخواستیں وصول کرتا ہے اور اجازت یافتہ کارروائیاں رجسٹر شدہ ٹول سرورز کو بھیجتا ہے۔
• پورٹ 8081 پر کنٹرول طیارہ: REST API اور انتظامی کنسول کی میزبانی کرتا ہے۔
• پورٹ 8082 پر LLM طیارہ: معاون LLM درخواستوں کو پراکسی کرتا ہے اور استعمال کی معلومات ریکارڈ کرتا ہے۔

PostgreSQL ضروری ہے۔ Redis سے مطابقت رکھنے والا سیشن اسٹور اختیاری ہے اور MCP طیارے کو ایک سے زیادہ ریپلیکا کے ساتھ چلانے کی اجازت دیتا ہے؛ بنڈل شدہ تعیناتیاں Valkey استعمال کرتی ہیں۔ ClickHouse اختیاری ہے اور اضافی تجزیاتی خصوصیات فراہم کرتا ہے۔

اہم خصوصیات

• ہر درخواست کے لیے توثیق: گیٹ وے سے جاری کردہ API کیز کسی ٹیننٹ اور کردار تک محدود ہوتی ہیں۔
• محفوظ کنیکٹر اسناد: اسناد ایک خفیہ کردہ سیکرٹ اسٹور میں محفوظ ہوتی ہیں اور کال کرنے والے کے سامنے ظاہر کیے بغیر آؤٹ باؤنڈ MCP درخواستوں میں شامل کی جاتی ہیں۔
• ایجنٹ کے لیے مخصوص ٹول پالیسیاں: پروفائلز محدود کر سکتے ہیں کہ ایجنٹ کون سے ٹولز استعمال کر سکتا ہے۔ پابندیاں صرف ٹولز کی فہرست بناتے وقت نہیں بلکہ tools/call کے دوران بھی نافذ کی جاتی ہیں۔
• پرامپٹس اور وسائل: گیٹ وے بیک اینڈ پرامپٹس اور وسائل کو مشترکہ نیم اسپیس کے ذریعے منتقل کرتا ہے اور وہی پروفائل پالیسیاں لاگو کرتا ہے۔
• اسکلز اور کمانڈز: پروفائلز میں دوبارہ قابلِ استعمال حوالہ جاتی متن اور مقامی MCP طریقۂ کار کے ذریعے ظاہر کیے جانے والے پرامپٹ ٹیمپلیٹس شامل کیے جا سکتے ہیں۔
• متعدد فراہم کنندگان والا LLM پراکسی: LLM طیارہ Anthropic، Bedrock، OpenAI، اور Gemini کو سپورٹ کرتا ہے جبکہ ٹوکن کے استعمال اور تخمینی لاگت کو ریکارڈ کرتا ہے۔
• مرکزی مشاہد پذیری: کنسول رسائی کے لاگز، LLM لاگز، سیشن ٹائم لائنز، اور ضروری اسٹوریج فعال ہونے پر تجزیاتی ڈیش بورڈ تک رسائی فراہم کرتا ہے۔
• آؤٹ باؤنڈ درخواستوں کا تحفظ: سرور سائیڈ ریکویسٹ جعل سازی کے خطرات کم کرنے کے لیے داخلی، لوپ بیک، لنک لوکل، اور دیگر نجی مقامات کو پہلے سے بلاک کیا جاتا ہے۔

ضروریات

تیز ترین سیٹ اپ Docker Compose استعمال کرتا ہے۔ شروع کرنے سے پہلے درج ذیل انسٹال یا تصدیق کر لیں:

• Compose پلگ اِن کے ساتھ Docker، مثلاً Docker Desktop، Colima، یا Docker Engine۔
• ہیلتھ چیکس کے لیے curl اور API جوابات پر کارروائی کے لیے jq۔
• مقامی پورٹس 8080، 8081، اور 8082 خالی ہوں۔
• اگر تجزیاتی پروفائل اور اس کی Adminer سروس فعال کریں تو پورٹ 8090 بھی خالی ہو۔
• کم از کم 4 GB مفت Docker گنجائش، یا ClickHouse تجزیات شامل کرنے پر 8 GB۔

macOS اور Linux سپورٹ کیے جاتے ہیں۔ Windows کو WSL2 کے ذریعے استعمال کیا جا سکتا ہے، تاہم اس ماحول کی فی الحال جانچ نہیں کی گئی۔

Docker سے باہر build کرنے کے لیے ریپوزٹری کو Go 1.27، کنسول کے لیے Node.js 26، اور make درکار ہیں۔ کچھ عملی مثالوں کے لیے اضافی طور پر npx، Python، kind، kubectl، یا کسی فراہم کنندہ کی API key درکار ہوتی ہے۔

گیٹ وے انسٹال اور شروع کریں

1. ریپوزٹری کلون کریں

git clone https://github.com/Tuskira/ai-agent-gateway.git
cd ai-agent-gateway

2. معیاری Compose اسٹیک لانچ کریں

docker compose -f deploy/docker-compose.yml up --build -d

پہلی بار شروع ہونے میں کچھ وقت لگ سکتا ہے کیونکہ Docker کو مطلوبہ اجزا build یا ڈاؤن لوڈ کرنے اور ڈیٹا بیس کو شروع کرنے کی ضرورت ہوتی ہے۔

3. کنٹرول طیارے کا انتظار کریں

until curl -sf localhost:8081/api/v1/health >/dev/null; do sleep 1; done

یہ لوپ اس وقت تک انتظار کرتا ہے جب تک کنٹرول طیارے کا ہیلتھ اینڈ پوائنٹ کامیاب جواب نہیں دیتا۔

4. تینوں طیارے چیک کریں

curl localhost:8080/health
curl localhost:8081/api/v1/health
curl localhost:8082/health

کامیاب جوابات اس بات کی تصدیق کرتے ہیں کہ MCP، کنٹرول، اور LLM لسنرز دستیاب ہیں۔

انتظامی رسائی شروع کریں

نئی تعیناتی میں کوئی کنسول صارف اور کوئی API key نہیں ہوتی۔ پہلے سے طے شدہ ٹیننٹ اور منتظم کی API key بنانے کے لیے یہ عمل شروع کریں:

docker compose -f deploy/docker-compose.yml exec gateway /gateway bootstrap-key

کمانڈ API key صرف ایک بار دکھاتی ہے۔ اسے محفوظ رکھیں کیونکہ شروع کرنے کے طریقۂ کار میں کنیکٹر رجسٹر کرنے اور انتظامی API کارروائیاں انجام دینے کے لیے یہی key استعمال ہوتی ہے۔

اس کے بعد پہلا کنسول صارف بنائیں:

docker compose -f deploy/docker-compose.yml exec gateway /gateway create-user -tenant default -username admin -role admin

یہ کمانڈ ایک بار استعمال ہونے والا عارضی پاس ورڈ دکھاتی ہے۔ http://localhost:8081 کھولیں، admin کے طور پر سائن اِن کریں، اور اشارہ ملنے پر عارضی پاس ورڈ تبدیل کریں۔

پروگراموں کو عموماً API keys کے ذریعے توثیق کرنی چاہیے۔ کنسول ہنگامی متبادل کے طور پر API key بھی قبول کر سکتا ہے۔

بنیادی استعمال: MCP سرور شامل کریں اور کال کریں

گیٹ وے کی اصطلاح میں، MCP ٹول سرور API میں connector اور کنسول میں MCP ہوتا ہے۔ سائن اِن کرنے کے بعد MCPs → Catalog کھولیں تاکہ شامل کیے جا سکنے والے تیار شدہ MCP سرورز دیکھ سکیں۔

پہلی بار استعمال کا معمول کا طریقہ یہ ہے:

1. ایڈمنسٹریٹر API کلید بنائیں اور محفوظ کریں۔
2. MCP سرور کو کنیکٹر کے طور پر رجسٹر کریں۔
3. کنیکٹر کو درکار کسی بھی اسناد کو ترتیب دیں۔
4. ایجنٹ پروفائل بنائیں یا منتخب کریں۔
5. کنیکٹر کے ٹولز اس پروفائل کے لیے دستیاب کریں۔
6. گیٹ وے کے MCP لسنر پر پورٹ 8080 کے ذریعے اجازت یافتہ ٹول کال کریں۔
7. انتظامی کنسول میں کال کا معائنہ کریں۔

ریپوزٹری میں examples/01-quickstart کے تحت مکمل قابلِ اجرا رہنمائی موجود ہے۔ یہ اسٹیک شروع کرتی ہے، تینوں پلینز کی تصدیق کرتی ہے، ایڈمنسٹریٹر کلید بناتی ہے، ایک نمونہ MCP سرور رجسٹر کرتی ہے، اور اس کے ایک ٹول کو کال کرتی ہے۔ کنیکٹر کی درست رجسٹریشن اور ٹول کال کی درخواستوں کے لیے آغاز کی رہنمائی پر عمل کریں۔

بیرونی اسناد کے بغیر چلنے والی تمام مثالیں چلانے کے لیے یہ کمانڈ استعمال کریں:

make examples-smoke

ایجنٹ پروفائلز رسائی کیسے نافذ کرتے ہیں

پروفائلز ایجنٹ کے لیے دستیاب ٹولز، پرامپٹس، وسائل، مہارتوں اور کمانڈز کی وضاحت کرتے ہیں۔ ٹول کی پابندیوں کی جانچ اس وقت ہوتی ہے جب ایجنٹ tools/call کو طلب کرتا ہے، اس لیے tools/list سے ٹول چھپانا نفاذ کی واحد سطح نہیں ہے۔

زیادہ مضبوط پالیسی نفاذ کے لیے API کلید کو کسی پروفائل سے منسلک کریں۔ کسی منسلک کے بغیر، کال کرنے والا X-Agent-Profile-Name ہیڈر کے ذریعے اپنا مطلوبہ پروفائل بتا سکتا ہے۔ کلید اور پروفائل کا منسلک ہونا کال کرنے والے کو آزادانہ طور پر کوئی دوسرا پروفائل منتخب کرنے سے روکتا ہے۔

جب متعدد MCP سرورز پرامپٹس یا وسائل فراہم کرتے ہیں، تو گیٹ وے انہیں ایک مشترکہ نیم اسپیس میں رکھتا ہے۔ پرامپٹس کے نام کے ساتھ ان کے کنیکٹر کا نام شامل کیا جاتا ہے، جبکہ وسائل گیٹ وے کے زیر انتظام URIs استعمال کرتے ہیں۔ وہی پروفائل قواعد طے کرتے ہیں کہ ایجنٹ کن اندراجات تک رسائی حاصل کر سکتا ہے۔

LLM پراکسی استعمال کریں

LLM پلین معاون ماڈل فراہم کنندگان تک مرکزی راستہ فراہم کرتا ہے: Anthropic، AWS Bedrock، OpenAI، اور Gemini۔ اس کے ذریعے ایجنٹ ایپلیکیشنز ٹولز کے لیے استعمال ہونے والی اسی کنٹرول شدہ سطح سے ماڈل ٹریفک بھیج سکتی ہیں۔

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

کلائنٹ ترتیب دینے سے پہلے لسنر کی تصدیق کے لیے ہیلتھ اینڈ پوائنٹ استعمال کریں:

curl localhost:8082/health

اینالیٹکس فعال کریں

معیاری تعیناتی ClickHouse کے بغیر LLM لاگز کو سپورٹ کرتی ہے۔ Overview ڈیش بورڈ، Access Logs، Session Timeline، اور ClickHouse پر مبنی اینالیٹکس شامل کرنے کے لیے Compose کو analytics پروفائل کے ساتھ شروع کریں:

GATEWAY_SINKS_CLICKHOUSE_ENABLED=true docker compose -f deploy/docker-compose.yml --profile analytics up --build -d

اس کنفیگریشن کے لیے زیادہ مقامی وسائل درکار ہیں اور یہ پورٹ 8090 استعمال کر سکتی ہے۔

حساس درخواست کے باڈیز کا تحفظ کریں

نمائشی اسٹیک LLM درخواست اور جواب کے باڈیز PostgreSQL میں محفوظ کرتا ہے، جہاں ہر ایک کی حد 1 MiB ہے۔ analytics پروفائل کے ساتھ یہ LLM اور MCP درخواست اور جواب کے باڈیز کو ClickHouse میں بھی محفوظ کرتا ہے تاکہ انہیں کنسول میں دکھایا جا سکے۔ یہ باڈیز کنٹینر لاگز میں پرنٹ نہیں کیے جاتے۔

اگر پرامپٹس، ماڈل کے جوابات، یا ٹول پے لوڈز میں حساس معلومات شامل ہو سکتی ہیں، تو باڈی اسٹوریج مکمل طور پر بند کر دیں:

GATEWAY_LLM_PROXY_CAPTURE_STORE_BODIES=false GATEWAY_CAPTURE_STORE_BODIES=false docker compose -f deploy/docker-compose.yml up --build -d

پروڈکشن ڈیٹا کے ساتھ کیپچر کی خصوصیات استعمال کرنے سے پہلے آبزرویبلٹی کی دستاویزات کا جائزہ لیں۔

مقامی یا نجی MCP سرورز سے محفوظ طریقے سے جڑیں

گیٹ وے لوپ بیک، نجی، لنک لوکل، اور دیگر اندرونی منزلوں کو بطور ڈیفالٹ بلاک کرتا ہے۔ یہ کلاؤڈ میٹا ڈیٹا ایڈریس 169.254.169.254 کو بھی مستقل طور پر بلاک کرتا ہے۔ یہ پالیسی کسی کنیکٹر، کیٹلاگ اندراج، یا ماڈل ہدف کو میزبان یا نیٹ ورک پر موجود حساس سروسز تک خاموشی سے پہنچنے سے روکتی ہے۔

اگر کسی میزبان نام کے بنائے جانے کے وقت وہ صرف بلاک شدہ پتوں پر حل ہوتا ہے، تو گیٹ وے اسے 400 egress_blocked کے ساتھ مسترد کر دیتا ہے۔ جو میزبان نام ابھی حل نہ ہو، اسے قبول کیا جا سکتا ہے، لیکن گیٹ وے کے کنیکٹ کرنے کی کوشش کے وقت اس کی دوبارہ جانچ کی جاتی ہے۔

بائنری براہِ راست چلانا

make run کے ساتھ چلاتے وقت، اگر MCP سرور اسی مشین پر چل رہا ہو تو لوپ بیک کی واضح اجازت دیں:

GATEWAY_EGRESS_ALLOWED_CIDRS=127.0.0.0/8,::1/128 make run

فراہم کردہ Compose اسٹیک استعمال کرنا

شامل کردہ Compose کنفیگریشن پہلے ہی host.docker.internal اور لوپ بیک CIDRs کی اجازت دیتی ہے۔ اس لیے آپ کے لیپ ٹاپ پر چلنے والے سرور کو host.docker.internal کے ذریعے مخاطب کیا جا سکتا ہے۔ مشترکہ ماحول میں ان اجازتوں کو ہٹا دیں، جب تک کہ ان کی ضرورت نہ ہو۔

Kubernetes یا نجی نیٹ ورکس استعمال کرنا

کلسٹر کے اندر موجود Kubernetes سروس کے لیے صرف کال کیے جانے والے DNS نام کی اجازت دیں، مثلاً:

GATEWAY_EGRESS_ALLOWED_HOSTS=my-mcp-server.my-ns.svc

متبادل طور پر آپ متعلقہ pod یا service CIDR کی اجازت دے سکتے ہیں۔ صرف VPN یا نجی نیٹ ورک پر دستیاب سرورز کے لیے ہر نجی ایڈریس رینج کو فعال کرنے کے بجائے مخصوص میزبان نام یا محدود CIDR شامل کریں۔

آؤٹ باؤنڈ اجازت ناموں کی فہرست کو حتی الامکان محدود رکھیں۔ ابتدائی جانچ آسان بنانے کے لیے تحفظ کو غیر فعال نہ کریں۔

اعلیٰ سطحی آپریشنل تجاویز

• انسانی اور پروگراماتی رسائی الگ رکھیں: منتظمین کے لیے کنسول اکاؤنٹس اور ایجنٹس اور آٹومیشن کے لیے گیٹ وے سے جاری کردہ API کیز استعمال کریں۔
• کیز کو پروفائلز سے منسلک کریں: پروفائل سے منسلک کی، درخواست کے ہیڈر کے ذریعے کال کرنے والوں کو پروفائل منتخب کرنے کی اجازت دینے کے مقابلے میں زیادہ مضبوط یقین دہانیاں فراہم کرتی ہے۔
• اسناد گیٹ وے میں رکھیں: کنیکٹر کی اسناد مرکزی طور پر ترتیب دیں تاکہ ایجنٹس کو بنیادی راز موصول نہ ہوں۔
• کنیکٹر کی اسناد تبدیل کرتے رہیں: ہر ایجنٹ کو الگ الگ اپ ڈیٹ کرنے کے بجائے کنیکٹر اور اسناد کے انتظام کی خصوصیات استعمال کریں۔
• ڈیٹا کیپچر کو کنٹرول کریں: خفیہ پرامپٹس یا ٹول کے نتائج پر کارروائی سے پہلے فیصلہ کریں کہ درخواست اور جواب کے باڈیز محفوظ کیے جانے چاہییں یا نہیں۔
• متعدد ریپلیکس کے لیے منصوبہ بنائیں: MCP پلیَن کو ایک سے زیادہ ریپلیکس تک اسکیل کرتے وقت اختیاری Redis-protocol سیشن اسٹور ترتیب دیں۔
• محدود ایگریس قواعد استعمال کریں: وسیع نجی رینجز کے بجائے انفرادی میزبانوں یا CIDRs کی اجازت دیں۔
• عملی مثالوں سے رجوع کریں: انفرادی مثالیں اضافی منظرناموں کا احاطہ کرتی ہیں اور اپنے README فائلوں میں مطلوبہ ٹولز یا وینڈر کیز درج کرتی ہیں۔
• تبدیلیوں کی توقع رکھیں: یہ منصوبہ pre-1.0 الفا سافٹ ویئر ہے، اس لیے معمولی ورژنز کے درمیان APIs اور کنفیگریشن تبدیل ہو سکتی ہے۔

Docker کے باہر تعمیر

مقامی ڈیولپمنٹ کے لیے Go 1.27، Node.js 26، اور make انسٹال کریں۔ ریپوزٹری make build اور make run ورک فلو فراہم کرتی ہے۔ اختیاری ڈیولپمنٹ اور ریلیز ٹولز میں golangci-lint، govulncheck، اور goreleaser شامل ہیں۔

ڈیولپمنٹ کے طریقۂ کار، ٹیسٹ کمانڈز، پل ریکویسٹ کی رہنمائی، اور اسٹورز، سنکس، اور پرووائیڈرز کے ایکسٹینشن پوائنٹس کے لیے contributing guide دیکھیں۔

نتیجہ

AI Agent Gateway تصدیق شدہ اینڈ پوائنٹس کے پیچھے MCP ٹولز اور متعدد LLM پرووائیڈرز تک رسائی کو مرکزی بناتا ہے۔ اس کا پروفائل نفاذ، اسناد کی انجیکشن، بیرونی نیٹ ورک کنٹرولز، اور آبزرویبلٹی کی خصوصیات پالیسی اور رازوں کو انفرادی ایجنٹ کنفیگریشنز سے باہر رکھنے میں مدد دیتی ہیں۔

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