Dovednosti a agenti - Twenty Documentation

defineSkill

Definujte dovednosti agentů AI

Dovednosti definují znovupoužitelné pokyny a schopnosti, které mohou agenti AI používat ve vašem pracovním prostoru. K definování dovedností s vestavěnou validací použijte defineSkill():

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

Hlavní body:

name je jedinečný identifikátor dovednosti (doporučuje se kebab-case).
label je uživatelsky čitelný název zobrazovaný v UI.
content obsahuje pokyny dovednosti — je to text, který agent AI používá.
icon (volitelné) nastavuje ikonu zobrazovanou v UI.
description (volitelné) poskytuje doplňující kontext o účelu dovednosti.

defineAgent

Definujte AI agenty s vlastními prompty

Agenti jsou asistenti AI, kteří běží ve vašem pracovním prostoru. K vytvoření agentů s vlastním systémovým promptem použijte defineAgent():

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

Hlavní body:

name je jedinečný identifikátor agenta (doporučuje se kebab-case).
label je zobrazovaný název v UI.
prompt je systémový prompt, který definuje chování agenta.
description (volitelné) poskytuje kontext o tom, co agent dělá.
icon (volitelné) nastavuje ikonu zobrazovanou v UI.
modelId (volitelné) přepíše výchozí model AI používaný agentem.
responseFormat (volitelně) určuje tvar výstupu agenta. Výchozí hodnota je { type: 'text' } pro volný text. Použijte { type: 'json', schema } k vynucení strukturovaného výstupu ve formátu JSON.

Ve výchozím nastavení agent vrací volný text. Chcete-li získat strukturovaný výstup, nastavte responseFormat na { type: 'json' } a poskytněte 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,
    },
  },
});

Poznámky ke schématu:

Schéma je plochý objekt: type každé vlastnosti musí být primitivní typ (string, number nebo boolean). Vnořené objekty a pole nejsou podporovány.
description (volitelně) u každé vlastnosti navádí model, co má na toto místo doplnit.
required (volitelně) vypisuje vlastnosti, které musí model vždy vrátit.
additionalProperties: false (volitelně) zakáže jakoukoli vlastnost, která není deklarována v properties.

runAgent

Spuštění agenta z logické funkce

runAgent() umožňuje logické funkci spustit jednoho z agentů vaší aplikace (s jeho dovednostmi a nástroji). Identifikujte agenta pomocí universalIdentifier, který jste předali do 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.',
});

Hlavní body:

Agent běží synchronně a může sám číst/aktualizovat záznamy pomocí vlastních nástrojů — runAgent() vrátí výsledek až po dokončení běhu.
Aplikace může spouštět pouze své vlastní agenty.
Výchozí role aplikace musí udělovat příznak oprávnění AI — přidejte SystemPermissionFlag.AI do permissionFlagUniversalIdentifiers (nebo nastavte canAccessAllTools: true). Bez něj runAgent() selže s chybou oprávnění.
Nastavte u logické funkce velkorysou hodnotu timeoutSeconds — běh agenta může trvat několik sekund.
success je true a result není null po dokončení běhu; při chybě je success false, result je null a error obsahuje důvod (například když během běhu workspace vyčerpal AI kredity).

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

Vyhněte se smyčkám: pokud voláte runAgent() z databázového triggeru *.updated a agent aktualizuje stejný záznam, omezte trigger pomocí updatedFields na pole, do kterého agent nikdy nezapisuje (např. zdrojovou URL), nebo před voláním runAgent() zkontrolujte, zda je některé cílové pole stále prázdné.