> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 스킬 & 에이전트

> 앱용 AI 스킬 및 에이전트 정의.

<Warning>
  스킬과 에이전트는 현재 알파 단계입니다. 해당 기능은 작동하지만 아직 발전 중입니다.
</Warning>

앱은 워크스페이스 내에서 동작하는 AI 기능을 정의할 수 있습니다 — 재사용 가능한 스킬 지침과 사용자 지정 시스템 프롬프트를 갖춘 에이전트.

<AccordionGroup>
  <Accordion title="defineSkill" description="AI 에이전트 스킬 정의">
    스킬은 워크스페이스 내에서 AI 에이전트가 사용할 수 있는 재사용 가능한 지침과 기능을 정의합니다. `defineSkill()`을 사용해 내장 검증과 함께 스킬을 정의하세요:

    ```ts src/skills/example-skill.ts theme={null}
    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` (선택 사항)은 스킬의 목적에 대한 추가 컨텍스트를 제공합니다.
  </Accordion>

  <Accordion title="defineAgent" description="사용자 지정 프롬프트로 AI 에이전트를 정의하세요">
    에이전트는 워크스페이스 내에서 동작하는 AI 비서입니다. `defineAgent()`를 사용하여 사용자 지정 시스템 프롬프트로 에이전트를 생성하세요:

    ```ts src/agents/example-agent.ts theme={null}
    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`를 제공하세요:

    ```ts src/agents/structured-agent.ts theme={null}
    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`에 선언되지 않은 모든 속성을 금지합니다.
  </Accordion>

  <Accordion title="runAgent" description="로직 함수에서 에이전트를 실행">
    `runAgent()`를 사용하면 로직 함수가 앱의 에이전트(해당 skills 및 tools 포함) 중 하나를 실행할 수 있습니다. `defineAgent()`에 전달했던 `universalIdentifier`로 에이전트를 식별합니다:

    ```ts src/logic-functions/run-enricher.ts theme={null}
    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됩니다.
    * 앱은 자신의 에이전트만 실행할 수 있습니다.
    * 앱의 [기본 역할](/l/ko/developers/extend/apps/config/roles)은 `AI` 권한 플래그를 부여해야 합니다. 이를 위해 `permissionFlagUniversalIdentifiers`에 `SystemPermissionFlag.AI`를 추가하거나, `canAccessAllTools: true`로 설정하세요.
      이 권한이 없으면 `runAgent()`는 권한 오류로 실패합니다.
    * 로직 함수에 충분히 큰 `timeoutSeconds`를 설정하세요. 에이전트 실행에는 여러 초가 걸릴 수 있습니다.
    * 실행이 완료되면 `success`는 `true`이고 `result`는 null이 아닙니다. 실패 시 `success`는 `false`, `result`는 `null`이며, `error`에 이유가 들어 있습니다(예: 실행 도중 워크스페이스의 AI 크레딧이 소진된 경우).

    ```ts src/roles/default-role.ts theme={null}
    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],
    });
    ```

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