Навыки и агенты - Twenty Documentation

defineSkill

Определяйте навыки ИИ-агентов

Навыки определяют многократно используемые инструкции и возможности, которые агенты ИИ могут использовать в вашем рабочем пространстве. Используйте 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`,
});

Основные моменты:

name — уникальная строка-идентификатор навыка (рекомендуется kebab-case).
label — читаемое человеком отображаемое имя, показываемое в UI.
content содержит инструкции навыка — это текст, который использует агент ИИ.
icon (необязательно) задаёт значок, отображаемый в UI.
description (необязательно) предоставляет дополнительный контекст о назначении навыка.

defineAgent

Определяйте ИИ-агентов с пользовательскими промптами

Агенты — это ИИ-помощники, работающие в вашем рабочем пространстве. Используйте 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.',
});

Основные моменты:

name — уникальная строка-идентификатор агента (рекомендуется kebab-case).
label — отображаемое имя, показываемое в UI.
prompt — это системный промпт, определяющий поведение агента.
description (необязательно) предоставляет контекст о том, что делает агент.
icon (необязательно) задаёт значок, отображаемый в UI.
modelId (необязательно) переопределяет модель ИИ по умолчанию, используемую агентом.
responseFormat (необязательно) определяет форму вывода агента. По умолчанию для свободного текста используется { type: 'text' }. Используйте { type: 'json', schema }, чтобы принудительно получать структурированный JSON-вывод.

По умолчанию агент возвращает свободный текст. Чтобы получить структурированный вывод, установите для responseFormat значение { type: 'json' } и укажите 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,
    },
  },
});

Примечания к схеме:

Схема — это плоский объект: type каждого свойства должен быть примитивом (string, number или boolean). Вложенные объекты и массивы не поддерживаются.
description (необязательно) для каждого свойства подсказывает модели, что туда нужно поместить.
required (необязательно) перечисляет свойства, которые модель всегда должна возвращать.
additionalProperties: false (необязательно) запрещает любые свойства, не объявленные в properties.

runAgent

Запуск агента из логической функции

runAgent() позволяет логической функции запустить одного из агентов вашего приложения (с его навыками и инструментами). Идентифицируйте агента по universalIdentifier, который вы передали в 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.',
});

Основные моменты:

Агент выполняется синхронно и может самостоятельно читать и обновлять записи с помощью собственных инструментов — runAgent() возвращает результат после завершения выполнения.
Приложение может запускать только собственных агентов.
Роль по умолчанию приложения должна предоставлять флаг разрешения AI — добавьте SystemPermissionFlag.AI в permissionFlagUniversalIdentifiers (или установите canAccessAllTools: true). Без этого runAgent() завершится с ошибкой прав доступа.
Установите достаточно большое значение timeoutSeconds для логической функции — выполнение агента может занимать несколько секунд.
success имеет значение true, а result — не null, когда запуск завершается; при ошибке success равно false, result равно null, а в error содержится причина (например, если в рабочем пространстве закончились AI-кредиты во время запуска).

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

Избегайте циклов: если вы вызываете runAgent() из триггера события базы данных *.updated, и агент обновляет ту же запись, ограничьте триггер, указав в updatedFields поле, которое агент никогда не изменяет (например, исходный URL), или добавьте проверку, что хотя бы одно целевое поле всё ещё пусто, прежде чем вызывать runAgent().