Skill e agenti - Twenty Documentation

defineSkill

Definisci le skill degli agenti IA

Le skill definiscono istruzioni e capacità riutilizzabili che gli agenti IA possono utilizzare all’interno del tuo spazio di lavoro. Usa defineSkill() per definire skill con convalida integrata:

src/skills/example-skill.ts

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

Punti chiave:

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.

defineAgent

Definisci agenti IA con prompt personalizzati

Gli agenti sono assistenti IA che vivono all’interno del tuo spazio di lavoro. Usa defineAgent() per creare agenti con un prompt di sistema personalizzato:

src/agents/example-agent.ts

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

Punti chiave:

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) controlla la forma dell’output dell’agente. Per il testo in formato libero, il valore predefinito è { type: 'text' }. Usa { type: 'json', schema } per forzare un output JSON strutturato.

Per impostazione predefinita, un agente restituisce testo in formato libero. Per ottenere un output strutturato, imposta responseFormat su { type: 'json' } e fornisci uno schema:

src/agents/structured-agent.ts

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

Note sullo schema:

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.

runAgent

Esegui un agente da una funzione di logica

runAgent() permette a una funzione di logica di eseguire uno degli agenti della tua app (con le sue skill e i suoi strumenti). Identifica l’agente tramite l’universalIdentifier che hai passato a defineAgent():

src/logic-functions/run-enricher.ts

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

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

Punti chiave:

L’agente viene eseguito in modo sincrono e può leggere/aggiornare direttamente i record tramite i propri strumenti — runAgent() viene risolta una volta completata l’esecuzione.
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.
success è true e result è non nullo quando l’esecuzione viene completata; in caso di errore success è false, result è null ed error contiene il motivo (ad esempio, quando lo spazio di lavoro esaurisce i crediti AI durante l’esecuzione).

src/roles/default-role.ts

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

Evita i loop: se chiami runAgent() da un trigger di evento del database *.updated e l’agente aggiorna lo stesso record, limita il trigger con updatedFields a un campo che l’agente non scrive mai (ad esempio l’URL di origine), oppure controlla che almeno uno dei campi di destinazione sia ancora vuoto prima di chiamare runAgent().