مرجع REST API

التوثيق التفاعلي

يقدّم كل تطبيق Agent-Lab توثيق OpenAPI 3 تلقائياً — التنفيذ المرجعي متاح على http://localhost:18000/docs (أو على تطبيقك أينما كان يعمل). يوثّق الكتالوج أدناه الموجّهات المدمجة في الإطار؛ وتظهر extra_routers الخاصة بك في المخطط نفسه.

المصادقة

عندما تكون قيمة auth.enabled هي true (راجع مرجع الإعدادات)، تتطلب المسارات رمز bearer من Keycloak. ولا يُركَّب الموجّه /auth إلا عند تفعيل المصادقة:

TOKEN=$(curl -s -X POST https://<host>/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "…", "password": "…"}' | jq -r '.access_token')

curl -s https://<host>/agents/list -H "Authorization: Bearer $TOKEN" | jq

يتناول المصادقة باستخدام Keycloak إعداد الـ realm والعميل.

المسارات التي لا تتطلب مصادقة: /status/*، و/docs، و/openapi.json، و/mcp، و/static، ونقاط نهاية OAuth المعروفة (well-known)، ونقطة تركيب SPA — أما كل ما عدا ذلك فيتطلب رمزاً صالحاً.

نقاط النهاية

الوكلاء

أنشئ نسخاً من أي نوع وكيل مسجّل؛ ويُتحقق من agent_type ديناميكياً مقابل السجل.

الرسائل

النماذج اللغوية

التكاملات

المرفقات

الحالة وMCP

أمثلة على الطلبات

إنشاء نسخة وكيل — يقبل agent_name المحارف [a-zA-Z0-9_-]؛ ويجب أن يكون agent_type نوعاً مسجّلاً؛ أما language_model_id فاختياري:

curl -s -X POST http://localhost:18000/agents/create \
  -H "Content-Type: application/json" \
  -d '{
        "agent_name": "support-agent-1",
        "agent_type": "coordinator_planner_supervisor",
        "language_model_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }' | jq

إرسال رسالة — تكون قيمة message_role إحدى القيم human أو assistant أو tool؛ وattachment_id اختياري:

curl -s -X POST http://localhost:18000/messages/post \
  -H "Content-Type: application/json" \
  -d '{
        "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "message_role": "human",
        "message_content": "Summarize the attached report.",
        "attachment_id": null
      }' | jq

تحديث إعداد وكيل — يقبل setting_key المحارف [a-zA-Z_-]؛ ويتسع setting_value لما يصل إلى 16,000 حرف (هنا تُخزَّن قوالب الموجّهات وحمولات JSON — راجع نموذج نطاق الكيانات):

curl -s -X POST http://localhost:18000/agents/update_setting \
  -H "Content-Type: application/json" \
  -d '{
        "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "setting_key": "system_prompt",
        "setting_value": "You are a concise research assistant…"
      }' | jq

الاصطلاحات

• المعرّفات من نوع UUID؛ وتقبل جميع نقاط نهاية القوائم أجسام JSON، لا سلاسل الاستعلام.
• الإعدادات أزواج مفتاح-قيمة تُخزَّن مع الوكيل أو النموذج — وبهذه الطريقة يشغّل التنفيذ نفسه نسخاً عديدة بإعدادات مختلفة.
• السجل هو المصدر المعتمد للقيم الصالحة لـ agent_type — نفّذ GET /agents/types لترى ما اكتشفه التطبيق قيد التشغيل (بما في ذلك حزمك الخاصة عبر scan_packages).