Abilități și agenți - Twenty Documentation

defineSkill

Definiți abilități pentru agentul AI

Abilitățile definesc instrucțiuni și capabilități reutilizabile pe care agenții AI le pot folosi în spațiul dvs. de lucru. Folosiți defineSkill() pentru a defini abilități cu validare încorporată:

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

Puncte cheie:

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.

defineAgent

Definiți agenți AI cu prompturi personalizate

Agenții sunt asistenți AI care există în interiorul spațiului dvs. de lucru. Utilizați defineAgent() pentru a crea agenți cu un prompt de sistem personalizat:

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

Puncte cheie:

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) controlează forma ieșirii agentului. Valoarea implicită este { type: 'text' } pentru text liber. Folosește { type: 'json', schema } pentru a impune ieșire JSON structurată.

În mod implicit, un agent returnează text liber. Pentru a obține o ieșire structurată, setează responseFormat la { type: 'json' } și furnizează 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 despre schemă:

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.

runAgent

Rulează un agent dintr-o funcție logică

runAgent() permite unei funcții logice să ruleze unul dintre agenții aplicației tale (cu abilitățile și instrumentele sale). Identifică agentul prin universalIdentifier pe care l-ai transmis către 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.',
});

Puncte cheie:

Agentul rulează sincron și poate citi/actualiza direct înregistrări prin propriile sale instrumente — runAgent() este rezolvat după ce rularea se încheie.
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.
success este true și result este nenul când rularea se încheie; în caz de eșec success este false, result este null, iar error conține motivul (de exemplu, când spațiul de lucru rămâne fără credite AI în timpul rulării).

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

Evită buclele: dacă apelezi runAgent() dintr-un declanșator de tip eveniment de bază de date *.updated, iar agentul actualizează aceeași înregistrare, restrânge declanșatorul cu updatedFields la un câmp pe care agentul nu îl scrie niciodată (de exemplu, URL-ul sursă) sau verifică dacă vreun câmp țintă este încă gol înainte de a apela runAgent().