upstream-twenty/packages/twenty-docs/l/tr/developers/extend/apps/logic/skills-and-agents.mdx

---
title: Beceriler ve Ajanlar
description: Uygulamanız için yapay zekâ yetenekleri ve ajanları tanımlayın.
icon: robot
---

<Warning>
  Beceriler ve ajanlar şu anda alfa aşamasında. Özellik işlevsel ancak hâlâ gelişmekte.
</Warning>

Uygulamalar, çalışma alanı içinde yer alan yapay zekâ yeteneklerini — yeniden kullanılabilir yetenek yönergeleri ve özel sistem istemlerine sahip ajanları — tanımlayabilir.

<AccordionGroup>
<Accordion title="defineSkill" description="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:

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

Ö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.

</Accordion>
<Accordion title="defineAgent" description="Ö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:

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

Ö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:

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

Ş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.

</Accordion>
<Accordion title="runAgent" description="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: Ya bir `prompt` dizesi ya da bir `messages` konuşma geçmişi iletin — ikisini birden değil:

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

Çok turlu botlar (Slack, Discord, Teams, …) için, tek bir `prompt` yerine iş parçacığı geçmişini `messages` olarak iletin:

```ts src/logic-functions/reply-in-thread.ts
import { runAgent } from 'twenty-sdk/logic-function';

const { result, error, success } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  messages: [
    { role: 'user', content: 'Who owns Acme?' },
    { role: 'assistant', content: 'Sarah owns the Acme account.' },
    { role: 'user', content: 'What was the last touchpoint?' },
  ],
});
```

Önemli noktalar:
* `prompt` (string) veya `messages`'tan (1 ila 100 adet `{ role: 'user' | 'assistant', content: string }` girişi) **yalnızca birini** sağlayın.
* 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ü](/l/tr/developers/extend/apps/config/roles), `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).

```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>
  **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.
</Warning>

### Bir çalışma alanı üyesi adına çalıştırma

Çalıştırma bir kişi tarafından tetiklendiğinde — örneğin bir mesajı yanıtlayan bir sohbet
botu — ajanın uygulama yerine o üye olarak davranması için `runAsWorkspaceMemberId` iletin:

```ts src/logic-functions/answer-question.ts
const { result } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  prompt: 'How many open opportunities do we have?',
  runAsWorkspaceMemberId: '20202020-0687-4c41-b707-ed1bfca972a7',
});
```

Ardından çalıştırma **üyenin kendi rolüyle** hareket eder: yalnızca o üyenin yapabildiklerini yapabilir, daha fazlasını yapamaz; oluşturduğu kayıtlar ona atfedilir ve üyenin satır düzeyi izinleri uygulanır. Ajanın rolü buna dahil olmaz — bu rol, arkalarında kimse olmayan çalıştırmalar için uygulamanın varsayılanıdır. Otonom çalıştırmalar (zamanlanmış işler, veritabanı olayı tetikleyicileri) için alanı atlayın: bunlar ajanın kendi rolünü korur. Hareket eden uygulama, üyenin izinlerini daraltmadan, kaynak bilgisini korumak için çalıştırmanın bağlamına bağlı kalır.

Çalıştırmayı tetikleyen kişiyi bir çalışma alanı üyesiyle eşleştirmekten uygulamanız sorumludur. Birini belirtmek bir uygulama erişim belirteci gerektirir ve bir belirtecin neyi
belirtebileceği, bir kullanıcı içerip içermediğine bağlıdır:

* **Kullanıcı ile ilişkili olmayan** bir belirteç herhangi bir üyeyi belirtebilir. Bir mantık fonksiyonu bunlardan biriyle çalışır ve `client_credentials` aracılığıyla ya da bir API
  anahtarından oluşturulan belirteçler de aynı şekilde çalışır.
* Bir ön bileşenin aldığı gibi, **bir kullanıcının adına düzenlenmiş** bir belirteç yalnızca o kullanıcının kendi üyesini
  belirtebilir.

Bunların dışındaki her şey — sıradan bir kullanıcı oturumu, bir uygulama belirteci olmayan bir API anahtarı — hiçbir şekilde
bir üyeyi belirtemez.

<Warning>
  `runAgent()` çalışma alanı üyesi çözülemediğinde — bilinmeyen veya kaldırılmış bir üye ya da rolü olmayan bir üye — hata fırlatır. Bu, çağıranın istediğinden daha fazla erişim sağlayacağından asla
  ajanın kendi rolüne geri dönmez.
</Warning>

</Accordion>
</AccordionGroup>