스킬 & 에이전트 - Twenty Documentation

defineSkill

AI 에이전트 스킬 정의

스킬은 워크스페이스 내에서 AI 에이전트가 사용할 수 있는 재사용 가능한 지침과 기능을 정의합니다. 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은 스킬의 고유 식별자 문자열입니다(케밥 케이스 권장).
label은 UI에 표시되는 사람이 읽기 쉬운 표시 이름입니다.
content에는 스킬 지침이 포함됩니다 — 이는 AI 에이전트가 사용하는 텍스트입니다.
icon (선택 사항)은 UI에 표시되는 아이콘을 설정합니다.
description (선택 사항)은 스킬의 목적에 대한 추가 컨텍스트를 제공합니다.

defineAgent

사용자 지정 프롬프트로 AI 에이전트를 정의하세요

에이전트는 워크스페이스 내에서 동작하는 AI 비서입니다. 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은 에이전트의 고유 식별자 문자열입니다(케밥 케이스 권장).
label은 UI에 표시되는 표시 이름입니다.
prompt는 에이전트의 동작을 정의하는 시스템 프롬프트입니다.
description (선택 사항)은 에이전트가 수행하는 작업에 대한 컨텍스트를 제공합니다.
icon (선택 사항)은 UI에 표시되는 아이콘을 설정합니다.
modelId (선택 사항)은 에이전트가 사용하는 기본 AI 모델을 재정의합니다.
responseFormat(선택 사항)은 에이전트 출력의 형태를 제어합니다. 자유 형식 텍스트의 기본값은 { type: 'text' }입니다. 구조화된 JSON 출력을 강제하려면 { type: 'json', schema }를 사용하세요.

기본적으로 에이전트는 자유 형식 텍스트를 반환합니다. 구조화된 출력을 받으려면, 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()를 사용하면 로직 함수가 앱의 에이전트(해당 skills 및 tools 포함) 중 하나를 실행할 수 있습니다. defineAgent()에 전달했던 universalIdentifier로 에이전트를 식별합니다:

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

핵심 요점:

에이전트는 동기적으로 실행되며, 자체 tools를 통해 레코드를 읽고/업데이트할 수 있습니다. 실행이 완료되면 runAgent()가 resolve됩니다.
앱은 자신의 에이전트만 실행할 수 있습니다.
앱의 기본 역할은 AI 권한 플래그를 부여해야 합니다. 이를 위해 permissionFlagUniversalIdentifiers에 SystemPermissionFlag.AI를 추가하거나, 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],
});

루프를 피하세요: *.updated 데이터베이스 이벤트 트리거에서 runAgent()를 호출하고 에이전트가 동일한 레코드를 업데이트하는 경우, updatedFields를 에이전트가 절대 쓰지 않는 필드(예: 원본 URL)로 한정하거나, runAgent()를 호출하기 전에 대상 필드 중 어느 것이든 아직 비어 있는지 여부를 검사해 가드하세요.