Skills & Agents - Twenty Documentation

defineSkill

Define AI agent skills

Skills define reusable instructions and capabilities that AI agents can use within your workspace. Use defineSkill() to define skills with built-in validation:

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

Key points:

name is a unique identifier string for the skill (kebab-case recommended).
label is the human-readable display name shown in the UI.
content contains the skill instructions — this is the text the AI agent uses.
icon (optional) sets the icon displayed in the UI.
description (optional) provides additional context about the skill’s purpose.

defineAgent

Define AI agents with custom prompts

Agents are AI assistants that live inside your workspace. Use defineAgent() to create agents with a custom system prompt:

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

Key points:

name is the unique identifier string for the agent (kebab-case recommended).
label is the display name shown in the UI.
prompt is the system prompt that defines the agent’s behavior.
description (optional) provides context about what the agent does.
icon (optional) sets the icon displayed in the UI.
modelId (optional) overrides the default AI model used by the agent.
responseFormat (optional) controls the shape of the agent’s output. Defaults to { type: 'text' } for free-form text. Use { type: 'json', schema } to force structured JSON output.

By default an agent returns free-form text. To get structured output, set responseFormat to { type: 'json' } and provide a 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,
    },
  },
});

Schema notes:

The schema is a flat object: each property’s type must be a primitive (string, number, or boolean). Nested objects and arrays are not supported.
description (optional) on each property guides the model on what to put there.
required (optional) lists the properties the model must always return.
additionalProperties: false (optional) forbids any property not declared in properties.

runAgent

Run an agent from a logic function

runAgent() lets a logic function run one of your app’s agents (with its skills and tools). Identify the agent by the universalIdentifier you passed to 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.',
});

Key points:

The agent runs synchronously and can read/update records itself via its own tools — runAgent() resolves once the run completes.
An app can only run its own agents.
The app’s default role must grant the AI permission flag — add SystemPermissionFlag.AI to its permissionFlagUniversalIdentifiers (or set canAccessAllTools: true). Without it, runAgent() fails with a permission error.
Set a generous timeoutSeconds on the logic function — agent runs can take several seconds.
success is true and result is non-null when the run completes; on failure success is false, result is null, and error holds the reason (for example, when the workspace ran out of AI credits mid-run).

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

Avoid loops: if you call runAgent() from a *.updated database-event trigger and the agent updates the same record, scope the trigger with updatedFields to a field the agent never writes (e.g. the source URL), or guard on whether any target field is still empty before calling runAgent().