Skip to main content
المهارات والوكلاء حاليًا في مرحلة الألفا. الميزة تعمل لكنها لا تزال قيد التطور.
يمكن للتطبيقات تعريف قدرات ذكاء اصطناعي تعمل داخل مساحة العمل — تعليمات مهارات قابلة لإعادة الاستخدام ووكلاء بموجهات نظام مخصّصة.
تُحدِّد المهارات تعليمات وإمكانات قابلة لإعادة الاستخدام يمكن لوكلاء الذكاء الاصطناعي استخدامها داخل مساحة العمل لديك. استخدم defineSkill() لتعريف مهارات مع تحقّق مدمج:
src/skills/example-skill.ts
النقاط الرئيسية:
  • name هي سلسلة معرّف فريدة للمهارة (يُنصَح باستخدام kebab-case).
  • label هو اسم العرض المقروء للبشر الظاهر في واجهة المستخدم.
  • content يحتوي على تعليمات المهارة — وهو النص الذي يستخدمه وكيل الذكاء الاصطناعي.
  • icon (اختياري) يحدّد الأيقونة المعروضة في واجهة المستخدم.
  • description (اختياري) يوفّر سياقًا إضافيًا حول غرض المهارة.
الوكلاء هم مساعدون ذكاء اصطناعي يعيشون داخل مساحة العمل لديك. استخدم defineAgent() لإنشاء وكلاء بموجه نظام مخصّص:
src/agents/example-agent.ts
النقاط الرئيسية:
  • name هي سلسلة معرّف فريدة للوكيل (يُنصح باستخدام kebab-case).
  • label هو اسم العرض الظاهر في واجهة المستخدم.
  • prompt هو موجه النظام الذي يحدّد سلوك الوكيل.
  • description (اختياري) يوفّر سياقًا حول ما يفعله الوكيل.
  • icon (اختياري) يحدّد الأيقونة المعروضة في واجهة المستخدم.
  • modelId (اختياري) يتجاوز نموذج الذكاء الاصطناعي الافتراضي الذي يستخدمه الوكيل.
  • responseFormat (اختياري) يتحكم في شكل مخرجات الوكيل. القيمة الافتراضية هي { type: 'text' } للنص الحر. استخدم { type: 'json', schema } لفرض مخرجات JSON منظمة.
بشكل افتراضي، يعيد الوكيل نصًا حرًا. للحصول على مخرجات منظمة، عيّن responseFormat إلى { type: 'json' } ووفّر schema:
src/agents/structured-agent.ts
ملاحظات حول المخطط:
  • المخطط كائن مسطح: يجب أن يكون type لكل خاصية نوعًا بدائيًا (string أو number أو boolean). الكائنات المتداخلة والمصفوفات غير مدعومة.
  • description (اختياري) على كل خاصية يوجه النموذج لما يجب وضعه هناك.
  • required (اختياري) يسرد الخصائص التي يجب على النموذج إرجاعها دائمًا.
  • additionalProperties: false (اختياري) يمنع أي خاصية غير معرّفة في properties.
تتيح runAgent() لدالة منطقية تشغيل أحد وكلاء تطبيقك (مع مهاراته وأدواته). حدِّد الوكيل بواسطة universalIdentifier الذي مررته إلى defineAgent(). مرر إما سلسلة prompt أو سجل المحادثة messages — وليس كليهما معًا:
src/logic-functions/run-enricher.ts
لبوتات المحادثة متعددة الجولات (Slack, Discord, Teams, …)، مرر سجل سلسلة المحادثة كـ messages بدلًا من استخدام prompt واحد فقط:
src/logic-functions/reply-in-thread.ts
النقاط الرئيسية:
  • قدِّم واحدًا فقط من prompt (سلسلة نصية) أو messages (من 1 إلى 100 عنصر من { role: 'user' | 'assistant', content: string }).
  • يعمل الوكيل بشكل متزامن ويمكنه قراءة/تحديث السجلات بنفسه عبر أدواته الخاصة — يتم حل runAgent() بمجرد اكتمال التشغيل.
  • لا يمكن للتطبيق تشغيل سوى وكلائه الخاصين.
  • يجب أن يمنح الدور الافتراضي للتطبيق علامة الإذن AI — أضِف SystemPermissionFlag.AI إلى permissionFlagUniversalIdentifiers الخاصة به (أو عيِّن canAccessAllTools: true). بدون ذلك، تفشل runAgent() بخطأ في الأذونات.
  • اضبط قيمة كبيرة لـ timeoutSeconds على الدالة المنطقية — قد يستغرق تشغيل الوكيل عدة ثوانٍ.
  • يكون success بقيمة true وresult غير فارغ عند اكتمال التشغيل؛ في حال الفشل يكون success بقيمة false، وresult بقيمة null، وتحتوي error على السبب (على سبيل المثال، عندما تنفد أرصدة الذكاء الاصطناعي الخاصة بمساحة العمل أثناء التشغيل).
src/roles/default-role.ts
تجنب الحلقات: إذا استدعيت runAgent() من مشغل حدث قاعدة بيانات من نوع *.updated وقام الوكيل بتحديث نفس السجل، فحدد نطاق المشغل باستخدام updatedFields إلى حقل لا يكتبه الوكيل أبدًا (مثل عنوان URL المصدر)، أو تحقَّق مما إذا كان أي حقل مستهدف لا يزال فارغًا قبل استدعاء runAgent().

التشغيل نيابةً عن أحد أعضاء مساحة العمل

مرر runAsWorkspaceMemberId عندما يتم تشغيل التنفيذ بواسطة شخص — مثل روبوت دردشة يجيب على رسالة، مثلاً — لكي يتصرف الوكيل بصفة ذلك العضو بدلًا من التطبيق:
src/logic-functions/answer-question.ts
ثم يعمل التنفيذ باستخدام دور العضو نفسه: يمكنه القيام بكل ما يمكن لذلك العضو القيام به ولا أكثر، وتنسب إليه السجلات التي ينشئها، وتُطبَّق أذوناتُه على مستوى الصف. لا يشارك دور الوكيل — فهو الإعداد الافتراضي للتطبيق لعمليات التنفيذ التي لا يقف خلفها أي شخص. احذف الحقل في عمليات التنفيذ الذاتية (المهام المجدولة، مشغلات أحداث قاعدة البيانات): في هذه الحالة يحتفظ الوكيل بدوره الخاص. يبقى التطبيق الفاعل مرتبطًا بسياق التنفيذ لأغراض التتبّع وإثبات المصدر، دون تقييد أذونات العضو.تطبيقك مسؤول عن تعيين الشخص الذي شغّل التنفيذ إلى عضو في مساحة العمل. يتطلب تسمية عضو ما رمز وصول للتطبيق، وما يمكن للرمز تسميته يعتمد على ما إذا كان يتضمن مستخدمًا أم لا:
  • يمكن لرمز بدون مستخدم مرفق أن يسمّي أي عضو. تعمل الدالة المنطقية بدون مستخدم، وكذلك الرموز المُنشأة عبر client_credentials أو من مفتاح API.
  • لا يمكن لرمز مُصدَر نيابةً عن مستخدم، كما يستقبله مكوّن الواجهة الأمامية، أن يسمّي إلا العضو الخاص بذلك المستخدم فقط.
لا يمكن لأي شيء آخر — جلسة مستخدم عادية، أو مفتاح API بدون رمز تطبيق — أن يسمّي عضوًا على الإطلاق.
يقوم runAgent() بإطلاق استثناء عندما يتعذّر حل عضو مساحة العمل — مثل عضو غير معروف أو تمت إزالته، أو ليس لديه أي دور. لا يعود إطلاقًا إلى دور الوكيل نفسه، لأن ذلك سيمنح صلاحيات وصول أكثر مما طلبه المستدعي.