أدوات الوكيل

في DYPAI، الأدوات هي endpoints. أي endpoint بنيته أصلاً — استعلام SQL أو سير عمل يخصم بطاقة أو دالة ترسل بريداً — يمكن تفعيله كأداة. يقرأ الوكيل وصفه ويقرر متى يستدعيه ويحصل على ما يُرجعه endpoint.

يعني هذا أنك لا تكتب «أدوات وكيل» منفصلة عن تطبيقك. يمكن لـ endpoint list_products نفسه الذي تستدعيه واجهة React عبر useEndpoint() أن يستدعيه الوكيل نيابة عن محادثة.

تحويل endpoint إلى أداة

افتح endpoint

اذهب إلى صفحة تفاصيل endpoint في لوحة التحكم.

فعّل مفتاح Tool

في الرأس، انقر مفتاح Tool لتفعيله. تظهر شارة بجانب اسم endpoint.

اكتب وصف أداة

هذا ما يراه الوكيل. اجعله واضحاً ومحدداً — هكذا يقرر الوكيل متى يستدعي الأداة.

جيد: "Search products by name, category, or price range. Returns up to 50 matching products with id, name, price, and stock."

سيئ: "Products endpoint"

عرّف مخطط الإدخال

انقر Edit input schema وصف المعاملات التي تقبلها الأداة. يصبح هذا مخطط JSON الذي يستخدمه LLM لتوليد الحجج.

أرفقه بوكيل

افتح endpoint وكيلك وابحث عن حقل Tools واختر الأداة. احفظ.

افعل ذلك بالطلب

يعطي MCP مساعد الذكاء الاصطناعي القدرة على فعل هذا كله. قل فقط "Turn list_products and create_order into tools and attach them to my sales_assistant agent." يكشف MCP السحابي 41 أداة موجّهة للوكيل — راجع مرجع MCP.

التأليف عبر YAML / MCP

عندما تعرّف (أو مساعد الذكاء الاصطناعي) وكيلاً في YAML أو عبر MCP، تشير إلى الأدوات باسم endpoint، لا بـ UUID:

JavaScript

agent:
  provider: DYPAI Managed
  model: gpt-5-nano
  tools: [list_tasks, create_task]

يربط المرمّز تلك الأسماء بـ tool_ids الأساسية (UUIDs) تلقائياً، ويربطها مرة أخرى إلى أسماء عندما يقرأ سير العمل. لا تكتب tool_ids يدوياً بأسماء فيها — سرد أسماء endpoints تحت tools ودع DYPAI تحل المعرّفات.

مخططات الإدخال

يخبر مخطط الإدخال LLM ما الحجج التي يمكنه تمريرها. تستخدم DYPAI مخطط JSON القياسي.

JavaScript

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search term for the product name"
    },
    "category": {
      "type": "string",
      "enum": ["electronics", "clothing", "books"],
      "description": "Optional category filter"
    },
    "max_price": {
      "type": "number",
      "description": "Maximum price in EUR"
    }
  },
  "required": ["query"]
}

نصائح لمخططات جيدة:

استخدم description على كل حقل. يقرأ LLM هذه.
استخدم enum لتقييد الخيارات عندما تكون هناك قائمة ثابتة — لن يهلوس LLM قيماً.
علّم الحقول المطلوبة حتى يعرف LLM ما يجب توفيره.
أبقِه بسيطاً. مخطط بـ 20 حقلاً اختيارياً عادة علامة على أن الأداة يجب تقسيمها إلى اثنتين.

كيف يستخدم الوكيل أداة

عندما يقرر الوكيل استدعاء أداة:

يولّد LLM الحجج المطابقة لمخطط الإدخال.
تستدعي DYPAI endpoint الأداة داخل المشروع نفسه — مع سياق مستخدم الوكيل (لذا يعمل ${current_user_id} والمصادقة كالمعتاد).
يُرجع endpoint رده العادي.
يُعاد ذلك الرد إلى LLM كنتيجة أداة.
يقرر الوكيل ما إذا كان يستدعي أداة أخرى أو ينتج الإجابة النهائية.

يحدث هذا كله داخل تنفيذ واحد. ترى واجهتك رداً متدفقاً واحداً، لا خمسة طلبات منفصلة.

الحواجز

يمكن للوكلاء إحداث ضرر كبير إذا تكرروا إلى الأبد أو استدعوا أدوات دون حدود. لدى DYPAI عدة حواجز مضمّنة، قابلة للضبط لكل وكيل:

Parameter	Type	Description
`max_iterations`	`number (default 5)`	كم جولة استدعاء أداة يمكن للوكيل تشغيلها قبل التوقف وإرجاع ما لديه. يمنع الحلقات اللانهائية.
`tool_timeout`	`seconds (default 30)`	مهلة لكل أداة. إذا استغرقت أداة أطول، تُجهض ويحصل الوكيل على خطأ يمكنه التعافي منه.
`Depth limit`	`automatic`	لا يمكن لأداة وكيل أن يستدعيها وكيل آخر لأكثر من 3 مستويات عمقاً. يمنع سلاسل الأدوات التكرارية من الانفجار.
`Workflow stack tracking`	`automatic`	إذا كانت أداة موجودة أصلاً في مكدس التنفيذ، لا يمكن استدعاؤها مرة أخرى في الطلب نفسه. يمنع حلقات A → B → A.

المصادقة داخل الأدوات

ترث الأدوات سياق الاستدعاء. إذا دردش مستخدم بمصادقة JWT مع وكيلك:

تعمل أي أداة يستدعيها الوكيل كذلك المستخدم
يُحل ${current_user_id} في SQL إلى معرّف المستخدم
تنطبق أمان مستوى الصف وفحوصات الأدوار بشكل عادي
يمكن للمستخدم العمل فقط على بياناته عبر الوكيل

يعني هذا أنك لا تحتاج «إصدارات وكيل» منفصلة لـ endpoints. يعمل endpoint الذي كتبته أصلاً لـ GET /my-orders بمصادقة JWT مباشرة.

أي endpoints تصنع أدوات جيدة؟

جيدة

Endpoints الاستعلام التي تُرجع بيانات منظَّمة (سرد وبحث والحصول). طفرات بسيطة (إنشاء وتحديث) بمدخلات واضحة. إجراءات متماثلة يمكن للوكيل إعادة المحاولة بأمان.

تجنّب

Endpoints بآثار جانبية معقّدة (إرسال بريد وخصم بطاقات) ما لم ترد حقاً أن يفعل الوكيل ذلك ذاتياً. Endpoints دون مخططات إدخال/إخراج واضحة.

الأدوات التدميرية تحتاج تأكيداً

للأدوات التي تفعل أشياء تدميرية — الحذف وإرسال المدفوعات وإرسال الرسائل — صمّمها لتتطلب حقول تأكيد صريحة (confirm: true) حتى لا يشغّلها الوكيل بالخطأ. أو أبقِها بعيداً عن الوكلاء بالكامل ودع المستخدم يشغّلها مباشرة.

الحدود


أدوات لكل وكيل	لا حد صارم، لكن >10 يبدأ بإضرار دقة النموذج
طول وصف الأداة	1024 حرفاً
مهلة الأداة	1–120 ثانية
الحد الأقصى للتكرارات	1–20
العمق التكراري	3 مستويات

الخطوات التالية

النماذج والمزوّدون

اختيار OpenAI مقابل Anthropic مقابل Gemini لاستدعاء الأدوات.

الذاكرة

حافظ على حالة المحادثة عبر استدعاءات الأدوات.

أدوات الوكيل

تحويل endpoint إلى أداة

افتح endpoint

اذهب إلى صفحة تفاصيل endpoint في لوحة التحكم.

فعّل مفتاح Tool

في الرأس، انقر مفتاح Tool لتفعيله. تظهر شارة بجانب اسم endpoint.

اكتب وصف أداة

هذا ما يراه الوكيل. اجعله واضحاً ومحدداً — هكذا يقرر الوكيل متى يستدعي الأداة.

جيد: "Search products by name, category, or price range. Returns up to 50 matching products with id, name, price, and stock."

سيئ: "Products endpoint"

عرّف مخطط الإدخال

انقر Edit input schema وصف المعاملات التي تقبلها الأداة. يصبح هذا مخطط JSON الذي يستخدمه LLM لتوليد الحجج.

أرفقه بوكيل

افتح endpoint وكيلك وابحث عن حقل Tools واختر الأداة. احفظ.

افعل ذلك بالطلب

التأليف عبر YAML / MCP

عندما تعرّف (أو مساعد الذكاء الاصطناعي) وكيلاً في YAML أو عبر MCP، تشير إلى الأدوات باسم endpoint، لا بـ UUID:

JavaScript

agent:
  provider: DYPAI Managed
  model: gpt-5-nano
  tools: [list_tasks, create_task]

مخططات الإدخال

يخبر مخطط الإدخال LLM ما الحجج التي يمكنه تمريرها. تستخدم DYPAI مخطط JSON القياسي.

JavaScript

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search term for the product name"
    },
    "category": {
      "type": "string",
      "enum": ["electronics", "clothing", "books"],
      "description": "Optional category filter"
    },
    "max_price": {
      "type": "number",
      "description": "Maximum price in EUR"
    }
  },
  "required": ["query"]
}

نصائح لمخططات جيدة:

استخدم description على كل حقل. يقرأ LLM هذه.
استخدم enum لتقييد الخيارات عندما تكون هناك قائمة ثابتة — لن يهلوس LLM قيماً.
علّم الحقول المطلوبة حتى يعرف LLM ما يجب توفيره.
أبقِه بسيطاً. مخطط بـ 20 حقلاً اختيارياً عادة علامة على أن الأداة يجب تقسيمها إلى اثنتين.

كيف يستخدم الوكيل أداة

عندما يقرر الوكيل استدعاء أداة:

يولّد LLM الحجج المطابقة لمخطط الإدخال.
تستدعي DYPAI endpoint الأداة داخل المشروع نفسه — مع سياق مستخدم الوكيل (لذا يعمل ${current_user_id} والمصادقة كالمعتاد).
يُرجع endpoint رده العادي.
يُعاد ذلك الرد إلى LLM كنتيجة أداة.
يقرر الوكيل ما إذا كان يستدعي أداة أخرى أو ينتج الإجابة النهائية.

يحدث هذا كله داخل تنفيذ واحد. ترى واجهتك رداً متدفقاً واحداً، لا خمسة طلبات منفصلة.

الحواجز

Parameter	Type	Description
`max_iterations`	`number (default 5)`	كم جولة استدعاء أداة يمكن للوكيل تشغيلها قبل التوقف وإرجاع ما لديه. يمنع الحلقات اللانهائية.
`tool_timeout`	`seconds (default 30)`	مهلة لكل أداة. إذا استغرقت أداة أطول، تُجهض ويحصل الوكيل على خطأ يمكنه التعافي منه.
`Depth limit`	`automatic`	لا يمكن لأداة وكيل أن يستدعيها وكيل آخر لأكثر من 3 مستويات عمقاً. يمنع سلاسل الأدوات التكرارية من الانفجار.
`Workflow stack tracking`	`automatic`	إذا كانت أداة موجودة أصلاً في مكدس التنفيذ، لا يمكن استدعاؤها مرة أخرى في الطلب نفسه. يمنع حلقات A → B → A.

المصادقة داخل الأدوات

ترث الأدوات سياق الاستدعاء. إذا دردش مستخدم بمصادقة JWT مع وكيلك:

تعمل أي أداة يستدعيها الوكيل كذلك المستخدم
يُحل ${current_user_id} في SQL إلى معرّف المستخدم
تنطبق أمان مستوى الصف وفحوصات الأدوار بشكل عادي
يمكن للمستخدم العمل فقط على بياناته عبر الوكيل

يعني هذا أنك لا تحتاج «إصدارات وكيل» منفصلة لـ endpoints. يعمل endpoint الذي كتبته أصلاً لـ GET /my-orders بمصادقة JWT مباشرة.

أي endpoints تصنع أدوات جيدة؟

جيدة

تجنّب

الأدوات التدميرية تحتاج تأكيداً

الحدود


أدوات لكل وكيل	لا حد صارم، لكن >10 يبدأ بإضرار دقة النموذج
طول وصف الأداة	1024 حرفاً
مهلة الأداة	1–120 ثانية
الحد الأقصى للتكرارات	1–20
العمق التكراري	3 مستويات

الخطوات التالية

النماذج والمزوّدون

اختيار OpenAI مقابل Anthropic مقابل Gemini لاستدعاء الأدوات.

الذاكرة

حافظ على حالة المحادثة عبر استدعاءات الأدوات.