المهارات والوكلاء

import { defineSkill } from 'twenty-sdk/define';

export default defineSkill({
  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  name: 'sales-outreach',
  label: 'Sales Outreach',
  description: 'Guides the AI agent through a structured sales outreach process',
  icon: 'IconBrain',
  content: `You are a sales outreach assistant. When reaching out to a prospect:
1. Research the company and recent news
2. Identify the prospect's role and likely pain points
3. Draft a personalized message referencing specific details
4. Keep the tone professional but conversational`,
});

• name هي سلسلة معرّف فريدة للمهارة (يُنصَح باستخدام kebab-case).
• label هو اسم العرض المقروء للبشر الظاهر في واجهة المستخدم.
• content يحتوي على تعليمات المهارة — وهو النص الذي يستخدمه وكيل الذكاء الاصطناعي.
• icon (اختياري) يحدّد الأيقونة المعروضة في واجهة المستخدم.
• description (اختياري) يوفّر سياقًا إضافيًا حول غرض المهارة.

import { defineAgent } from 'twenty-sdk/define';

export default defineAgent({
  universalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  name: 'sales-assistant',
  label: 'Sales Assistant',
  description: 'Helps the sales team draft outreach emails and research prospects',
  icon: 'IconRobot',
  prompt: 'You are a helpful sales assistant. Help users with their questions and tasks.',
});

• name هي سلسلة معرّف فريدة للوكيل (يُنصح باستخدام kebab-case).
• label هو اسم العرض الظاهر في واجهة المستخدم.
• prompt هو موجه النظام الذي يحدّد سلوك الوكيل.
• description (اختياري) يوفّر سياقًا حول ما يفعله الوكيل.
• icon (اختياري) يحدّد الأيقونة المعروضة في واجهة المستخدم.
• modelId (اختياري) يتجاوز نموذج الذكاء الاصطناعي الافتراضي الذي يستخدمه الوكيل.
• responseFormat (اختياري) يحدد شكل الإخراج الافتراضي للوكيل. القيمة الافتراضية هي { type: 'text' } للنص الحر. استخدم { type: 'json', schema } لفرض مخرجات JSON منظمة. يمكن لاستدعاء runAgent() أو لخطوة ذكاء اصطناعي في سير عمل طلب شكل مختلف، ويكون له الأسبقية.
• يربط roleUniversalIdentifier (اختياري) الوكيل بدور يحدده تطبيقك. يجب ألا يمنح ذلك الدور صلاحيات أكثر من دور التطبيق، وإلا فسيفشل الإصدار؛ راجع أدوار الوكلاء.
• يُفعّل modelConfiguration (اختياري) الأدوات الأصلية للنموذج، كما تفعل صفحة إعدادات الوكيل: { webSearch: { enabled: true }, twitterSearch: { enabled: true } }. لا تعمل كل أداة إلا مع النماذج التي تدعمها. اتركه خارجًا لإبقائها معطلة.
• يُخفي isSystem (اختياري، وقيمته الافتراضية false) الوكيل من قوائم الوكلاء، مثل الوكلاء الذين ينشئهم Twenty لخطوات الذكاء الاصطناعي لسير العمل. إنه يغيّر ما يُعرض فقط: لا يمكن تغيير وكلاء التطبيق إلا من خلال التطبيق، بغض النظر عما تقوله هذه العلامة.

import { defineAgent } from 'twenty-sdk/define';

export default defineAgent({
  universalIdentifier: 'c4d5e6f7-a8b9-0123-cdef-456789012345',
  name: 'lead-scorer',
  label: 'Lead Scorer',
  prompt: 'Score the lead and explain your reasoning.',
  responseFormat: {
    type: 'json',
    schema: {
      type: 'object',
      properties: {
        score: { type: 'number', description: 'Lead score from 0 to 100' },
        summary: { type: 'string', description: 'Short reasoning for the score' },
      },
      required: ['score', 'summary'],
      additionalProperties: false,
    },
  },
});

• المخطط كائن مسطح: يجب أن يكون type لكل خاصية نوعًا بدائيًا (string أو number أو boolean). الكائنات المتداخلة والمصفوفات غير مدعومة.
• description (اختياري) على كل خاصية يوجه النموذج لما يجب وضعه هناك.
• required (اختياري) يسرد الخصائص التي يجب على النموذج إرجاعها دائمًا.
• additionalProperties: false (اختياري) يمنع أي خاصية غير معرّفة في properties.

import { defineMcpServer } from 'twenty-sdk/define';

import { GITHUB_CONNECTION_PROVIDER_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';

export default defineMcpServer({
  universalIdentifier: '0b6c4f7e-3d5a-4a8e-9a0d-6f1e2c3b4a01',
  name: 'github',
  label: 'GitHub',
  url: 'https://api.githubcopilot.com/mcp/',
  connectionProvider: {
    universalIdentifier: GITHUB_CONNECTION_PROVIDER_UNIVERSAL_IDENTIFIER,
  },
});

• name بصيغة snake_case (أحرف صغيرة وأرقام وشرطات سفلية، يبدأ بحرف، وبحد أقصى 32 حرفًا) وفريد في مساحة العمل. يُضاف كبادئة إلى أسماء أدوات الخادم.
• يجب أن يكون url عنوان URL من نوع HTTP أو HTTPS.
• يشير connectionProvider (اختياري) إلى موفر اتصال معلن بواسطة التطبيق نفسه. ترسل الاستدعاءات رمز الوصول الخاص بذلك الاتصال كرمز Bearer. احذفه لخادم عام.
• لا يمكن أن يتغير عنوان URL في إصدار لاحق أثناء ربط موفر اتصال، لذلك لا تُرسل الرموز أبدًا إلى مضيف آخر.
• يمكن لمساحات العمل إلغاء تنشيط الخادم؛ ويحافظ إصدار لاحق من التطبيق على هذا الخيار.
• يتطلب "engines": { "twenty": ">=2.53.0" }.

import { runAgent } from 'twenty-sdk/logic-function';

const { threadId, runId, status, result, error, success } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  input: 'Enrich House Ad <recordId>: fill empty fields from its listing URL.',
});

• input عبارة عن سلسلة نصية، أو قائمة تضم من 1 إلى 100 رسالة ({ role: 'user' | 'assistant', content: string }). يمكن أن تتضمن رسالة user أيضًا مرفقات ملفات (انظر أدناه). لإجراء محادثة، مرّر thread بدلًا من إعادة تشغيل الأدوار السابقة بنفسك.
• افتراضيا، ينتظر الاستدعاء الوكيل، الذي يمكنه قراءة/تحديث السجلات بنفسه عبر أدواته الخاصة — يُرجع runAgent() بمجرد اكتمال التشغيل. مرر waitForCompletion: false للإرجاع بمجرد بدء التشغيل: تكون status حينها RUNNING وresult: null، ويصل الرد إلى محادثة threadId. يُرجع التشغيل الذي يستمر لأكثر من 15 دقيقة أيضا بالحالة RUNNING.
• يمكن للوكيل أيضًا التوقف مؤقتًا حتى يتغير سجل أو يمر بعض الوقت. تُرجع runAgent() بعد ذلك success: true وstatus: 'SUSPENDED' و result: null؛ ثم يواصل الوكيل العمل بنفسه لاحقًا، ويصل ردّه إلى محادثة threadId. يفشل استدعاء thread الذي لا يزال وكيله في حالة انتظار إلى أن ينتهي.
• يُخزَّن كل استدعاء مع مدخلاته وحالته، بالإضافة إلى رده واستخدامه عند اكتماله، بحيث يظهر في عمليات تشغيل الوكيل. من دون thread، يحصل الاستدعاء على محادثة خاصة به: يسمّيها threadId، ولا يراها أي استدعاء لاحق مطلقًا.
• لا يمكن للتطبيق تشغيل سوى وكلائه الخاصين.
• يجب أن يمنح الدور الافتراضي للتطبيق علامة الإذن AI — أضِف SystemPermissionFlag.AI إلى permissionFlagUniversalIdentifiers الخاصة به (أو عيِّن canAccessAllTools: true). بدون ذلك، تفشل runAgent() بخطأ في الأذونات.
• اضبط قيمة كبيرة لـ timeoutSeconds على الدالة المنطقية — قد يستغرق تشغيل الوكيل عدة ثوانٍ.
• تكون status بالقيمة COMPLETED مع result غير فارغ عند اكتمال التشغيل دون انتظار؛ وبالقيمة SUSPENDED مع success: true وresult: null أثناء الانتظار؛ وبالقيمة RUNNING مع success: true وresult: null عندما لا ينتظر الاستدعاء التشغيل؛ وبالقيمة FAILED مع success: false واحتواء error على السبب (على سبيل المثال، عندما تنفد أرصدة الذكاء الاصطناعي لمساحة العمل أثناء التشغيل).

import { defineApplicationRole, SystemPermissionFlag } from 'twenty-sdk/define';

export default defineApplicationRole({
  universalIdentifier: 'b648f87b-1d26-4961-b974-0908fd991061',
  label: 'Default function role',
  // runAgent() requires the AI permission flag on the app's default role.
  permissionFlagUniversalIdentifiers: [SystemPermissionFlag.AI],
});

​

إرسال الملفات مع رسالة

const { result } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  input: [
    {
      role: 'user',
      content: 'What does this error screen say?',
      attachments: [{ fileId: uploadedFileId, filename: 'error.png' }],
    },
  ],
});

• يمكن لرسائل user فقط أن تحمل مرفقات. لا يمكن تمثيلها في دور assistant، لذا ترفضها runAgent() هناك بدلاً من إسقاطها.
• بحد أقصى 10 مرفقات لكل رسالة.
• يجب أن يشير fileId إلى ملف تم تحميله بالكامل في مساحة العمل نفسها، ضمن مجلد agent-chat. أي شيء آخر يؤدي إلى فشل الاستدعاء بدلاً من الإجابة بهدوء من دون الملف.

​

طلب نتيجة منظَّمة

const { result } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  input: `Score this lead: ${JSON.stringify(lead)}`,
  responseFormat: {
    type: 'json',
    schema: {
      type: 'object',
      properties: {
        score: { type: 'number', description: 'Lead score from 0 to 100' },
      },
      required: ['score'],
    },
  },
});

​

متابعة محادثة

const { result, threadId } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  input: 'What was the last touchpoint?',
  additionalInstructions: 'Answer in Slack markdown.',
  thread: { key: `${channelId}:${threadTs}`, title: 'Acme renewal' },
});

• تقتصر المفاتيح على تطبيقك ووكيلك، لذا لا يشترك تطبيقان مطلقًا في محادثة واحدة. لا يمكن تمرير thread إلا باستخدام رموز وصول التطبيق.
• input لا يمكن أن يحتوي إلا على رسائل user: فالمحادثة تحتوي بالفعل على ردود الوكيل.
• additionalInstructions تُعطى للنموذج لهذا الاستدعاء فقط ولا يتم تخزينها، وهي مناسبة للإرشادات الخاصة بكل طلب، مثل قواعد التنسيق أو موعد نهائي. وهي تعمل دون thread أيضًا.
• يُخزَّن كل تشغيل كدور مع حالته، بما في ذلك عمليات التشغيل الفاشلة. يُخزَّن استخدامه عند عودة الوكيل، حتى إذا نفدت أرصدته. إن التشغيل الفاشل ليس جزءًا من المحادثة، لذا لا تراه المكالمة التالية له.
• تعمل الاستدعاءات على سلسلة المحادثة نفسها واحدًا تلو الآخر: ينتظر الاستدعاء الثاني حتى ينتهي الأول، لذا يرى كلٌّ منها الأدوار التي سبقته.
• عندما تُنفَّذ الأدوار بصفتها أعضاء مختلفين (انظر أدناه)، لا يرى كل منها سوى النص الخاص بأدوار الآخرين، ولا يرى مطلقًا نتائج أدواتهم، إذ قُرئت تلك النتائج باستخدام أذونات شخص آخر.

​

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

const { result } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  input: 'How many open opportunities do we have?',
  runAsWorkspaceMemberId: '20202020-0687-4c41-b707-ed1bfca972a7',
});

• يمكن لرمز بدون مستخدم مرفق أن يسمّي أي عضو. تعمل الدالة المنطقية بدون مستخدم، وكذلك الرموز المُنشأة عبر client_credentials أو من مفتاح API.
• لا يمكن لرمز مُصدَر نيابةً عن مستخدم، كما يستقبله مكوّن الواجهة الأمامية، أن يسمّي إلا العضو الخاص بذلك المستخدم فقط.

​

متابعة محادثة

import {
  isAgentChatTurnEndEvent,
  listConversationMessages,
  streamConversation,
} from 'twenty-sdk/logic-function';

const conversation = {
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  threadKey: `${channelId}:${threadTs}`,
};
const abortController = new AbortController();
let maxCatchupSeq: number | undefined;

// subscribe before reading the history, so nothing streamed in between is lost
for await (const event of streamConversation({
  ...conversation,
  signal: abortController.signal,
})) {
  if (event.type === 'keepalive' && maxCatchupSeq === undefined) {
    const { messages, streamCatchup } =
      await listConversationMessages(conversation);

    showMessages(messages);
    for (const chunk of streamCatchup.chunks) showChunk(chunk);
    maxCatchupSeq = streamCatchup.maxSeq;
  }

  if (
    event.type === 'stream-chunk' &&
    (event.seq ?? 0) > (maxCatchupSeq ?? 0)
  ) {
    // an AI SDK UIMessageChunk, such as { type: 'text-delta', delta }
    showChunk(event.chunk);
  }

  // the reply's save, or why it stopped, such as credits-exhausted
  if (isAgentChatTurnEndEvent(event)) {
    abortController.abort();
  }
}

• الأحداث خاصة بالدردشة نفسها: يحمل stream-chunk كائن UIMessageChunk من AI SDK ومعرّف seq، وتوضح الإشعارات مثل message-persisted (تم حفظ رسالة: رسالة عضو أو الرد، الذي يحمل turnId الخاص بتشغيله)، وcredits-exhausted (توقف الرد عند نفاد الأرصدة من مساحة العمل)، وqueue-updated أو stream-error متى تقرأ السجل مرة أخرى. يصل keepalive عند الاتصال، ثم كل بضع ثوانٍ: اقرأ السجل عند أول واحد، لأن ما حدث قبله موجود فيه.
• لتحويل المقاطع إلى رسائل كما تفعل الدردشة، مررها إلى readUIMessageStream() من الحزمة ai.
• تُرجع listConversationMessages() القيمة { messages, streamCatchup }: الرسائل المحفوظة ككائنات UIMessage من AI SDK، كما تنشئها الدردشة، ومقاطع رد ما زال يُبث. اعرض تلك المقاطع، ثم تخطَّ المقاطع المباشرة التي يكون فيها seq أقل من أو مساويًا لـ streamCatchup.maxSeq، لأنها تكررها.
• تُرجع runAgent() القيمة runId، أي الدور الذي تفتحه المكالمة: تحمل رسائل ذلك التشغيل هذه القيمة كـ metadata.turnId. يستمر التشغيل الذي ينتظر في أدوار لاحقة من المحادثة.
• يبقى الدفق مفتوحًا حتى تُلغي signal الخاص به أو تستخدم break، ويُطلق خطأً إذا انقطع الاتصال: أعد إنشاء الدفق للاستئناف.
• يقرأ التطبيق محادثاته الخاصة فقط. تُظهر الأدوار التي فتحها عضو في مكان آخر، مثل الدردشة، نصها فقط في السجل والبث المباشر وفي التشغيل التالي للوكيل: في البث المباشر، تصل مقاطعها الأخرى كمقاطع message-metadata فارغة، لذلك يبقى seq بلا فجوات. تبقى الأدوار التي شغّلها تطبيقك كعضو (انظر أعلاه) كاملة عندما يقرأها بنفسه.
• يتطلب "engines": { "twenty": ">=2.56.0" }.

import { ai } from 'twenty-sdk/logic-function';

const { success, text, error } = await ai.generate({
  instructions: 'You qualify inbound leads for a B2B CRM.',
  input: `Is ${companyName} a good fit? Answer in one sentence.`,
});

• input عبارة عن سلسلة، أو قائمة برسائل { role: 'user' | 'assistant', content }.
• يضيف instructions (اختياري) تعليمات النظام الخاصة بالمتصل.
• يختار modelId (اختياري) النموذج. من دونه، تستخدم المكالمة النموذج الافتراضي لمساحة العمل.
• يعمل responseFormat (اختياري) كما في runAgent(). مع { type: 'json', schema }، يُضاف المخطط إلى طلب النموذج نفسه، لذا يتطلب جواب JSON طلبًا واحدًا (بالإضافة إلى خطوات الأداة عندما يمنح scope الأدوات).
• يتيح scope (اختياري) للمكالمة استخدام قاعدة البيانات، كما هو موضح أدناه.

• text هو رد الاستجابة النصية، ويكون null لاستجابة JSON.
• object هو نتيجة استجابة JSON، ويكون null بخلاف ذلك.
• يشرح error التشغيل الفاشل عندما تكون success هي false. يُحل التشغيل الذي يفشل بهذه الطريقة بدلًا من إطلاق خطأ؛ أما المكالمة التي لا يمكنها بدء تشغيل، مثل مكالمة ذات إدخال غير صالح، فتُطلق خطأً.
• يحدد runId التشغيل المسجل، مع نموذجه واستخدامه وأرصدته.
• usage هو { inputTokens, outputTokens }: ما أنفقه التشغيل، بما في ذلك الخطوات التي انتهت قبل الإخفاق.

const { object } = await ai.generate({
  input: `Find the open opportunities of ${companyName} and rate their risk.`,
  responseFormat: {
    type: 'json',
    schema: {
      type: 'object',
      properties: { risk: { type: 'string' } },
      required: ['risk'],
    },
  },
  scope: {
    objectPermissions: [
      { objectUniversalIdentifier: OPPORTUNITY_UID, canReadObjectRecords: true },
    ],
  },
});

const abortController = new AbortController();

const { text } = await ai.generate({
  input: `Draft a follow-up email to ${companyName}.`,
  onChunk: (chunk) => {
    // an AI SDK UIMessageChunk, such as { type: 'text-delta', delta }
  },
  signal: abortController.signal,
});

• تتبع المكالمة التشغيل عبر الاشتراك نفسه الذي تستخدمه streamConversation(): تشترك أولًا، وتنتظر حتى يصبح الاشتراك مباشرًا، ثم تبدأ التشغيل، لذلك لا يفوتها أي مقطع.
• المقاطع خاصة بالدردشة نفسها: مررها إلى readUIMessageStream() من حزمة ai لإنشاء الرسالة.
• يلغي signal المكالمة: يُرفض بخطأ الإلغاء ويغلق الدفق. يستمر التشغيل نفسه، ويُسجل كالمعتاد.
• بمجرد أن يصبح الدفق مباشرًا، لا يؤدي فشله إلا إلى إيقاف المقاطع: تظل المكالمة تُحل بنتيجة التشغيل، التي تُفوتر في كلتا الحالتين. تُرفض المكالمة عندما يفشل الاشتراك قبل أن يصبح مباشرًا، لذلك لا يبدأ التشغيل مطلقًا، أو عندما يُطلق onChunk خطأً.
• يتابع التطبيق عمليات التشغيل الخاصة به فقط، لذا يحتاج onChunk إلى رمز مميز للتطبيق.
• يتطلب "engines": { "twenty": ">=2.56.0" }.