スキルとエージェント - 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 はスキルの一意の識別子文字列です（kebab-case を推奨）。
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 はエージェントの一意の識別子文字列です（kebab-case を推奨）。
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() を使用すると、ロジック関数からアプリのエージェント（そのスキルやツールを含む）を実行できます。 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.',
});

主なポイント：

エージェントは同期的に実行され、自身のツールを通じてレコードの読み取り/更新ができます。runAgent() は、実行が完了すると解決されます。
アプリは自分自身のエージェントのみを実行できます。
アプリのデフォルトロールには 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() を呼び出す前に、対象フィールドのいずれかがまだ空であるかどうかを判定してガードしてください。