Skill e agenti

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 è una stringa identificativa univoca per la skill (kebab-case consigliato).
• label è il nome di visualizzazione leggibile mostrato nell’UI.
• content contiene le istruzioni della skill — questo è il testo che l’agente IA utilizza.
• icon (opzionale) imposta l’icona visualizzata nell’UI.
• description (opzionale) fornisce contesto aggiuntivo sullo scopo della skill.

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 è la stringa identificativa univoca dell’agente (kebab-case consigliato).
• label è il nome visualizzato nell’UI.
• prompt è il prompt di sistema che definisce il comportamento dell’agente.
• description (opzionale) fornisce contesto su ciò che fa l’agente.
• icon (opzionale) imposta l’icona visualizzata nell’UI.
• modelId (opzionale) sostituisce il modello di IA predefinito utilizzato dall’agente.
• responseFormat (facoltativo) imposta il formato di output predefinito dell’agente. Per il testo in formato libero, il valore predefinito è { type: 'text' }. Usa { type: 'json', schema } per forzare un output JSON strutturato. Una chiamata a runAgent() o un passaggio AI di un workflow può richiedere un formato diverso, che ha la precedenza.
• roleUniversalIdentifier (facoltativo) associa l’agente a un ruolo definito dalla tua app. Quel ruolo non deve concedere più del ruolo dell’applicazione, altrimenti la build non riesce; vedi Ruoli degli agenti.
• modelConfiguration (facoltativo) attiva gli strumenti nativi del modello, come fa la pagina delle impostazioni dell’agente: { webSearch: { enabled: true }, twitterSearch: { enabled: true } }. Ogni strumento funziona solo con i modelli che lo supportano. Omettilo per mantenerli disattivati.
• isSystem (facoltativo, il valore predefinito è false) nasconde l’agente dagli elenchi di agenti, come gli agenti che Twenty crea per i passaggi IA dei workflow. Modifica solo ciò che viene visualizzato: gli agenti di un’app possono essere modificati solo tramite l’app, indipendentemente da quanto indica questo flag.

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

• Lo schema è un oggetto piatto: il type di ogni proprietà deve essere un primitivo (string, number o boolean). Gli oggetti annidati e gli array non sono supportati.
• description (facoltativo) su ogni proprietà guida il modello su cosa inserire lì.
• required (facoltativo) elenca le proprietà che il modello deve sempre restituire.
• additionalProperties: false (facoltativo) vieta qualsiasi proprietà non dichiarata in 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 è in snake_case (lettere minuscole, cifre e trattini bassi, inizia con una lettera, massimo 32 caratteri) ed è univoco nello spazio di lavoro. Funge da prefisso per i nomi degli strumenti del server.
• url deve essere un URL HTTP o HTTPS.
• connectionProvider (facoltativo) fa riferimento a un provider di connessione dichiarato dalla stessa app. Le chiamate inviano il token di accesso di tale connessione come token Bearer. Omettilo per un server pubblico.
• L’URL non può cambiare in una versione successiva quando è collegato un provider di connessione, affinché i token non vengano mai inviati a un altro host.
• Gli spazi di lavoro possono disattivare il server; una versione successiva dell’app mantiene questa scelta.
• Richiede "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 è una stringa o un elenco da 1 a 100 messaggi ({ role: 'user' | 'assistant', content: string }). Un messaggio user può anche includere allegati di file (vedi sotto). Per mantenere una conversazione, passa un thread invece di riprodurre tu stesso i turni precedenti.
• Per impostazione predefinita, la chiamata attende l’agente, che può leggere/aggiornare i record autonomamente tramite i propri strumenti — runAgent() viene risolta una volta completata l’esecuzione. Passa waitForCompletion: false per risolvere non appena l’esecuzione si avvia: status è quindi RUNNING e result: null, e la risposta arriva nella conversazione threadId. Un’esecuzione che supera i 15 minuti restituisce anch’essa RUNNING.
• L’agente può anche sospendersi finché un record non cambia o non è trascorso del tempo. runAgent() viene quindi risolto con success: true, status: 'SUSPENDED' e result: null; l’agente prosegue autonomamente in seguito e la sua risposta arriva nella conversazione threadId. Una chiamata a un thread il cui agente è ancora in attesa non riesce finché non termina.
• Ogni chiamata viene archiviata con il relativo input e stato, oltre alla risposta e all’utilizzo al completamento, così da comparire nelle esecuzioni dell’agente. Senza un thread, una chiamata riceve una conversazione propria: threadId la denomina e una chiamata successiva non la vede mai.
• Un’app può eseguire solo i propri agenti.
• Il ruolo predefinito dell’app deve concedere il flag di autorizzazione AI — aggiungi SystemPermissionFlag.AI ai suoi permissionFlagUniversalIdentifiers (oppure imposta canAccessAllTools: true). In mancanza di ciò, runAgent() non riesce con un errore di autorizzazione.
• Imposta un valore generoso per timeoutSeconds sulla funzione di logica — l’esecuzione degli agenti può richiedere diversi secondi.
• status è COMPLETED con un result non null quando l’esecuzione viene completata senza attendere; SUSPENDED con success: true e result: null mentre attende; RUNNING con success: true e result: null quando la chiamata non ha atteso l’esecuzione; FAILED con success: false e error che contiene il motivo (ad esempio, quando lo spazio di lavoro esaurisce i crediti AI durante l’esecuzione).

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

​

Invio di file con un messaggio

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

• Solo i messaggi user possono contenere allegati. Non possono essere rappresentati in un turno dell’assistente, quindi runAgent() li rifiuta lì anziché eliminarli.
• Al massimo 10 allegati per messaggio.
• Il fileId deve indicare un file completamente caricato nello stesso spazio di lavoro, nella cartella agent-chat. Qualsiasi altra cosa fa fallire la chiamata anziché rispondere silenziosamente senza il file.

​

Richiedere un risultato strutturato

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

​

Proseguire una conversazione

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

• Le chiavi hanno ambito limitato alla tua app e al tuo agente, quindi due app non condividono mai una conversazione. Solo i token di accesso dell’app possono passare un thread.
• input può contenere solo messaggi user: la conversazione contiene già le risposte dell’agente.
• additionalInstructions vengono fornite al modello solo per questa chiamata e non vengono archiviate, il che è adatto per indicazioni specifiche per richiesta, come regole di formattazione o una scadenza. Funzionano anche senza un thread.
• Ogni esecuzione viene archiviata come turno con il relativo stato, incluse quelle non riuscite. Il suo utilizzo viene archiviato quando l’agente restituisce il controllo, anche se ha esaurito i crediti. Un’ esecuzione non riuscita non fa parte della conversazione, quindi la chiamata successiva non la vede.
• Le chiamate sullo stesso thread vengono eseguite una alla volta: una seconda chiamata attende che la prima termini, così ciascuna vede i turni precedenti.
• Quando i turni vengono eseguiti come membri diversi (vedi sotto), ciascuno vede solo il testo dei turni degli altri, mai i risultati dei loro strumenti, poiché questi sono stati letti con le autorizzazioni di qualcun altro.

​

Esecuzione per conto di un membro dello spazio di lavoro

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 senza alcun utente associato può specificare qualsiasi membro. Una funzione logica viene eseguita con uno, e così anche i token generati tramite client_credentials o da una chiave API.
• Un token emesso per conto di un utente, come quello che riceve un front component, può specificare solo il membro dell’utente stesso.

​

Seguire una conversazione

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

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.

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

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

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