The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
i18n - docs translations (#29505)
twenty-pr[bot]3673490e314a
diff --git a/packages/twenty-docs/ar/developers/extend/apps/logic/credits.mdx b/packages/twenty-docs/ar/developers/extend/apps/logic/credits.mdxindex f4dac42576c..1bcd970d78a 100644--- a/packages/twenty-docs/ar/developers/extend/apps/logic/credits.mdx+++ b/packages/twenty-docs/ar/developers/extend/apps/logic/credits.mdx@@ -133,7 +133,7 @@ await chargeCredits({## التحقق قبل الإنفاق-قد تنفد الاعتمادات من مساحة العمل. عند حدوث ذلك، تُرفَض دالتك قبل أن يبدأ تنفيذ التعليمات البرمجية الخاصة بك، ويتوقف عمل المنصة نفسها أيضًا: يعيد `runAgent` خطأً بدلًا من التشغيل، وترفض نقاط دخول الذكاء الاصطناعي الأخرى الطلب رفضًا تامًا. لا يشغّل `sendInboxMessage` أي نموذج ولا يضيف أي رسوم للذكاء الاصطناعي من تلقاء نفسه، رغم أن الدالة التي تستدعيه تُرفَض مثل أي دالة أخرى؛ ويُحتسب رد العضو مثل أي دور في الدردشة. تُعد خطافات إلغاء التثبيت وقطع الاتصال استثناءً وتعمل دائمًا، لذا يظل من الممكن إزالة التطبيق بشكل سليم. قد يفشل التنفيذ الذي يتمكن من المرور رغم ذلك في مرحلة متأخرة، عند استدعاء للمنصة لم يكتبه، إذا نفدت اعتمادات مساحة العمل أثناء التشغيل.+قد تنفد الاعتمادات من مساحة العمل. عند حدوث ذلك، تُرفَض دالتك قبل أن يبدأ تنفيذ التعليمات البرمجية الخاصة بك، ويتوقف عمل المنصة نفسها أيضًا: يعيد `runAgent` خطأً بدلًا من التشغيل، وترفض نقاط دخول الذكاء الاصطناعي الأخرى الطلب رفضًا تامًا. لا يشغّل `sendInboxMessage` أي نموذج ولا يضيف أي رسوم للذكاء الاصطناعي من تلقاء نفسه، رغم أن الدالة التي تستدعيه تُرفَض مثل أي دالة أخرى؛ ويُحتسب رد العضو مثل أي دور في الدردشة. تُعد خطافات إلغاء التثبيت وقطع الاتصال استثناءً وتعمل دائمًا، لذا يظل من الممكن إزالة التطبيق بشكل سليم. فالتنفيذ الذي لا يزال يفشل في وقت متأخر، على اسم المنصة لم يكتب إذا كان حيز العمل ينفد في منتصف المدة؛ `أي`. ولد" ثم حل مع "النجاح: خطأ" وسبب "الخطأ".اسأل أولًا:diff --git a/packages/twenty-docs/ar/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/ar/developers/extend/apps/logic/logic-functions.mdxindex 746ed506aec..f29fbc09533 100644--- a/packages/twenty-docs/ar/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/ar/developers/extend/apps/logic/logic-functions.mdx@@ -619,7 +619,7 @@ const asApplication = new RestApiClient({ runAs: 'application' });</Note>-تستخدم مساعدات SDK التي تصل إلى موارد تطبيقك الخاصة دائمًا صلاحيات الوصول الخاصة بها وتتجاهل `runAs`: [مخزن المفتاح-القيمة](/ar/developers/extend/apps/logic/key-value-store)، و[الاتصالات](/ar/developers/extend/apps/logic/connections)، و[قنوات المراسلة](/ar/developers/extend/apps/logic/messaging-channels)، و`runAgent`، و`getPublicAssetUrl`، و[تحصيل الأرصدة](/ar/developers/extend/apps/logic/credits).+تستخدم مساعدات SDK التي تصل إلى موارد تطبيقك الخاصة دائمًا صلاحيات الوصول الخاصة بها وتتجاهل `runAs`: [مخزن المفتاح-القيمة](/ar/developers/extend/apps/logic/key-value-store)، و[الاتصالات](/ar/developers/extend/apps/logic/connections)، و[قنوات المراسلة](/ar/developers/extend/apps/logic/messaging-channels)، و`runAgent`، و`getPublicAssetUrl`، و[تحصيل الأرصدة](/ar/developers/extend/apps/logic/credits). يتبع `ai.generate` العملاء الافتراضيين بدلاً من ذلك: إذ يتصرف بصفته الشخص الذي بدأ التشغيل، ضمن دور تطبيقك، أو بصفته تطبيقك عندما لا يكون هناك من فعل ذلك.#### إتاحة دالة كأداة ذكاء اصطناعي أو كإجراء ضمن سير العملdiff --git a/packages/twenty-docs/ar/developers/extend/apps/logic/skills-and-agents.mdx b/packages/twenty-docs/ar/developers/extend/apps/logic/skills-and-agents.mdxindex 4d968ab28b9..2de6fe36bb2 100644--- a/packages/twenty-docs/ar/developers/extend/apps/logic/skills-and-agents.mdx+++ b/packages/twenty-docs/ar/developers/extend/apps/logic/skills-and-agents.mdx@@ -144,7 +144,7 @@ export default defineMcpServer({```ts src/logic-functions/run-enricher.tsimport { runAgent } from 'twenty-sdk/logic-function';-const { threadId, status, result, error, success } = await runAgent({+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.',});@@ -304,6 +304,186 @@ const { result } = await runAgent({يقوم `runAgent()` بإطلاق استثناء عندما يتعذّر حل عضو مساحة العمل — مثل عضو غير معروف أو تمت إزالته، أو ليس لديه أي دور. لا يعود إطلاقًا إلى دور الوكيل نفسه، لأن ذلك سيمنح صلاحيات وصول أكثر مما طلبه المستدعي.</Warning>+### متابعة محادثة++يقرأ التطبيق المحادثات التي يجريها مع وكلائه عبر واجهة برمجة التطبيقات نفسها+المستخدمة للدردشة: تُرجع `listConversationMessages()` سجلها، وتُنتج+`streamConversation()` أحداثها المباشرة، رمزًا تلو الآخر. سمِّ+المحادثة باستخدام الوكيل ومفتاح `thread` الذي تمرره إلى `runAgent()`؛ ويمكنك+بدء متابعتها قبل أن يصل إليها التشغيل الأول.++```ts src/logic-functions/follow-conversation.ts+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" }`.++</Accordion>+<Accordion title="إنشاء بالذكاء الاصطناعي" description="استدعِ نموذجًا من دالة منطقية، من دون وكيل">++تستدعي `ai.generate()` نموذجًا من دالة منطقية. بخلاف+`runAgent()`، لا تحتاج إلى `defineAgent()`: تحمل المكالمة تعليماتها+الخاصة، ولا تفتح أي محادثة. استخدمها للمهام التي تُنفذ لمرة واحدة، مثل+التصنيف أو التلخيص أو الاستخراج.++```ts+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` (اختياري) للمكالمة استخدام قاعدة البيانات، كما هو موضح أدناه.++يُحل إلى `{ success, text, object, error, runId, usage }`:++* `text` هو رد الاستجابة النصية، ويكون `null` لاستجابة JSON.+* `object` هو نتيجة استجابة JSON، ويكون `null` بخلاف ذلك.+* يشرح `error` التشغيل الفاشل عندما تكون `success` هي `false`. يُحل التشغيل الذي يفشل+ بهذه الطريقة بدلًا من إطلاق خطأ؛ أما المكالمة التي لا يمكنها بدء تشغيل، مثل+ مكالمة ذات إدخال غير صالح، فتُطلق خطأً.+* يحدد `runId` التشغيل المسجل، مع نموذجه واستخدامه وأرصدته.+* `usage` هو `{ inputTokens, outputTokens }`: ما أنفقه التشغيل، بما في ذلك+ الخطوات التي انتهت قبل الإخفاق.++تتصرف المكالمة بصفتها الجهة التي أجرتها: العضو الذي ينتمي إليه رمز مميز بنطاق مستخدم،+وإلا فتطبيقك، وإلا مفتاح API. من دالة منطقية، تتبع+العملاء الافتراضيين: تتصرف بصفتها الشخص الذي شغّل التشغيل، أو بصفتها+تطبيقك عندما لا يكون هناك أحد. لا تتجاوز مطلقًا دور تطبيقك، ولا+يمكن لتطبيق من دون دور افتراضي استدعاؤها.++من دون `scope`، لا تقرأ المكالمة أي سجلات ولا تكتبها. للسماح لها باستخدام+قاعدة البيانات، مرر `scope`، مكتوبًا مثل أذونات الدور:++```ts+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 },+ ],+ },+});+```++النطاق لا يؤدي إلا إلى التضييق: فهو لا يمنح أي شيء لا يملكه المتصل بالفعل.++لعرض الرد أثناء كتابته، مرر `onChunk`. تُحل المكالمة مع ذلك+إلى النتيجة نفسها، بمجرد تمرير المقطع الأخير إلى `onChunk`. إذا لم تصل+نهاية الدفق مطلقًا، تتوقف عن الانتظار بمجرد وصول النتيجة ومرور 5 ثوانٍ+من دون مقطع جديد، وتظل تمرر كل مقطع تلقته حتى ذلك الحين:++```ts+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" }`.++<Note>+ تتطلب `ai.generate()` علامة إذن الذكاء الاصطناعي في الدور الافتراضي للتطبيق،+ مثل `runAgent()`.+</Note>+</Accordion><Accordion title="sendInboxMessage" description="بدء محادثة أو متابعتها في دردشات الأعضاء">diff --git a/packages/twenty-docs/ar/developers/extend/apps/logic/workflows.mdx b/packages/twenty-docs/ar/developers/extend/apps/logic/workflows.mdxindex 05444247ab8..c13d6a79f1c 100644--- a/packages/twenty-docs/ar/developers/extend/apps/logic/workflows.mdx+++ b/packages/twenty-docs/ar/developers/extend/apps/logic/workflows.mdx@@ -110,7 +110,13 @@ export default defineWorkflow({* تأخذ معاملات عامل التصفية قيم `ViewFilterOperand`، المُصدَّرة بواسطة `twenty-sdk/define`. تأخذ عوامل مجموعات التصفية قيماً نصية مثل `'AND'` أو `'OR'`.* تسمي حقول النموذج من النوع `RECORD` كائنها باستخدام `settings.objectUniversalIdentifier`. توفّر الحقول من النوعين `SELECT` و`MULTI_SELECT` خيارات حقل موجود من النوع نفسه، تمت تسميته باستخدام `settings.selectedFieldUniversalIdentifier`.* لتشغيل التعليمات البرمجية الخاصة بك، استخدم خطوة `LOGIC_FUNCTION`. خطوة التعليمات البرمجية في المنشئ غير متاحة.-* تشغّل خطوات `AI_AGENT` أحد وكلاء تطبيقك، المُسمّى باستخدام `agentUniversalIdentifier`، وتستخدم إعدادات خطوة أداة الإنشاء التالية: `prompt` و`responseFormat` و`humanInputInstructions` و`conversation` و`workspaceMemberId` للعضو الذي تجري محادثة الوكيل معه.+* تأتي خطوات `AI_AGENT` بنوعين لا يمكنك مزجهما:++ * لا تحتوي خطوة Generate على وكيل. تحمل `instructions` و`modelId` و`modelConfiguration` و`scope` الخاصة بها، وتعمل مرة واحدة: دون محادثة أو إدخال بشري أو انتظار.+ * تشغّل خطوة Agent أحد وكلاء تطبيقك، الذي يُسمّى باستخدام `agentUniversalIdentifier`، ويحمل تعليماته ونموذجه وأذوناته الخاصة. لا تقبل سوى خطوة Agent كلاً من `humanInputInstructions` و`conversation`.++ يأخذ كلا النوعين `prompt` و`responseFormat` الخاصين بالمنشئ، و`workspaceMemberId` لعضو مساحة العمل الذي يجري الوكيل معه محادثته.+* يقبل `scope` الخاص بخطوة `AI_AGENT` أذونات دور من دون هويته أو مسنداته على مستوى الصف: `canReadAllObjectRecords` و`objectPermissions` و`fieldPermissions` بحسب المعرّف الشامل، و`permissionFlagUniversalIdentifiers`، وما إلى ذلك. إنه يقيّد فقط: لا يمكن للذكاء الاصطناعي الخاص بالخطوة أبدًا الوصول إلى أكثر مما يمكن لمن يشغّل سير العمل الوصول إليه. يُفسَّر كدور تكون فيه علامات جميع السجلات معطّلة افتراضيًا: تُرفض إجراءات الكائنات وعلامات الأذونات التي لا يمنحها، وتظل كائنات النظام قابلة للقراءة ما لم يمنح المزيد، ويتبع الحقل الذي لا يدرجه كائنه. لا تحصل خطوة Generate التي لا تحتوي على `scope` على أي أدوات بيانات؛ وتعمل خطوة Agent بدور وكيلها.* لا تعمل خطوات البريد الإلكتروني والتقويم إلا إذا كان دور تطبيقك يتضمن علامة الإذن المطابقة: `SystemPermissionFlag.SEND_EMAIL_TOOL` لـ `SEND_EMAIL` و`DRAFT_EMAIL`، و`SystemPermissionFlag.CREATE_CALENDAR_EVENT_TOOL` لـ `CREATE_CALENDAR_EVENT`. تمنحها مساحة العمل عند تثبيت التطبيق، ويمكن للخطوة بعد ذلك استخدام أي حساب متصل في مساحة العمل، مثل سير عمل تم إنشاؤه في التطبيق.* معرّفات الحسابات المتصلة محلية لكل مساحة عمل، لذا لا تضمّن أحدها بصورة ثابتة. سمِّ الحساب بإحدى الطريقتين التاليتين:diff --git a/packages/twenty-docs/es/developers/extend/apps/logic/credits.mdx b/packages/twenty-docs/es/developers/extend/apps/logic/credits.mdxindex d66c660272c..2545eb31d0d 100644--- a/packages/twenty-docs/es/developers/extend/apps/logic/credits.mdx+++ b/packages/twenty-docs/es/developers/extend/apps/logic/credits.mdx@@ -133,7 +133,7 @@ Notas:## Comprobar antes de gastar-Un espacio de trabajo puede quedarse sin créditos. Cuando eso sucede, tu función se rechaza antes de que se inicie tu código, y el propio trabajo de la plataforma también se detiene: `runAgent` devuelve un error en lugar de ejecutarse, y los demás puntos de entrada de IA se rechazan directamente. `sendInboxMessage` no ejecuta ningún modelo ni añade ningún cargo de IA propio, aunque la función que lo llama se rechaza como cualquier otra; la respuesta de un miembro se cobra como cualquier turno de chat. Los hooks de desinstalación y desconexión son la excepción y siempre se ejecutan, por lo que una aplicación aún puede eliminarse correctamente. Una ejecución que logra pasar aún puede fallar más tarde, en una llamada de la plataforma que no escribió, si el espacio de trabajo se queda sin créditos durante la ejecución.+Un espacio de trabajo puede quedarse sin créditos. Cuando eso sucede, tu función se rechaza antes de que se inicie tu código, y el propio trabajo de la plataforma también se detiene: `runAgent` devuelve un error en lugar de ejecutarse, y los demás puntos de entrada de IA se rechazan directamente. `sendInboxMessage` no ejecuta ningún modelo ni añade ningún cargo de IA propio, aunque la función que lo llama se rechaza como cualquier otra; la respuesta de un miembro se cobra como cualquier turno de chat. Los hooks de desinstalación y desconexión son la excepción y siempre se ejecutan, por lo que una aplicación aún puede eliminarse correctamente. Una ejecución que se lleva a cabo puede todavía fallar tarde, en una llamada de plataforma que no escribía, si el espacio de trabajo se queda a medio plazo; `ai. enerate` luego resuelve con `éxito: falso` y la razón en `error`.Pregunta primero:diff --git a/packages/twenty-docs/es/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/es/developers/extend/apps/logic/logic-functions.mdxindex 6a7af3f3625..a05c7323ccd 100644--- a/packages/twenty-docs/es/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/es/developers/extend/apps/logic/logic-functions.mdx@@ -621,7 +621,7 @@ Comprueba `context.workspaceMemberId` cuando una función se comporta de forma d</Note>-Las utilidades del SDK que acceden a los recursos propios de tu aplicación siempre usan su acceso e ignoran `runAs`: el [almacén de clave-valor](/es/developers/extend/apps/logic/key-value-store), las [conexiones](/es/developers/extend/apps/logic/connections), los [canales de mensajería](/es/developers/extend/apps/logic/messaging-channels), `runAgent`, `getPublicAssetUrl` y el [cargo de créditos](/es/developers/extend/apps/logic/credits).+Las utilidades del SDK que acceden a los recursos propios de tu aplicación siempre usan su acceso e ignoran `runAs`: el [almacén de clave-valor](/es/developers/extend/apps/logic/key-value-store), las [conexiones](/es/developers/extend/apps/logic/connections), los [canales de mensajería](/es/developers/extend/apps/logic/messaging-channels), `runAgent`, `getPublicAssetUrl` y el [cargo de créditos](/es/developers/extend/apps/logic/credits). En cambio, `ai.generate` sigue a los clientes predeterminados: actúa como la persona que desencadenó la ejecución, dentro del rol de tu aplicación, o como tu aplicación cuando nadie lo hizo.#### Exponer una función como herramienta de IA o acción de flujo de trabajodiff --git a/packages/twenty-docs/es/developers/extend/apps/logic/skills-and-agents.mdx b/packages/twenty-docs/es/developers/extend/apps/logic/skills-and-agents.mdxindex 40f15c772eb..34c87803642 100644--- a/packages/twenty-docs/es/developers/extend/apps/logic/skills-and-agents.mdx+++ b/packages/twenty-docs/es/developers/extend/apps/logic/skills-and-agents.mdx@@ -145,7 +145,7 @@ a `defineAgent()` y pasa lo que quieres que procese como `input`:```ts src/logic-functions/run-enricher.tsimport { runAgent } from 'twenty-sdk/logic-function';-const { threadId, status, result, error, success } = await runAgent({+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.',});@@ -311,6 +311,188 @@ designar a ningún miembro.rol propio del agente, ya que eso otorgaría más acceso del que solicitó quien llama.</Warning>+### Siguiendo una conversación++Una aplicación lee las conversaciones que mantiene con sus agentes a través de la misma API+que el chat: `listConversationMessages()` devuelve su historia, y+`streamConversation()` produce sus eventos en vivo, token por token. Nombra la conversación+por el agente y la clave `hilo` que pasas a `runAgent()`; Tú+puedes empezar a seguirlo antes de que la primera ejecución llegue a él.++```ts src/logic-functions/follow-conversation.ts+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();+ }+}+```++* Los eventos son propios del chat: `stream-chunk` lleva un SDK+ `UIMessageChunk` y un `seq`, y notificaciones como `message-persisted`+ (un mensaje fue guardado: un miembro, o la respuesta, que lleva su ejecución+ `turnId`), `credits-exhausted` (la respuesta se detuvo cuando el espacio de trabajo corrió+ sin créditos), `queue-updated` o `stream-error` decir cuando+ para leer la historia de nuevo. Un `keepalive` viene una vez conectado, luego cada+ pocos segundos: lee la historia en la primera, ya que lo que pasó antes de+ está ahí.+* Para convertir chunks en mensajes como lo hace el chat, pipéalos en+ `readUIMessageStream()` del paquete `ai`.+* `listConversationMessages()` devuelve `{ mensajes, streamCatchup }`: los mensajes guardados+ como AI SDK `UIMessage`s, a medida que el chat los construye, y las porciones de+ una respuesta todavía fluyendo. Muestra esos trozos y luego omite trozos vivos cuyos+ `seq` es como máximo `streamCatchup.maxSeq`, ya que los repiten.+* `runAgent()` devuelve `runId`, el giro que abre la llamada: los mensajes de esa ejecución+ llevan como `metadata.turnId`. Una ejecución que espera en turnos posteriores de+ la conversación.+* El stream permanece abierto hasta que abortes su `señal` o `romper`, y arroja si+ la conexión cae: stream de nuevo para reanudar.+* Una aplicación sólo lee sus propias conversaciones. Turna un miembro abierto en otro lugar,+ como en el chat, muestra solo su texto en la historia, viva y en la siguiente carrera del agente+ : vive, sus otros trozos llegan como trozos+ `message-metadata`, así que `seq` permanece recolectado. Turna tu aplicación se ha ejecutado como un miembro+ (ver arriba) permanecen entera cuando lee por sí mismo.+* Requiere `"engines": { "twenty": ">=2.56.0" }`.++</Accordion>+<Accordion title="ai.generate" description="Llamar a un modelo desde una función lógica, sin un agente">++`ai.generate()` llama a un modelo desde una función lógica. A diferencia de+`runAgent()`, no necesita `defineAgent()`: la llamada lleva sus propias instrucciones+, y no abre ninguna conversación. Úselo para un trabajo de un solo tiro, como+clasificar, resumir o extraer.++```ts+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` es una cadena o una lista de mensajes `{ role: 'user' | 'assistant', content }`+ .+* `instructions` (opcional) añade las instrucciones del sistema de llamada.+* `modelId` (opcional) elige el modelo. Sin ella, la llamada utiliza el modelo predeterminado del espacio de trabajo+ .+* `responseFormat` (opcional) funciona como en `runAgent()`. Con+ `{ type: 'json', schema }`, el esquema se incluye en la propia solicitud al modelo, por lo que+ una respuesta JSON requiere una solicitud (más pasos de herramientas cuando un `scope` concede+ herramientas).+* `scope` (opcional) permite a la llamada utilizar la base de datos, como se describe a continuación.++Resuelve a `{ éxito, texto, objeto, error, runId, uso }`:++* `text` es la respuesta de un texto, y `null` para una respuesta JSON.+* `object` es el resultado de una respuesta JSON, y `null` de otra manera.+* `error` explica una ejecución fallida, cuando `success` es `false`. Una ejecución que falla+ resuelve esta manera en lugar de lanzarla; una llamada que no puede iniciar una ejecución, tal+ como una con entrada no válida, lanza.+* `runId` identifica la ejecución registrada, con su modelo, uso y créditos.+* `usage` es `{ inputTokens, outputTokens }`: lo que gastó la ejecución, incluyendo los pasos+ que terminaron antes de un fallo.++La llamada actúa como quien lo hizo: el miembro a un token con ámbito de usuario pertenece,+de lo contrario su aplicación, de lo contrario la clave API. Desde una función lógica+sigue a los clientes predeterminados: actúa como la persona que desencadenó la ejecución, o como+tu aplicación cuando nadie lo hizo. Nunca excede el rol de tu aplicación, y+una aplicación sin un rol predeterminado no puede llamarla.++Sin `scope`, la llamada lee y no escribe registros. Para permitir que use la base de datos+, pase un `scope`, escrito como los permisos de un rol:++```ts+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 },+ ],+ },+});+```++Un alcance sólo estrecha: no concede nada que el que llama no tenga ya.++Para mostrar la respuesta mientras está escrita, pase `onChunk`. La llamada todavía resuelve+al mismo resultado, una vez que el último fragmento fue entregado a `onChunk`. Si el final del streamformat@@0+nunca llega, deja de esperar una vez que el resultado está dentro y 5 s+pasa sin un nuevo trozo, y sigue entregando cada trozo recibido entonces:++```ts+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,+});+```++* La llamada sigue la ejecución a través de la misma suscripción que+ `streamConversation()`: se suscribe primero, espera hasta que la suscripción esté+ en vivo, luego comienza la ejecución, por lo que no pierde ningún chunk.+* Los trozos son los propios del chat: póngalos en `readUIMessageStream()` desde el paquete+ `ai` para construir el mensaje.+* `signal` aborta la llamada: rechaza con el error de aborto y cierra la transmisión+ . La ejecución en sí misma continúa, y se registra como de costumbre.+* Una vez que el stream está vivo, un fallo solo detiene los pedazos: la llamada+ todavía se resuelve con el resultado de la ejecución. que se facturan de cualquier manera. La llamada+ se rechaza cuando la suscripción falla antes de activarse, por lo que la ejecución nunca+ comienza, o cuando `onChunk` genera una excepción.+* Una aplicación sólo sigue sus propias ejecuciones, así que `onChunk` necesita un token de aplicación.+* Requiere `"engines": { "twenty": ">=2.56.0" }`.++<Note>+ `ai.generate()` requiere la bandera de permiso de IA en el rol predeterminado de la aplicación,+ como `runAgent()`.+</Note>+</Accordion><Accordion title="sendInboxMessage" description="Inicia o continúa una conversación en los chats de los miembros">diff --git a/packages/twenty-docs/es/developers/extend/apps/logic/workflows.mdx b/packages/twenty-docs/es/developers/extend/apps/logic/workflows.mdxindex 903bf5b58c1..5b5750cfb81 100644--- a/packages/twenty-docs/es/developers/extend/apps/logic/workflows.mdx+++ b/packages/twenty-docs/es/developers/extend/apps/logic/workflows.mdx@@ -110,7 +110,13 @@ Sus entradas coinciden con los pasos del [generador de flujos de trabajo](/es/us* Los operandos de filtro toman valores de `ViewFilterOperand`, exportados por `twenty-sdk/define`. Los operadores de grupo de filtros toman valores de cadena como `'AND'` u `'OR'`.* Los campos de formulario de tipo `RECORD` nombran su objeto con `settings.objectUniversalIdentifier`. Los campos de tipo `SELECT` y `MULTI_SELECT` ofrecen las opciones de un campo existente del mismo tipo, denominado con `settings.selectedFieldUniversalIdentifier`.* Para ejecutar tu propio código, usa un paso `LOGIC_FUNCTION`. El paso Code del constructor no está disponible.-* Los pasos de `AI_AGENT` ejecutan uno de los agentes de tu aplicación, denominado con `agentUniversalIdentifier`, y toman la configuración de pasos del constructor: `prompt`, `responseFormat`, `humanInputInstructions`, `conversation` y `workspaceMemberId` para el miembro con el que mantiene la conversación el agente.+* Los pasos de `AI_AGENT` son de dos tipos, que no se pueden mezclar:++ * Un paso Generate no tiene agente. Incluye sus propias `instructions`, `modelId`, `modelConfiguration` y `scope`, y se ejecuta una vez: sin conversación, sin intervención humana, sin espera.+ * Un paso Agent ejecuta uno de los agentes de tu aplicación, denominado con `agentUniversalIdentifier`, que incluye sus propias instrucciones, modelo y permisos. Solo un paso Agent acepta `humanInputInstructions` y `conversation`.++ Ambos tipos aceptan el `prompt` y el `responseFormat` del generador, y `workspaceMemberId` para el miembro con el que se mantiene la conversación del agente.+* El `scope` de un paso `AI_AGENT` acepta los permisos de un rol sin su identidad ni predicados a nivel de fila: `canReadAllObjectRecords`, `objectPermissions` y `fieldPermissions` por identificador universal, `permissionFlagUniversalIdentifiers`, etc. Solo restringe: la IA del paso nunca accede a más de lo que accede quien ejecuta el workflow. Se resuelve como un rol cuyos indicadores de todos los registros están desactivados de forma predeterminada: se deniegan las acciones de objetos y los indicadores de permisos que no concede, los objetos del sistema siguen siendo legibles a menos que conceda más, y un campo que no enumera sigue a su objeto. Un paso Generate sin un `scope` no obtiene herramientas de datos; un paso Agent se ejecuta con el rol de su agente.* Los pasos de correo electrónico y calendario se ejecutan solo si el rol de tu aplicación tiene el indicador de permiso correspondiente: `SystemPermissionFlag.SEND_EMAIL_TOOL` para `SEND_EMAIL` y `DRAFT_EMAIL`, `SystemPermissionFlag.CREATE_CALENDAR_EVENT_TOOL` para `CREATE_CALENDAR_EVENT`. El espacio de trabajo lo concede al instalar la aplicación, y el paso puede usar cualquier cuenta conectada en el espacio de trabajo, como un flujo de trabajo creado en la aplicación.* Los ID de las cuentas conectadas son locales para cada espacio de trabajo, así que no codifiques uno de forma fija. Asigne un nombre a la cuenta de una de estas dos formas:diff --git a/packages/twenty-docs/it/developers/extend/apps/logic/credits.mdx b/packages/twenty-docs/it/developers/extend/apps/logic/credits.mdxindex 89c6dfa903c..36e5d517792 100644--- a/packages/twenty-docs/it/developers/extend/apps/logic/credits.mdx+++ b/packages/twenty-docs/it/developers/extend/apps/logic/credits.mdx@@ -133,7 +133,7 @@ Note:## Verificare prima di spendere-Un workspace può esaurire i crediti. Quando ciò accade, la tua funzione viene rifiutata prima che il codice inizi e anche il lavoro della piattaforma si interrompe: `runAgent` restituisce un errore invece di essere eseguito e gli altri punti di ingresso dell'IA rifiutano del tutto. `sendInboxMessage` non esegue alcun modello e non aggiunge alcun addebito AI proprio, sebbene la funzione che la chiama venga rifiutata come qualsiasi altra; la risposta di un membro viene addebitata come qualsiasi turno di chat. Gli hook di disinstallazione e disconnessione costituiscono l'eccezione e vengono sempre eseguiti, quindi un'app può comunque essere rimossa correttamente. Un'esecuzione che riesce a passare può comunque fallire più tardi, durante una chiamata della piattaforma che non ha scritto, se lo spazio di lavoro esaurisce le risorse durante l'esecuzione.+Un workspace può esaurire i crediti. Quando ciò accade, la tua funzione viene rifiutata prima che il codice inizi e anche il lavoro della piattaforma si interrompe: `runAgent` restituisce un errore invece di essere eseguito e gli altri punti di ingresso dell'IA rifiutano del tutto. `sendInboxMessage` non esegue alcun modello e non aggiunge alcun addebito AI proprio, sebbene la funzione che la chiama venga rifiutata come qualsiasi altra; la risposta di un membro viene addebitata come qualsiasi turno di chat. Gli hook di disinstallazione e disconnessione costituiscono l'eccezione e vengono sempre eseguiti, quindi un'app può comunque essere rimossa correttamente. Un'esecuzione che arriva attraverso può ancora fallire tardi, su una chiamata di piattaforma non ha scritto, se il workspace termina a metà corso; `ai. enerate` poi risolve con `successo: false` e la ragione in `error`.Chiedi prima:diff --git a/packages/twenty-docs/it/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/it/developers/extend/apps/logic/logic-functions.mdxindex 10b77877537..86a48ea1e4b 100644--- a/packages/twenty-docs/it/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/it/developers/extend/apps/logic/logic-functions.mdx@@ -620,7 +620,7 @@ Controlla `context.workspaceMemberId` quando una funzione si comporta diversamen</Note>-Gli helper dell'SDK che accedono alle risorse della tua applicazione usano sempre il relativo accesso e ignorano `runAs`: l'[archivio chiave-valore](/it/developers/extend/apps/logic/key-value-store), le [connessioni](/it/developers/extend/apps/logic/connections), i [canali di messaggistica](/it/developers/extend/apps/logic/messaging-channels), `runAgent`, `getPublicAssetUrl` e l'[addebito dei crediti](/it/developers/extend/apps/logic/credits).+Gli helper dell'SDK che accedono alle risorse della tua applicazione usano sempre il relativo accesso e ignorano `runAs`: l'[archivio chiave-valore](/it/developers/extend/apps/logic/key-value-store), le [connessioni](/it/developers/extend/apps/logic/connections), i [canali di messaggistica](/it/developers/extend/apps/logic/messaging-channels), `runAgent`, `getPublicAssetUrl` e l'[addebito dei crediti](/it/developers/extend/apps/logic/credits). `ai.generate` segue invece i client predefiniti: agisce come la persona che ha avviato l'esecuzione, nell'ambito del ruolo della tua app, oppure come la tua app quando nessuno l'ha avviata.#### Esporre una funzione come strumento di IA o come azione del flusso di lavorodiff --git a/packages/twenty-docs/it/developers/extend/apps/logic/skills-and-agents.mdx b/packages/twenty-docs/it/developers/extend/apps/logic/skills-and-agents.mdxindex 715833ae07b..1f20fda9946 100644--- a/packages/twenty-docs/it/developers/extend/apps/logic/skills-and-agents.mdx+++ b/packages/twenty-docs/it/developers/extend/apps/logic/skills-and-agents.mdx@@ -144,7 +144,7 @@ Punti chiave:```ts src/logic-functions/run-enricher.tsimport { runAgent } from 'twenty-sdk/logic-function';-const { threadId, status, result, error, success } = await runAgent({+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.',});@@ -309,6 +309,188 @@ Qualsiasi altra cosa — una semplice sessione utente, una chiave API senza un truolo proprio dell'agente, poiché ciò concederebbe più accesso di quanto richiesto dal chiamante.</Warning>+### Seguire una conversazione++Un'app legge le conversazioni che intrattiene con i propri agenti tramite la stessa API+della chat: `listConversationMessages()` restituisce la relativa cronologia e+`streamConversation()` produce i relativi eventi in tempo reale, token per token. Assegna un nome alla+conversazione tramite l'agente e la chiave `thread` che passi a `runAgent()`; puoi+iniziare a seguirla prima che la prima esecuzione la raggiunga.++```ts src/logic-functions/follow-conversation.ts+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();+ }+}+```++* Gli eventi sono quelli della chat stessa: `stream-chunk` contiene un+ `UIMessageChunk` dell'AI SDK e un `seq`, e notifiche quali `message-persisted`+ (un messaggio è stato salvato: quello di un membro o la risposta, che contiene il+ proprio `turnId`), `credits-exhausted` (la risposta si è interrotta quando lo spazio di lavoro ha+ esaurito i crediti), `queue-updated` o `stream-error` indicano quando+ leggere nuovamente la cronologia. Un `keepalive` arriva una volta stabilita la connessione, poi ogni+ pochi secondi: leggi la cronologia al primo, poiché ciò che è accaduto prima+ si trova lì.+* Per trasformare i chunk in messaggi come fa la chat, inviali a+ `readUIMessageStream()` dal pacchetto `ai`.+* `listConversationMessages()` restituisce `{ messages, streamCatchup }`: i messaggi+ salvati come `UIMessage` dell'AI SDK, come li costruisce la chat, e i chunk di+ una risposta ancora in streaming. Mostra tali chunk, poi ignora i chunk in tempo reale il cui+ `seq` è al massimo `streamCatchup.maxSeq`, poiché li ripetono.+* `runAgent()` restituisce `runId`, il turno aperto dalla chiamata: i messaggi di tale esecuzione+ lo contengono come `metadata.turnId`. Un'esecuzione in attesa prosegue nei turni successivi+ della conversazione.+* Lo stream rimane aperto finché non interrompi il relativo `signal` o usi `break`, e genera un errore se+ la connessione cade: avvia nuovamente lo streaming per riprendere.+* Un'app legge solo le proprie conversazioni. I turni che un membro ha aperto altrove,+ ad esempio nella chat, mostrano solo il proprio testo, nella cronologia, in tempo reale e nella+ successiva esecuzione dell'agente: in tempo reale, gli altri chunk arrivano come chunk+ `message-metadata` vuoti, così `seq` rimane senza lacune. I turni eseguiti dalla tua app come+ membro (vedi sopra) rimangono integri quando li legge autonomamente.+* Richiede `"engines": { "twenty": ">=2.56.0" }`.++</Accordion>+<Accordion title="ai.generate" description="Chiama un modello da una funzione logica, senza un agente">++`ai.generate()` chiama un modello da una funzione logica. A differenza di+`runAgent()`, non ha bisogno di `defineAgent()`: la chiamata porta le proprie istruzioni+e non apre conversazioni. Usalo per un lavoro one-shot come la classificazione, la sintesi o l'estrazione di+.++```ts+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` è una stringa o un elenco di messaggi+ `{ role: 'user' | 'assistant', content }`.+* `instructions` (opzionale) aggiunge le istruzioni di sistema del chiamante.+* `modelId` (opzionale) sceglie il modello. Senza di esso, la chiamata utilizza il modello predefinito del workspace+ .+* `responseFormat` (opzionale) funziona come in `runAgent()`. Con+ `{ type: 'json', schema }`, lo schema va sulla richiesta del modello stesso, così+ una risposta JSON richiede una richiesta (più passaggi dello strumento quando un `scope` concede strumenti+ ).+* `scope` (opzionale) consente alla chiamata di utilizzare il database, come descritto di seguito.++Si risolve a `{ successo, testo, oggetto, errore, runId, use }`:++* `text` è la risposta di una risposta testuale e `null` per una JSON.+* `object` è il risultato di una risposta JSON, e `null` altrimenti.+* `error` spiega un'esecuzione fallita, quando `success` è `false`. Una corsa che fallisce+ risolve questo modo piuttosto che lanciare; una chiamata che non può avviare un'esecuzione, come+ come una con input non valido, lancia.+* `runId` identifica l'esecuzione registrata, con il suo modello, utilizzo e crediti.+* `usage` è `{ inputTokens, outputTokens }`: quello che è stato speso, inclusi i passaggi+ che sono terminati prima di un fallimento.++La chiamata agisce come chi lo ha fatto: il membro a cui appartiene un token di ambito utente,+altrimenti la tua applicazione, altrimenti la chiave API. Da una funzione logica+segue i client predefiniti: agisce come la persona che ha innescato l'esecuzione, o come+la tua applicazione quando nessuno lo ha fatto. Non supera mai il ruolo della tua applicazione, e+un'applicazione senza un ruolo predefinito non può chiamarla.++Senza `scope`, la chiamata legge e non scrive alcun record. Per permettergli di utilizzare il database+, passare un `scope`, scritto come permessi di un ruolo:++```ts+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 },+ ],+ },+});+```++Un ambito si restringe soltanto: non concede nulla che il chiamante non abbia già.++Per mostrare la risposta mentre è scritta, passare `onChunk`. La chiamata risolve ancora+allo stesso risultato, una volta che l'ultimo pezzo è stato consegnato a `onChunk`. Se la fine del flusso+non arriva mai, smette di aspettare una volta che il risultato è in e 5 s+passare senza un nuovo chunk, e ancora consegna su ogni pezzo ricevuto da allora:++```ts+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,+});+```++* La chiamata segue la corsa attraverso lo stesso abbonamento di+ `streamConversation()`: si iscrive prima, aspetta fino a quando l'abbonamento è+ live, poi inizia la run, quindi non manca nessun chunk.+* I chunks sono di proprietà della chat: li incanalano in `readUIMessageStream()` dal pacchetto `ai`+ per costruire il messaggio.+* `signal` interrompe la chiamata: rifiuta con l'errore di abort e chiude il flusso+ . La corsa stessa continua, e viene registrata come al solito.+* Una volta che lo stream è live, un guasto di esso ferma solo i chunk: la chiamata+ si risolve ancora con il risultato della corsa, che è fatturata in entrambi i modi. La chiamata+ rifiuta quando l'abbonamento fallisce prima che vada in diretta, quindi la corsa non+ inizia mai, o quando `onChunk` lancia.+* Un'app segue solo le sue funzioni, quindi `onChunk` ha bisogno di un token di app.+* Richiede `"engines": { "twenty": ">=2.56.0" }`.++<Note>+ `ai.generate()` richiede il flag dei permessi AI sul ruolo predefinito dell'app,+ come `runAgent()`.+</Note>+</Accordion><Accordion title="sendInboxMessage" description="Avvia o continua una conversazione nelle chat dei membri">diff --git a/packages/twenty-docs/it/developers/extend/apps/logic/workflows.mdx b/packages/twenty-docs/it/developers/extend/apps/logic/workflows.mdxindex e135c52ba6c..a7f2aae6fb4 100644--- a/packages/twenty-docs/it/developers/extend/apps/logic/workflows.mdx+++ b/packages/twenty-docs/it/developers/extend/apps/logic/workflows.mdx@@ -110,7 +110,13 @@ I relativi input corrispondono ai passaggi del [generatore di workflow](/it/user* Gli operandi di filtro accettano valori `ViewFilterOperand`, esportati da `twenty-sdk/define`. Gli operatori del gruppo di filtri accettano valori stringa come `'AND'` o `'OR'`.* I campi del modulo di tipo `RECORD` denominano il proprio oggetto con `settings.objectUniversalIdentifier`. I campi di tipo `SELECT` e `MULTI_SELECT` offrono le opzioni di un campo esistente dello stesso tipo, denominato con `settings.selectedFieldUniversalIdentifier`.* Per eseguire il tuo codice, usa un passaggio `LOGIC_FUNCTION`. Il passaggio Code del builder non è disponibile.-* I passaggi `AI_AGENT` eseguono uno degli agenti della tua app, denominato con `agentUniversalIdentifier`, e adottano le impostazioni del passaggio del builder: `prompt`, `responseFormat`, `humanInputInstructions`, `conversation` e `workspaceMemberId` per il membro con cui si svolge la conversazione dell'agente.+* I passaggi `AI_AGENT` sono di due tipi, che non puoi combinare:++ * Un passaggio Generate non ha un agente. Include le proprie `instructions`, `modelId`, `modelConfiguration` e `scope` e viene eseguito una sola volta: nessuna conversazione, nessun input umano, nessuna attesa.+ * Un passaggio Agent esegue uno degli agenti della tua app, denominato con `agentUniversalIdentifier`, che include le proprie istruzioni, il modello e le autorizzazioni. Solo un passaggio Agent accetta `humanInputInstructions` e `conversation`.++ Entrambi i tipi accettano `prompt` e `responseFormat` del builder, nonché `workspaceMemberId` per il membro con cui conversa l'agente.+* Lo `scope` di un passaggio `AI_AGENT` accetta le autorizzazioni di un ruolo senza la relativa identità o i predicati a livello di riga: `canReadAllObjectRecords`, `objectPermissions` e `fieldPermissions` per identificatore universale, `permissionFlagUniversalIdentifiers` e così via. Limita soltanto: l'IA del passaggio non accede mai a più dati di chi esegue il workflow. Viene risolto come un ruolo i cui flag per tutti i record sono disattivati per impostazione predefinita: le azioni sugli oggetti e i flag di autorizzazione che non concede vengono negati, gli oggetti di sistema rimangono leggibili a meno che non conceda di più, e un campo che non elenca segue il relativo oggetto. Un passaggio Generate senza uno `scope` non ottiene strumenti per i dati; un passaggio Agent viene eseguito con il ruolo del relativo agente.* I passaggi email e calendario vengono eseguiti solo se il ruolo della tua app dispone del flag di autorizzazione corrispondente: `SystemPermissionFlag.SEND_EMAIL_TOOL` per `SEND_EMAIL` e `DRAFT_EMAIL`, `SystemPermissionFlag.CREATE_CALENDAR_EVENT_TOOL` per `CREATE_CALENDAR_EVENT`. Il workspace lo concede installando l'app e il passaggio può quindi usare qualsiasi account connesso nel workspace, come un workflow creato nell'app.* Gli ID degli account connessi sono locali a ogni spazio di lavoro, quindi non codificarne uno in modo fisso. Specifica l'account in uno dei due modi seguenti:diff --git a/packages/twenty-docs/ro/developers/extend/apps/logic/credits.mdx b/packages/twenty-docs/ro/developers/extend/apps/logic/credits.mdxindex c9f4102857c..039b3c595ae 100644--- a/packages/twenty-docs/ro/developers/extend/apps/logic/credits.mdx+++ b/packages/twenty-docs/ro/developers/extend/apps/logic/credits.mdx@@ -133,7 +133,7 @@ Notițe:## Verificarea înainte de a cheltui-Un spațiu de lucru poate rămâne fără credite. Când se întâmplă acest lucru, funcția ta este refuzată înainte ca codul tău să pornească, iar activitatea proprie a platformei se oprește și ea: `runAgent` returnează o eroare în loc să ruleze, iar celelalte puncte de intrare AI refuză direct. `sendInboxMessage` nu rulează niciun model și nu adaugă niciun cost AI propriu, deși apelul de funcție care o invocă este facturat ca oricare altul; răspunsul unui membru este facturat ca orice tur de chat. Hookurile de dezinstalare și deconectare reprezintă excepția și rulează întotdeauna, astfel încât o aplicație să poată fi eliminată în continuare în mod curat. O execuție care reușește să treacă poate totuși eșua târziu, la un apel al platformei pe care nu l-a scris, dacă spațiul de lucru rămâne fără credite în timpul rulării.+Un spațiu de lucru poate rămâne fără credite. Când se întâmplă acest lucru, funcția ta este refuzată înainte ca codul tău să pornească, iar activitatea proprie a platformei se oprește și ea: `runAgent` returnează o eroare în loc să ruleze, iar celelalte puncte de intrare AI refuză direct. `sendInboxMessage` nu rulează niciun model și nu adaugă niciun cost AI propriu, deși apelul de funcție care o invocă este facturat ca oricare altul; răspunsul unui membru este facturat ca orice tur de chat. Hookurile de dezinstalare și deconectare reprezintă excepția și rulează întotdeauna, astfel încât o aplicație să poată fi eliminată în continuare în mod curat. O execuție care se termină poate totuși să eșueze târziu, pe un apel pe platformă nu a scris, dacă spațiul de lucru se termină la mijloc; `ai. enerate` apoi rezolvă cu `succes: false` şi motivul din `error`.Întrebați mai întâi:diff --git a/packages/twenty-docs/ro/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/ro/developers/extend/apps/logic/logic-functions.mdxindex 4bc1eb376cf..23728ddb591 100644--- a/packages/twenty-docs/ro/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/ro/developers/extend/apps/logic/logic-functions.mdx@@ -621,7 +621,7 @@ Verificați `context.workspaceMemberId` atunci când o funcție se comportă dif</Note>-Funcțiile ajutătoare SDK care accesează propriile resurse ale aplicației dvs. folosesc întotdeauna accesul acesteia și ignoră `runAs`: [stocarea cheie-valoare](/ro/developers/extend/apps/logic/key-value-store), [conexiunile](/ro/developers/extend/apps/logic/connections), [canalele de mesagerie](/ro/developers/extend/apps/logic/messaging-channels), `runAgent`, `getPublicAssetUrl` și [taxarea creditelor](/ro/developers/extend/apps/logic/credits).+Funcțiile ajutătoare SDK care accesează propriile resurse ale aplicației dvs. folosesc întotdeauna accesul acesteia și ignoră `runAs`: [stocarea cheie-valoare](/ro/developers/extend/apps/logic/key-value-store), [conexiunile](/ro/developers/extend/apps/logic/connections), [canalele de mesagerie](/ro/developers/extend/apps/logic/messaging-channels), `runAgent`, `getPublicAssetUrl` și [taxarea creditelor](/ro/developers/extend/apps/logic/credits). `ai.generate` urmează în schimb clienții impliciți: acționează ca persoana care a declanșat execuția, în cadrul rolului aplicației tale, sau ca aplicația ta atunci când nu a făcut-o nimeni.#### Expunerea unei funcții ca instrument AI sau ca acțiune în fluxul de lucrudiff --git a/packages/twenty-docs/ro/developers/extend/apps/logic/skills-and-agents.mdx b/packages/twenty-docs/ro/developers/extend/apps/logic/skills-and-agents.mdxindex 7da7c6bce73..f1bf3d6959f 100644--- a/packages/twenty-docs/ro/developers/extend/apps/logic/skills-and-agents.mdx+++ b/packages/twenty-docs/ro/developers/extend/apps/logic/skills-and-agents.mdx@@ -145,7 +145,7 @@ către `defineAgent()` și transmite ca `input` ceea ce vrei să proceseze:```ts src/logic-functions/run-enricher.tsimport { runAgent } from 'twenty-sdk/logic-function';-const { threadId, status, result, error, success } = await runAgent({+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.',});@@ -310,6 +310,186 @@ Orice altceva — o sesiune simplă de utilizator, o cheie API fără un token apropriul rol al agentului, deoarece acest lucru ar acorda mai mult acces decât a cerut apelantul.</Warning>+### În urma unei conversații++O aplicație citește conversațiile pe care le deține cu agenții săi prin intermediul aceluiași API+ca și chat: `listConversationMessages()` returnează istoricul ei, și+`streamConversation()` generează evenimentele sale live, token by token. Numește conversația+de către agent și cheia `thread` pe care o treci la \`runAgent()"; tu+îl poți urmări înainte ca prima execuție să ajungă la el.++```ts src/logic-functions/follow-conversation.ts+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();+ }+}+```++* Evenimentele sunt ale chatului: `stream-chunk` transportă un AI SDK+ `UIMessageChunk` şi un `seq`, şi notificări precum `mesaj` persistă` (un mesaj a fost salvat: un membru sau răspunsul, care transportă contul său`turnId`), `credits-exhausted`(răspunsul s-a oprit atunci când spațiul de lucru a expirat+ din credite),`queue-updated`sau`stream-error\` spune când+ să citească din nou istoria. Un "keepalive" vine odată conectat, apoi la fiecare+ câteva secunde: citește istoria din primul, de când ce s-a întâmplat înainte de+ este acolo.+* Pentru a transforma bucățile în mesaje cum face chatul, țineți-le în+ `readUIMessageStream()` din pachetul `ai`.+* `listConversationMessages()` returnează `{ mesaje, streamCatchup }`: mesajele salvate+ ca `UIMessage`s, pe măsură ce chat-ul le construiește, și bucățile de+ sunt încă în mișcare. Arată acele chunks, apoi sari peste chunkurile în direct care+ `seq` este cel mult `streamCatchup.maxSeq`, din moment ce le repetă.+* `runAgent()` returnează `runId`, apelul se deschis: mesajele care rulează+ îl poartă ca `metadata.turnId`. O cursă care așteaptă să se îndrepte mai târziu de conversația de la+ .+* Fluxul rămâne deschis până când renunțați la `semnal` sau `break`, și aruncă dacă+ picăturile de conexiune: stream-ul pentru a relua.+* O aplicație citește doar propriile sale conversații. Întoarce un membru deschis în altă parte,+ cum ar fi în chat, arată doar textul în istorie, live și în următoarea rulare a agentului+ : live, celelalte bucăți de joc sosesc sub formă de bucăți goale+ 'mesagerie metadata', astfel încât `seq` rămâne nesigur. Transformă aplicația ta rulată ca membru+ (a se vedea mai sus) rămâne întreagă atunci când citește de unul singur.+* Necesită `"motoare": { "twenty": ">=2.56.0" }`.++</Accordion>+<Accordion title="ai.generate" description="Apelați un model dintr-o funcție logică, fără un agent">++`ai.generate()` apelează un model dintr-o funcţie logică. Spre deosebire de+`runAgent()`, nu are nevoie de `defineAgent()`: apelul are propriile instrucțiuni+și nu deschide nicio conversație. Folosiți-l pentru o singură împuşcătură, cum ar fi+clasificare, sumarizare sau extracție.++```ts+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` este un șir sau o listă de mesaje `{ role: 'user' | 'assistant', content }`+ .+* `instrucțiuni` (opțional) adaugă instrucțiunile sistemului apelantului.+* `modelId` (opţional) alege modelul. Fără el, apelul folosește modelul implicit al spațiului de lucru+ .+* `responseFormat` (opţional) funcţionează ca în `runAgent()`. Cu+ `{ type: 'json', schema }", schema merge pe cererea modelului în sine, prin urmare+ un răspuns JSON face o cerere (plus unealtă pași atunci când un `scope\` acordă instrumente+ ).+* `scope` (opţional) permite apelării să utilizeze baza de date, aşa cum este descrisă mai jos.++Acesta se rezolvă pentru `{ success, text, obiect, eroare, runId, usage }`:++* `text` este răspunsul unui text şi `null` pentru unul JSON.+* `object` este rezultatul unui răspuns JSON şi `null` altfel.+* `error` explică o rulare eșuată, când `succes` este `false`. O execuție care eșuează+ rezolvă în acest fel în loc să aruncați; un apel care nu poate începe o rulare, cum ar fi+ ca unul cu intrare nevalidă, aruncă.+* `runId` identifică rularea înregistrată, cu modelul, utilizarea şi creditele sale.+* `usage` este `{ inputTokens, outputTokens }`: what the run cheltuit, including the+ steps that finished before a fail.++Apelul acționează ca oricine a făcut-o: membrului îi aparține un token scris de utilizator,+în caz contrar, aplicația dvs., în caz contrar cheia API. Dintr-o funcție logică+urmează clienții implici: acționează ca persoana care a declanșat rularea, sau ca+aplicația ta atunci când nimeni nu a făcut. Nu depășește niciodată rolul aplicației tale, iar+o aplicație fără un rol implicit nu o poate apela.++Fără `scope`, apelul citeşte şi nu scrie nici o înregistrare. Pentru a o lăsa să folosească baza de date+pasează un `scope`, scris ca permisiunile unui rol:++```ts+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 },+ ],+ },+});+```++O sferă de aplicare se limitează: nu acordă nimic apelantului care nu are deja un telefon.++Pentru a afișa răspunsul în timp ce este scris, treceți `onChunk`. Apelul încă se rezolvă cu+în acelaşi rezultat, odată ce ultimul chunk a fost înmânat lui `onChunk`. Dacă runda+nu soseşte niciodată, se opreşte să aştepte odată ce rezultatul este în şi 5 s+trece fără un nou chunk, și chiar mâini peste fiecare bucată primită până atunci:++```ts+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,+});+```++* Apelul se derulează prin același abonament ca+ `streamConversation()`: se abonează mai întâi, așteaptă până când abonamentul este+ live, apoi începe rularea, astfel încât să nu piardă chunk.+* Bucățile sunt ale chat-ului: țineți-le în `readUIMessageStream()` din pachetul+ pentru a construi mesajul.+* `semnal` anulează apelul: acesta respinge cu eroarea de abortare și închide fluxul+ Drumul în sine continuă şi este înregistrat ca de obicei.+* Odată ce fluxul este live, un eşec al acestuia opreşte doar bucăţile: apelul+ încă se rezolvă cu rezultatul run-ului. care este facturat în ambele sensuri. Apelul+ respinge atunci când abonamentul eșuează înainte de a trece în direct, astfel încât nu mai începe niciodată+ sau când `onChunk` arată.+* O aplicație urmează doar propriile sale execuții, astfel încât `onChunk` are nevoie de un token de aplicație.+* Necesită `"motoare": { "twenty": ">=2.56.0" }`.++<Note>+ `ai.generate()` necesită steagul de permisiune AI de pe rolul implicit al aplicației,+ like `runAgent()`.+</Note>+</Accordion><Accordion title="sendInboxMessage" description="Începeți sau continuați o conversație în chaturile membrilor">diff --git a/packages/twenty-docs/ro/developers/extend/apps/logic/workflows.mdx b/packages/twenty-docs/ro/developers/extend/apps/logic/workflows.mdxindex d07b7a8e495..5b51e4c2fdd 100644--- a/packages/twenty-docs/ro/developers/extend/apps/logic/workflows.mdx+++ b/packages/twenty-docs/ro/developers/extend/apps/logic/workflows.mdx@@ -110,7 +110,13 @@ Intrările lor corespund pașilor din [constructorul de fluxuri de lucru](/ro/us* Operanzii de filtrare acceptă valori `ViewFilterOperand`, exportate de `twenty-sdk/define`. Operatorii grupului de filtre acceptă valori șir de caractere precum `'AND'` sau `'OR'`.* Câmpurile de formular de tip `RECORD` își denumesc obiectul cu `settings.objectUniversalIdentifier`. Câmpurile de tip `SELECT` și `MULTI_SELECT` oferă opțiunile unui câmp existent de același tip, denumit cu `settings.selectedFieldUniversalIdentifier`.* Pentru a executa propriul cod, utilizați un pas `LOGIC_FUNCTION`. Pasul Code al generatorului nu este disponibil.-* Pașii `AI_AGENT` rulează unul dintre agenții aplicației tale, denumit cu `agentUniversalIdentifier`, și preiau setările pasului din constructor: `prompt`, `responseFormat`, `humanInputInstructions`, `conversation` și `workspaceMemberId` pentru membrul cu care agentul poartă conversația.+* Pașii `AI_AGENT` sunt de două tipuri, pe care nu îi puteți combina:++ * Un pas Generate nu are agent. Acesta are propriile `instructions`, `modelId`, `modelConfiguration` și `scope` și se execută o singură dată: fără conversație, fără intervenție umană, fără așteptare.+ * Un pas Agent execută unul dintre agenții aplicației dvs., denumit cu `agentUniversalIdentifier`, care are propriile instrucțiuni, propriul model și propriile permisiuni. Doar un pas Agent primește `humanInputInstructions` și `conversation`.++ Ambele tipuri primesc `prompt` și `responseFormat` ale constructorului, precum și `workspaceMemberId` pentru membrul cu care agentul poartă conversația.+* `scope` al unui pas `AI_AGENT` primește permisiunile unui rol fără identitatea acestuia sau predicatele la nivel de rând: `canReadAllObjectRecords`, `objectPermissions` și `fieldPermissions` după identificator universal, `permissionFlagUniversalIdentifiers` și așa mai departe. Acesta doar restricționează: AI-ul pasului nu accesează niciodată mai mult decât persoana care rulează fluxul de lucru. Se rezolvă ca un rol ale cărui indicatori pentru toate înregistrările sunt dezactivați implicit: acțiunile asupra obiectelor și indicatorii de permisiune pe care nu îi acordă sunt refuzați, obiectele de sistem rămân lizibile, cu excepția cazului în care acordă mai multe permisiuni, iar un câmp pe care nu îl listează urmează obiectul său. Un pas Generate fără un `scope` nu primește instrumente de date; un pas Agent rulează cu rolul agentului său.* Pașii de e-mail și calendar rulează numai dacă rolul aplicației dvs. are indicatorul de permisiune corespunzător: `SystemPermissionFlag.SEND_EMAIL_TOOL` pentru `SEND_EMAIL` și `DRAFT_EMAIL`, `SystemPermissionFlag.CREATE_CALENDAR_EVENT_TOOL` pentru `CREATE_CALENDAR_EVENT`. Spațiul de lucru o acordă prin instalarea aplicației, iar pasul poate utiliza apoi orice cont conectat din spațiul de lucru, asemenea unui flux de lucru creat în aplicație.* id-urile conturilor conectate sunt locale pentru fiecare spațiu de lucru, deci nu includeți unul direct în cod. Denumiți contul în unul dintre următoarele două moduri: