github-actions[bot]
2b3b2362db
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
139 lines
7.1 KiB
Plaintext
139 lines
7.1 KiB
Plaintext
---
|
|
title: 스킬 & 에이전트
|
|
description: 앱용 AI 스킬 및 에이전트 정의.
|
|
icon: robot
|
|
---
|
|
|
|
<Warning>
|
|
스킬과 에이전트는 현재 알파 단계입니다. 해당 기능은 작동하지만 아직 발전 중입니다.
|
|
</Warning>
|
|
|
|
앱은 워크스페이스 내에서 동작하는 AI 기능을 정의할 수 있습니다 — 재사용 가능한 스킬 지침과 사용자 지정 시스템 프롬프트를 갖춘 에이전트.
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="defineSkill" description="AI 에이전트 스킬 정의">
|
|
|
|
스킬은 워크스페이스 내에서 AI 에이전트가 사용할 수 있는 재사용 가능한 지침과 기능을 정의합니다. `defineSkill()`을 사용해 내장 검증과 함께 스킬을 정의하세요:
|
|
|
|
```ts 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` (선택 사항)은 스킬의 목적에 대한 추가 컨텍스트를 제공합니다.
|
|
|
|
</Accordion>
|
|
<Accordion title="defineAgent" description="사용자 지정 프롬프트로 AI 에이전트를 정의하세요">
|
|
|
|
에이전트는 워크스페이스 내에서 동작하는 AI 비서입니다. `defineAgent()`를 사용하여 사용자 지정 시스템 프롬프트로 에이전트를 생성하세요:
|
|
|
|
```ts 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`를 제공하세요:
|
|
|
|
```ts 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`에 선언되지 않은 모든 속성을 금지합니다.
|
|
|
|
</Accordion>
|
|
<Accordion title="runAgent" description="로직 함수에서 에이전트를 실행">
|
|
|
|
`runAgent()`를 사용하면 로직 함수가 앱의 에이전트(해당 skills 및 tools 포함) 중 하나를 실행할 수 있습니다. `defineAgent()`에 전달했던 `universalIdentifier`로 에이전트를 식별합니다:
|
|
|
|
```ts 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됩니다.
|
|
* 앱은 자신의 에이전트만 실행할 수 있습니다.
|
|
* 앱의 [기본 역할](/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
|
|
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>
|