Навыки и агенты

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 (необязательно) предоставляет дополнительный контекст о назначении навыка.

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-вывод. Вызов runAgent() или ИИ-шаг рабочего процесса может запросить другой формат, который имеет приоритет.
• roleUniversalIdentifier (необязательно) связывает агента с ролью, определённой вашим приложением. Эта роль не должна предоставлять больше прав, чем роль приложения, иначе сборка завершится с ошибкой; см. Роли агентов.
• modelConfiguration (необязательный параметр) включает встроенные инструменты модели, как на странице настроек агента: { webSearch: { enabled: true }, twitterSearch: { enabled: true } }. Каждый инструмент работает только с моделями, которые его поддерживают. Не указывайте его, чтобы они оставались отключенными.
• isSystem (необязательный параметр, по умолчанию false) скрывает агента из списков агентов, как агентов, которых Twenty создает для шагов ИИ в рабочих процессах. Он изменяет только отображаемое: агентов приложения можно изменять только через приложение, независимо от значения этого флага.

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.

import { defineMcpServer } from 'twenty-sdk/define';

import { GITHUB_CONNECTION_PROVIDER_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';

export default defineMcpServer({
  universalIdentifier: '0b6c4f7e-3d5a-4a8e-9a0d-6f1e2c3b4a01',
  name: 'github',
  label: 'GitHub',
  url: 'https://api.githubcopilot.com/mcp/',
  connectionProvider: {
    universalIdentifier: GITHUB_CONNECTION_PROVIDER_UNIVERSAL_IDENTIFIER,
  },
});

• name имеет формат snake_case (строчные буквы, цифры и символы подчёркивания, начинается с буквы, не более 32 символов) и уникален в рабочем пространстве. Он добавляется в начало имён инструментов сервера.
• url должен быть URL-адресом HTTP или HTTPS.
• connectionProvider (необязательно) ссылается на поставщика подключения, объявленного тем же приложением. Запросы отправляют токен доступа этого подключения в качестве токена Bearer. Не указывайте его для общедоступного сервера.
• URL-адрес нельзя изменить в более поздней версии, пока подключён поставщик подключения, поэтому токены никогда не отправляются на другой хост.
• Рабочие пространства могут деактивировать сервер; более поздняя версия приложения сохранит этот выбор.
• Требуется "engines": { "twenty": ">=2.53.0" }.

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

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

• input — это строка или список из 1–100 сообщений ({ role: 'user' | 'assistant', content: string }). Сообщение user также может содержать вложения файлов (см. ниже). Чтобы поддерживать диалог, передавайте thread, а не воспроизводите предыдущие ходы самостоятельно.
• По умолчанию вызов ожидает агента, который может самостоятельно читать и обновлять записи с помощью собственных инструментов — runAgent() возвращает результат после завершения запуска. Передайте waitForCompletion: false, чтобы вызов вернул результат сразу после запуска: status будет иметь значение RUNNING, а result: null; ответ поступит в беседу threadId. Запуск, длящийся более 15 минут, также завершается со значением RUNNING.
• Агент также может приостановить работу, пока не изменится запись или не пройдет некоторое время. Затем runAgent() завершается со значениями success: true, status: 'SUSPENDED' и result: null; позже агент самостоятельно продолжает работу, а его ответ появляется в беседе threadId. Вызов thread, агент которого все еще ожидает, завершается ошибкой, пока агент не завершит работу.
• Каждый вызов сохраняется вместе с его входными данными и статусом, а также с его ответом и использованием после завершения, поэтому он отображается в запусках агента. Без thread вызов получает собственный разговор: threadId задаёт его, и последующий вызов его никогда не видит.
• Приложение может запускать только собственных агентов.
• Роль по умолчанию приложения должна предоставлять флаг разрешения AI — добавьте SystemPermissionFlag.AI в permissionFlagUniversalIdentifiers (или установите canAccessAllTools: true). Без этого runAgent() завершится с ошибкой прав доступа.
• Установите достаточно большое значение timeoutSeconds для логической функции — выполнение агента может занимать несколько секунд.
• status имеет значение COMPLETED и не равный null result, когда запуск завершается без ожидания; SUSPENDED со значением success: true и result: null, пока он ожидает; RUNNING со значением success: true и result: null, когда вызов не ожидал запуска; FAILED со значением success: false и error, содержащим причину (например, когда в рабочем пространстве во время запуска закончились кредиты ИИ).

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

​

Отправка файлов вместе с сообщением

const { result } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  input: [
    {
      role: 'user',
      content: 'What does this error screen say?',
      attachments: [{ fileId: uploadedFileId, filename: 'error.png' }],
    },
  ],
});

• Вложения могут содержать только сообщения user. Их нельзя представить в ходе assistant, поэтому runAgent() отклоняет их, а не удаляет.
• Не более 10 вложений на сообщение.
• fileId должен указывать на полностью загруженный файл в том же рабочем пространстве, в папке agent-chat. В противном случае вызов завершается ошибкой вместо того, чтобы незаметно ответить без файла.

​

Запрос структурированного результата

const { result } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  input: `Score this lead: ${JSON.stringify(lead)}`,
  responseFormat: {
    type: 'json',
    schema: {
      type: 'object',
      properties: {
        score: { type: 'number', description: 'Lead score from 0 to 100' },
      },
      required: ['score'],
    },
  },
});

​

Продолжение диалога

const { result, threadId } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  input: 'What was the last touchpoint?',
  additionalInstructions: 'Answer in Slack markdown.',
  thread: { key: `${channelId}:${threadTs}`, title: 'Acme renewal' },
});

• Ключи ограничены вашим приложением и агентом, поэтому два приложения никогда не используют один диалог. Передавать thread могут только токены доступа приложения.
• input может содержать только сообщения user: в диалоге уже есть ответы агента.
• additionalInstructions передаются модели только для этого вызова и не сохраняются, что подходит для указаний для каждого запроса, например правил форматирования или крайнего срока. Они также работают без thread.
• Каждый запуск сохраняется как ход с указанием его статуса, включая неудачные. Его использование сохраняется при возврате агента, даже если у него закончились кредиты. Неудачный запуск не является частью разговора, поэтому следующий вызов его не видит.
• Вызовы в одной и той же цепочке выполняются по одному: второй вызов ожидает завершения первого, поэтому каждый из них видит предшествующие ему ходы.
• Когда ходы выполняются от имени разных участников (см. ниже), каждый из них видит только текст ходов остальных, но никогда не видит результаты их инструментов, поскольку они были получены с разрешениями другого пользователя.

​

Запуск от имени участника рабочего пространства

const { result } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  input: 'How many open opportunities do we have?',
  runAsWorkspaceMemberId: '20202020-0687-4c41-b707-ed1bfca972a7',
});

• Токен без привязанного пользователя может указать любого участника. Логическая функция выполняется с таким токеном; то же относится к токенам, выпущенным через client_credentials или на основе API‑ключа.
• Токен, выданный от имени пользователя (как у фронтенд‑компонента), может указывать только на участника самого этого пользователя.