Abilități și agenți

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 este un șir identificator unic pentru abilitate (se recomandă kebab-case).
• label este numele lizibil afișat în interfața cu utilizatorul (UI).
• content conține instrucțiunile abilității — acesta este textul pe care agentul AI îl folosește.
• icon (opțional) setează pictograma afișată în UI.
• description (opțional) oferă context suplimentar despre scopul abilității.

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 este un șir identificator unic pentru agent (se recomandă kebab-case).
• label este numele de afișare din interfața cu utilizatorul (UI).
• prompt conține promptul de sistem — acesta este textul de instrucțiuni care definește comportamentul agentului.
• description (opțional) oferă context despre ce face agentul.
• icon (opțional) setează pictograma afișată în UI.
• modelId (opțional) suprascrie modelul AI implicit utilizat de agent.
• responseFormat (opțional) stabilește formatul implicit al ieșirii agentului. Valoarea implicită este { type: 'text' } pentru text liber. Folosește { type: 'json', schema } pentru a impune ieșire JSON structurată. Un apel runAgent() sau un pas AI dintr-un flux de lucru poate solicita un format diferit, care are prioritate.
• roleUniversalIdentifier (opțional) leagă agentul de un rol definit de aplicația ta. Acel rol nu trebuie să acorde mai multe permisiuni decât rolul aplicației, altfel compilarea eșuează; consultați Roluri de agent.
• modelConfiguration (opțional) activează instrumentele native ale modelului, așa cum face pagina de setări a agentului: { webSearch: { enabled: true }, twitterSearch: { enabled: true } }. Fiecare instrument funcționează numai pe modelele care îl acceptă. Omiteți-l pentru a le menține dezactivate.
• isSystem (opțional, are implicit valoarea false) ascunde agentul din listele de agenți, la fel ca agenții pe care Twenty îi creează pentru pașii de IA din fluxurile de lucru. Schimbă doar ceea ce este afișat: agenții unei aplicații pot fi modificați numai prin intermediul aplicației, indiferent de valoarea acestei opțiuni.

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,
    },
  },
});

• Schema este un obiect plat: type al fiecărei proprietăți trebuie să fie un tip primitiv (string, number sau boolean). Obiectele îmbricate și tablourile nu sunt acceptate.
• description (opțional) pe fiecare proprietate ghidează modelul cu privire la ce să pună acolo.
• required (opțional) enumeră proprietățile pe care modelul trebuie să le returneze întotdeauna.
• additionalProperties: false (opțional) interzice orice proprietate care nu este declarată în 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 este în snake_case (litere mici, cifre și caractere de subliniere, începe cu o literă, maximum 32 de caractere) și este unic în spațiul de lucru. Acesta este prefixul numelor instrumentelor serverului.
• url trebuie să fie un URL HTTP sau HTTPS.
• connectionProvider (opțional) face referire la un furnizor de conexiune declarat de aceeași aplicație. Apelurile trimit tokenul de acces al conexiunii respective ca token Bearer. Omiteți-l pentru un server public.
• URL-ul nu se poate modifica într-o versiune ulterioară cât timp este asociat un furnizor de conexiune, astfel încât tokenurile să nu fie trimise niciodată către o altă gazdă.
• Spațiile de lucru pot dezactiva serverul; o versiune ulterioară a aplicației păstrează această opțiune.
• Necesită "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 este un șir sau o listă de 1 până la 100 de mesaje ({ role: 'user' | 'assistant', content: string }). Un mesaj user poate include și atașamente de fișiere (vezi mai jos). Pentru a menține o conversație, transmiteți un thread în loc să reluați dvs. rândurile anterioare.
• În mod implicit, apelul așteaptă agentul, care poate citi/actualiza înregistrări direct prin propriile sale instrumente — runAgent() se finalizează după ce execuția se încheie. Transmiteți waitForCompletion: false pentru a se finaliza de îndată ce începe execuția: status este apoi RUNNING și result: null, iar răspunsul ajunge în conversația threadId. O execuție care depășește 15 minute se finalizează, de asemenea, ca RUNNING.
• Agentul poate, de asemenea, să se întrerupă până când se modifică o înregistrare sau a trecut un anumit timp. runAgent() se rezolvă apoi cu success: true, status: 'SUSPENDED' și result: null; agentul continuă singur mai târziu, iar răspunsul său ajunge în conversația threadId. Un apel către un thread al cărui agent încă așteaptă eșuează până când acesta se finalizează.
• Fiecare apel este stocat împreună cu intrarea și starea sa, precum și cu răspunsul și utilizarea sa atunci când se finalizează, astfel încât să apară în execuțiile agentului. Fără un thread, un apel primește o conversație proprie: threadId o denumește, iar un apel ulterior nu o vede niciodată.
• O aplicație poate rula doar propriii săi agenți.
• Rolul implicit al aplicației trebuie să acorde indicatorul de permisiune AI — adaugă SystemPermissionFlag.AI la permissionFlagUniversalIdentifiers (sau setează canAccessAllTools: true). Fără acesta, runAgent() eșuează cu o eroare de permisiune.
• Setează un timeoutSeconds generos pentru funcția logică — rulările agentului pot dura câteva secunde.
• status este COMPLETED cu un result care nu este null atunci când execuția se finalizează fără a aștepta; SUSPENDED cu success: true și result: null cât timp așteaptă; RUNNING cu success: true și result: null atunci când apelul nu a așteptat execuția; FAILED cu success: false și error care conține motivul (de exemplu, când spațiul de lucru rămâne fără credite AI în timpul execuției).

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],
});

​

Trimiterea fișierelor cu un mesaj

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' }],
    },
  ],
});

• Doar mesajele user pot include atașamente. Acestea nu pot fi reprezentate într-un tur al asistentului, astfel încât runAgent() le respinge acolo, în loc să le elimine.
• Cel mult 10 atașamente per mesaj.
• fileId trebuie să indice un fișier încărcat complet în același spațiu de lucru, în folderul agent-chat. Orice altceva face ca apelul să eșueze, în loc să răspundă în mod discret fără fișier.

​

Solicitarea unui rezultat structurat

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'],
    },
  },
});

​

Continuarea unei conversații

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' },
});

• Cheile sunt limitate la aplicația și agentul dvs., astfel încât două aplicații nu partajează niciodată o conversație. Numai tokenurile de acces ale aplicației pot transmite un thread.
• input poate conține numai mesaje user: conversația conține deja răspunsurile agentului.
• additionalInstructions sunt oferite modelului numai pentru acest apel și nu sunt stocate, ceea ce este potrivit pentru instrucțiuni per solicitare, cum ar fi reguli de formatare sau un termen-limită. Acestea funcționează și fără un thread.
• Fiecare rulare este stocată ca un tur cu starea sa, inclusiv cele eșuate. Utilizarea sa este stocată când agentul revine, chiar dacă a rămas fără credite. O rulare eșuată nu face parte din conversație, astfel încât următorul apel nu o vede.
• Apelurile din același fir de discuție rulează pe rând: un al doilea apel așteaptă ca primul să se termine, astfel încât fiecare îl vede pe cel dinaintea sa.
• Când rândurile rulează ca membri diferiți (vedeți mai jos), fiecare vede numai textul rândurilor celorlalți, niciodată rezultatele instrumentelor lor, deoarece acestea au fost citite cu permisiunile altcuiva.

​

Rulare în numele unui membru al spațiului de lucru

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

• Un token fără niciun utilizator atașat poate denumi orice membru. O funcție logică rulează cu unul, la fel și tokenurile emise prin client_credentials sau dintr-o cheie API.
• Un token emis în numele unui utilizator, așa cum primește un front component, poate denumi doar propriul membru al acelui utilizator.

​

În urma unei conversații

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ăuturnId), credits-exhausted(răspunsul s-a oprit atunci când spațiul de lucru a expirat din credite),queue-updatedsaustream-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 UIMessages, 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" }.

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.

• 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.

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,
});

• 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" }.