Beceriler ve Ajanlar - Twenty Documentation

defineSkill

Yapay zekâ ajanı yeteneklerini tanımlayın

Yetenekler, yapay zekâ ajanlarının çalışma alanınızda kullanabileceği yeniden kullanılabilir yönergeleri ve kabiliyetleri tanımlar. Yerleşik doğrulamayla yetenekleri tanımlamak için defineSkill() kullanın:

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

Önemli noktalar:

name, yetenek için benzersiz bir tanımlayıcı dizedir (kebab-case önerilir).
label, UI’de gösterilen, insan tarafından okunabilir addır.
content, yetenek yönergelerini içerir — bu, yapay zekâ ajanının kullandığı metindir.
icon (isteğe bağlı), UI’de gösterilen simgeyi ayarlar.
description (isteğe bağlı), yeteneğin amacı hakkında ek bağlam sağlar.

defineAgent

Özel istemlerle yapay zekâ ajanları tanımlayın

Ajanlar, çalışma alanınız içinde bulunan yapay zekâ asistanlarıdır. Özel bir sistem istemiyle ajanlar oluşturmak için defineAgent() kullanın:

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

Önemli noktalar:

name, ajan için benzersiz bir tanımlayıcı dizedir (kebab-case önerilir).
label, UI’de gösterilen görünen addır.
prompt, ajanın davranışını tanımlayan sistem istemidir.
description (isteğe bağlı), ajanın ne yaptığı hakkında bağlam sağlar.
icon (isteğe bağlı), UI’de gösterilen simgeyi ayarlar.
modelId (isteğe bağlı), ajanın kullandığı varsayılan yapay zekâ modelini geçersiz kılar.
responseFormat (isteğe bağlı), ajan çıktısının şeklini kontrol eder. Serbest biçimli metin için varsayılan olarak { type: 'text' } kullanılır. Yapılandırılmış JSON çıktısını zorunlu kılmak için { type: 'json', schema } kullanın.

Varsayılan olarak bir ajan serbest biçimli metin döndürür. Yapılandırılmış çıktı almak için, responseFormat değerini { type: 'json' } yapın ve bir schema sağlayın:

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

Şema notları:

Şema düz bir nesnedir: her özelliğin type değeri, ilkel bir tür (string, number veya boolean) olmalıdır. İç içe nesneler ve diziler desteklenmez.
Her özellik üzerindeki description (isteğe bağlı), modele oraya ne koyması gerektiği konusunda yol gösterir.
required (isteğe bağlı), modelin her zaman döndürmesi gereken özellikleri listeler.
additionalProperties: false (isteğe bağlı), properties içinde tanımlanmamış herhangi bir özelliği yasaklar.

runAgent

Bir mantık işlevinden bir ajan çalıştırın

runAgent(), bir mantık işlevinin uygulamanızın ajanlarından birini (kendi yetenekleri ve araçlarıyla) çalıştırmasına olanak tanır. Ajanı, defineAgent() işlevine ilettiğiniz universalIdentifier ile belirleyin:

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

Önemli noktalar:

Ajan senkron olarak çalışır ve kendi araçları aracılığıyla kayıtları kendisi okuyup/güncelleyebilir — işlem tamamlandığında runAgent() çözümlenir.
Bir uygulama yalnızca kendi ajanlarını çalıştırabilir.
Uygulamanın varsayılan rolü, AI izin bayrağını vermelidir — permissionFlagUniversalIdentifiers içine SystemPermissionFlag.AI ekleyin (veya canAccessAllTools: true olarak ayarlayın). Bu olmadan, runAgent() bir izin hatasıyla başarısız olur.
Mantık işlevi için cömert bir timeoutSeconds değeri ayarlayın — ajan çalışmaları birkaç saniye sürebilir.
Çalışma tamamlandığında success değeri true olur ve result boş olmayan bir değerdir; başarısızlık durumunda success değeri false olur, result değeri null olur ve error nedenini tutar (örneğin, çalışma ortasında çalışma alanının AI kredileri bittiğinde).

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

Döngülerden kaçının: Bir *.updated veritabanı olayı tetikleyicisinden runAgent() çağırırsanız ve ajan aynı kaydı güncelliyorsa, tetikleyiciyi, ajan tarafından asla yazılmayan bir alana (örneğin kaynak URL) göre updatedFields ile kapsamlandırın veya runAgent() çağırmadan önce herhangi bir hedef alanın hâlâ boş olup olmadığına göre koruma ekleyin.