أدوات الوكيل

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

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

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

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

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

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

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

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

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

{
  "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 حقلاً اختيارياً عادة علامة على أن الأداة يجب تقسيمها إلى اثنتين.

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

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

1. يولّد LLM الحجج المطابقة لمخطط الإدخال.
2. تنفّذ HeroMate سير عمل الأداة داخل المشروع نفسه مع سياق المستخدم الذي استدعى الوكيل. لا ترسل طلب HTTP جديداً ولا تعيد تطبيق مصادقة endpoint الأداة أو الأدوار المسموح بها له.
3. يُرجع endpoint رده العادي.
4. يُعاد ذلك الرد إلى LLM كنتيجة أداة.
5. يقرر الوكيل ما إذا كان يستدعي أداة أخرى أو ينتج الإجابة النهائية.

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

الحواجز

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

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

اشترط مصادقة JWT على endpoint الوكيل عندما تحتاج الأدوات إلى هوية مستخدم موثوقة، وحدد الأدوار المسموح بها عند الحاجة. ترث الأدوات سياق المستدعي، لذا يُحل ${current_user_id} في SQL إلى معرّفه. لكن استدعاء الأداة ينفّذ سير عمل endpoint مباشرةً؛ لا تُطبَّق مجدداً إعدادات مصادقة HTTP أو الأدوار المسموح بها لهذا endpoint. ولا يوفّر HeroMate أماناً على مستوى الصفوف (RLS).

يجب أن يتحقق سير عمل كل أداة من دور المستدعي وأن يقيّد القراءة والكتابة بالسجلات المسموح له بها. يمكنك إعادة استخدام GET /my-orders في التطبيق والوكيل، لكن حماية JWT لمسار HTTP وحدها لا تحمي استدعاء الأداة الداخلي؛ ضع فحوصات الصلاحيات داخل سير العمل.

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

الحدود

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