نَشّر وحمّي وكلاء الذكاء الاصطناعي باستعمال بوابة وكلاء الذكاء الاصطناعي

شنو هو بوّابة وكلا الذكاء الاصطناعي؟

بوّابة وكلا الذكاء الاصطناعي هي خدمة مفتوحة المصدر كتخدم بين وكلاء الذكاء الاصطناعي والأنظمة اللي كيتاصلو بها. كتوفّر نقطة دخول وحدة، موثّقة وقابلة للمراقبة، لخوادم أدوات MCP ولمزوّدي LLM المدعومين، ومن بينهم Anthropic Claude وAWS Bedrock وOpenAI وGemini.

عوض ما تنسخ بيانات اعتماد الأدوات وإعدادات المزوّد لكل وكيل، تقدر تدبّر المصادقة والأسرار وسياسات الولوج وسجلات الطلبات مركزياً. البوّابة كتتوزّع فشكل ملف ثنائي واحد، وفيها وحدة تحكّم إدارية مضمّنة.

الخدمة كتفتح ثلاثة ديال المستمعين:

• طبقة MCP فالمنفذ 8080: كتستقبل طلبات MCP من الوكلاء وكتحوّل العمليات المسموح بها لخوادم الأدوات المسجّلة.
• طبقة التحكّم فالمنفذ 8081: كتستضيف REST API ووحدة التحكّم الإدارية.
• طبقة LLM فالمنفذ 8082: كتعمل كوسيط لطلبات LLM المدعومة وكتسجّل معلومات الاستعمال.

PostgreSQL ضروري. مخزن جلسات متوافق مع Redis اختياري، وكيخلّي طبقة MCP تخدم بأكثر من نسخة؛ التوزيعات المرفقة كتستعمل Valkey. ClickHouse اختياري وكيشغّل مزايا إضافية للتحليلات.

المزايا الرئيسية

• المصادقة فكل طلب: مفاتيح API اللي كتصدّرها البوّابة مرتبطة بمستأجر ودور.
• حماية بيانات اعتماد الموصلات: بيانات الاعتماد كتتخزّن فمخزن أسرار مشفّر وكتتحقن فطلبات MCP الخارجة بلا ما تبان للجهة اللي طلباتها.
• سياسات أدوات خاصة بكل وكيل: البروفايلات تقدر تحدّد الأدوات اللي يقدر الوكيل يستعملها. القيود كتتطبّق أثناء tools/call، وماشي غير ملي كتتعرض لائحة الأدوات.
• المطالبات والموارد: البوّابة كتمرّر مطالبات وموارد الواجهة الخلفية عبر مساحة أسماء مشتركة وكتطبّق نفس سياسات البروفايل.
• المهارات والأوامر: البروفايلات تقدر تضم نصوص مرجعية قابلة لإعادة الاستعمال وقوالب مطالبات معروضة عبر آليات MCP الأصلية.
• وسيط LLM متعدد المزوّدين: طبقة LLM كتدعم Anthropic وBedrock وOpenAI وGemini، وكتسجّل استعمال الرموز والتكلفة التقديرية.
• مراقبة مركزية: وحدة التحكّم كتوفّر الولوج لسجلات الولوج، وسجلات LLM، والخطوط الزمنية للجلسات، ولوحة تحليلات ملي كتكون وحدات التخزين الضرورية مفعّلة.
• حماية الطلبات الخارجة: الوجهات الداخلية، وloopback، وlink-local، والوجهات الخاصة الأخرى كتكون محظورة افتراضياً للتقليل من مخاطر تزوير الطلبات من جهة الخادم.

المتطلبات المسبقة

أسرع إعداد كيستعمل Docker Compose. قبل ما تبدا، نصّب أو تأكد من هاد العناصر:

• Docker مع إضافة Compose، بحال Docker Desktop أو Colima أو Docker Engine.
• curl لفحوصات الصحة وjq لمعالجة استجابات API.
• المنافذ المحلية 8080 و8081 و8082 تكون خالية.
• المنفذ 8090 إلا فعّلتي بروفايل التحليلات وخدمة Adminer ديالو.
• على الأقل 4 GB من سعة Docker الخالية، أو 8 GB ملي كتزيد تحليلات ClickHouse.

macOS وLinux مدعومين. Windows تقدر تستعملو عبر WSL2، مع أن هاد البيئة مازال ما تجرّباتش.

إلا بغيتي تبني خارج Docker، المستودع كيحتاج Go 1.27 وNode.js 26 للوحدة الإدارية وmake. بعض الأمثلة العملية كتحتاج حتى npx أو Python أو kind أو kubectl أو مفتاح API ديال المزوّد.

تثبيت البوّابة وتشغيلها

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 خاصّو يبني أو يحمّل المكوّنات الضرورية ويهيّأ قاعدة البيانات.

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. بْدا بإنشاء المستأجر الافتراضي ومفتاح API ديال مدير:

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

الأمر كيطبّع مفتاح API غير مرة وحدة. خزّنو بأمان حيث مسار البدء كيستعملو لتسجيل الموصلات وتنفيذ عمليات API الإدارية.

من بعد، أنشئ أول مستخدم لوحدة التحكّم:

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

هاد الأمر كيطبّع كلمة سر مؤقتة كتستعمل مرة وحدة. حلّ http://localhost:8081، دخل باسم admin، وبدّل كلمة السر المؤقتة ملي يطلب منك ذلك.

فالعادة، البرامج خاصها تصادق باستعمال مفاتيح API. وحدة التحكّم تقدر حتى تقبل مفتاح API كحل احتياطي فحالة الطوارئ.

الاستعمال الأساسي: إضافة واستدعاء خادم MCP

فمصطلحات البوّابة، خادم أدوات MCP كيتسمّى موصل فالـAPI و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

فعّل التحليلات

النشر العادي كيدعم سجلات LLM بلا ClickHouse. باش تزيد لوحة Overview، وسجلات الولوج، والخط الزمني للجلسات، والتحليلات المعتمدة على 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 لكل واحد. ومع بروفايل التحليلات، كيخزّن حتى أجسام طلبات واستجابات 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 المحلية أو الخاصة

البوابة كتمنع افتراضياً عناوين loopback، والعناوين الخاصة، وعناوين link-local، والوجهات الداخلية الأخرى. وكتمنع بشكل دائم عنوان بيانات السحابة 169.254.169.254. هاد السياسة كتمنع موصل، أو مدخل فالفهرس، أو هدف نموذج من الوصول بلا ما يبان لخدمات حساسة فالمضيف ولا فالشبكة.

إلا كان اسم المضيف كيتحل غير لعناوين محظورة ملي كيتصايب، البوابة كترفضو بـ400 egress_blocked. أما اسم المضيف اللي مازال ما كيتحلّش، يقدر يتقبل، ولكن كيتعاود التحقق منو ملي كتحاول البوابة تتصل.

تشغيل الملف التنفيذي مباشرة

ملي كتخدم بـmake run، سمح صراحة بـloopback إلا كان سيرفر MCP خدام فنفس الجهاز:

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

استعمال ستاك Compose المرفق

إعداد Compose المرفق كيسمح من قبل بـhost.docker.internal وبشبكات loopback CIDRs. بالتالي، سيرفر خدام فالحاسوب المحمول ديالك تقدر توصّل ليه عبر host.docker.internal. حيد هاد السماحات فالبيئات المشتركة إلا ما كانتش ضرورية.

استعمال Kubernetes ولا الشبكات الخاصة

بالنسبة لخدمة Kubernetes داخل الكلستر، سمح غير باسم DNS اللي غادي يتستعمل، مثلاً:

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

وتقدر حتى تسمح بـCIDR ديال الـpod ولا الخدمة المعنية. بالنسبة لسيرفرات ما كيتوصل ليها غير عبر VPN ولا شبكة خاصة، زِد اسم المضيف المحدد ولا CIDR ضيق، بلا ما تفعّل جميع نطاقات العناوين الخاصة.

خلي لوائح السماح للخروج ضيقة قدر الإمكان. ما تعطلش الحماية غير باش تسهّل الاختبار الأولي.

نصائح تشغيلية متقدمة

• فرّق بين الولوج البشري والولوج ديال البرامج: استعمل حسابات الكونسول للمسؤولين ومفاتيح API كيصدرها الـgateway للوكلاء والأتمتة.
• ربط المفاتيح بالبروفايلات: المفتاح المرتابط ببروفايل كيعطي ضمانات أقوى من أنك تخلي المستعملين يختارو بروفايل عن طريق ترويسة فالطلب.
• خزّن بيانات الاعتماد فالـgateway: كوّن بيانات اعتماد الـconnectors مركزياً باش ما يوصلوش الوكلاء للأسرار الأصلية.
• بدّل بيانات اعتماد الـconnectors بانتظام: استعمل خصائص إدارة الـconnectors وبيانات الاعتماد بلا ما تحدّث كل وكيل بوحدو.
• تحكّم فجمع البيانات: قرّر واش خاص الاحتفاظ بأجسام الطلبات والردود قبل معالجة prompts سرّية أو نتائج الأدوات.
• خطّط لعدة نسخ مكررة: كوّن مخزن الجلسات الاختياري ببروتوكول Redis ملي كتوسّع طبقة MCP لأكثر من نسخة مكررة وحدة.
• استعمل قواعد خروج ضيقة: سمح بمضيفين أو CIDRات محددين بلا ما تسمح بنطاقات خاصة واسعة.
• راجع الأمثلة التطبيقية: كل مثال كيغطي سيناريوهات إضافية وكيذكر الأدوات أو مفاتيح المورّدين المطلوبة فملفات README ديالو.
• توقّع التغييرات: المشروع مازال برنامج ألفا قبل الإصدار 1.0، لذلك الـAPIs والإعدادات يقدرو يتبدلو بين الإصدارات الثانوية.

البناء خارج Docker

فالتطوير المحلي، ثبّت Go 1.27 وNode.js 26 وmake. المستودع كيوفّر مسارات العمل make build وmake run. ومن أدوات التطوير والإصدار الاختيارية كاينين golangci-lint وgovulncheck وgoreleaser.

بالنسبة لاتفاقيات التطوير، وأوامر الاختبار، وإرشادات طلبات الدمج، ونقاط التوسعة الخاصة بالمخازن ووجهات الإرسال والمزوّدين، راجع دليل المساهمة.

الخلاصة

AI Agent Gateway كيجمع الولوج لأدوات MCP ولعدة مزوّدين ديال LLM من ورا نقاط نهاية محمية بالمصادقة. فرض البروفايلات، وحقن بيانات الاعتماد، والتحكم فالشبكة الصادرة، وخصائص المراقبة كيساعدو باش تبقى السياسات والأسرار بعيدة على إعدادات كل وكيل.

بدا بالإعداد السريع ديال Docker Compose، حفظ مفتاح المسؤول اللي تولّد، أنشئ مستخدم فالكونسول، وكمل أول سير عمل ديال connector. من بعد، زِد مفاتيح API مربوطة بالبروفايلات، كوّن الولوج للمزوّدين، اختار سياسة مناسبة لالتقاط الأجسام، وفعّل تحليلات ClickHouse غير ملي تحتاج للرؤية الإضافية.