# UI SDK Nedir? Ajanlar İçin Bileşen Değil, Davranış

> Vercel'in UI SDK'sı ajanlara bileşen değil davranış veriyor. Ne olduğunu, nasıl kullanıldığını ve frontend için ne anlama geldiğini anlattım.

Source: https://omergulcicek.com/blog/ui-sdk-nedir

12 Kasım 2026'da shadcn, Vercel'de geliştirdikleri **UI SDK**'yı duyurdu.[^shadcn-launch] Kendi tanımıyla UI SDK, ajanların yeni nesil arayüzleri kurması için bir davranış kütüphanesi.[^readme] Benim için tanımı şu: **Bootstrap geliştiricilere ortak bir görünüm dili verdi; UI SDK ise ajanlara arayüzleri hem kurmak hem de kullanmak için ortak bir davranış dili veriyor.**

Bu yazıda UI SDK'nın ne olduğunu ve nasıl kullanıldığını birkaç örnekle anlattım.

![Bir ortam seçicisi üç davranışa ayrılıyor: createPopup, createSelection ve createTypeahead. Görsel: UI SDK README](https://omergulcicek.com/blog/2026/11-15/ui-sdk-davranislar.webp)

## Bileşen Değil, Davranış

shadcn duyuruda şu soruyu soruyor: ajanlar arayüzlerin hem kurucusu hem kullanıcısı oluyorsa soyutlama nerede durmalı? Cevapları, Select gibi bir bileşenin içindeki popup, seçim mantığı, klavye navigasyonu ve focus yönetimini ayırıp test edilmiş, yeniden kullanılabilir parçalar hâline getirmek.[^shadcn-launch]

Yukarıdaki görsel bunu gösteriyor. Select aslında üç davranıştan oluşuyor:[^home]

- **`createPopup`:** Açılır, konumlanır, kapanır.
- **`createSelection`:** Bir ya da birden fazla seçim yapılır.
- **`createTypeahead`:** Birkaç harf yazınca ilgili seçeneğe atlanır.

Ajana Select yerine bu parçaları verirseniz yalnızca Select değil, autocomplete, combobox ya da henüz kimsenin düşünmediği bir bileşen de kurabilir.[^home] Ana sayfaya göre 50'den fazla davranış var: focus, seçim, sürükle bırak, yeniden boyutlandırma, sanal listeler ve ekran okuyucu desteği gibi.[^home]

shadcn fikri ikinci bir paylaşımında şöyle özetliyor: senin ve benim aynı arayüzlere değil, aynı arayüz davranışlarına ihtiyacımız var. Senin ajanın tarih seçmek için bir takvim, benimki basit bir input üretebilir. Arayüzler farklı olabilir, altta yatan garantiler aynı kalmalı.[^shadcn-behaviors]

## Primitive: Davranışları Bir Araya Getirmek

Davranışları bir bileşende toplayan yapının adı **primitive**. Primitive bir bileşenin state'ini, onu değiştiren fonksiyonları ve bunları kullanan parçaları tanımlıyor; kendi başına hiçbir şey render etmiyor.[^build] Dokümantasyondaki en küçük örnek bir sessize alma butonu:

```ts
import { definePrimitive } from "@ui-sdk/core"

const muteButton = definePrimitive({
  name: "mute-button",
  state: () => ({ muted: false }),
  api: (context) => ({
    toggle: () => context.store.set({ muted: !context.store.get().muted }),
  }),
  slots: (slot) => ({
    root: slot({
      attrs: (state) => ({
        type: "button",
        "aria-pressed": String(state.muted),
      }),
      press: ({ api }) => api.toggle(),
    }),
  }),
})
```

`attrs` state'i HTML attribute'larına çeviriyor: `muted` true olunca buton `aria-pressed="true"` alıyor. `press` ise butona tıklanınca ya da klavyeyle basılınca `toggle`'ı çağırıyor.[^build] Bu primitive'i React'te şöyle render ediyorsunuz:

```tsx
import { createParts } from "@ui-sdk/react/primitive"

const { Root: MuteButton } = createParts(muteButton, { root: "button" })

function Example() {
  return <MuteButton>Mute</MuteButton>
}
```

Davranış primitive'de kalıyor; aynı primitive React, Vue, Svelte, Solid ve Web Components'te çalışıyor. Parçalar stilsiz geliyor, CSS'i `data-slot` ve state attribute'larına yazıyorsunuz.[^build]

## Nasıl Kullanılır?

UI SDK şu an beta. Çekirdek paketle birlikte framework'ünüzün adaptörünü kurup ajanınıza skill'i veriyorsunuz:[^readme]

```bash
npm install @ui-sdk/react @ui-sdk/core
npx skills add vercel-labs/ui --skill ui-sdk
```

Asıl fikir, primitive'i sizin yazmamanız. README bunu açıkça söylüyor: bunu nasıl yazacağınızı öğrenmeniz gerekmiyor, ajanlarınız öğrenecek.[^readme] Siz ajana etkileşimi somut olarak anlatıyorsunuz. Dokümantasyondaki örnek bir emoji seçici: aramadan aşağı ok basınca focus ilk sonuca geçsin, ok tuşları grid'de gezinsin, Enter seçsin, seçim ekran okuyuculara duyurulsun.[^build-with-agent] Her paket kurulu sürümle eşleşen Markdown dokümanlarını içinde taşıdığı için ajan doğru sürümün dokümanını okuyor.[^build-with-agent]

## Ajanlar Arayüzü Kullanabiliyor

UI SDK'nın ikinci yarısı bence en az ilki kadar ilginç: ajan arayüzü kurmakla kalmıyor, kullanabiliyor da. Ana sayfaya göre ajanlar sayfayı ekran görüntüsü almadan okuyor ve kontrolleri doğrudan çalıştırıyor.[^home]

Uygulamaya bir köprü ekleniyor. `snapshot()` sayfadaki bileşenleri, state'lerini ve aksiyonlarını listeliyor; ajan da değeri tıklayıp yazarak değil, bileşenin API'sini çağırarak değiştiriyor:[^connect]

```ts
import { createAgent } from "@ui-sdk/react/agent"

const agent = createAgent()

agent.snapshot()
// [{ ref: "c1", component: "input", label: "Project name", value: "Apollo", actions: ["setValue", "clear"] }]

await agent.act({
  steps: [{ ref: "Project name", action: "setValue", args: ["Atlas"] }],
})
```

Burada erişilebilirlik ile ajan uyumluluğu aynı yere çıkıyor: input'a verilen erişilebilir isim hem ekran okuyucuların hem de ajanların bileşeni tanımasını sağlıyor.[^connect]

Ajanın neye dokunabileceğine de siz karar veriyorsunuz. `allow` callback'i hangi aksiyonların çalışacağını belirliyor, `data-agent-confirm` bir butonu her zaman kullanıcı onayına bağlıyor, `data-agent-hidden` bir bölümü ajandan tamamen saklıyor.[^permissions] Deneysel `createHistory` ile yalnızca ajanın yaptığı değişiklikler geri alınabiliyor.[^history]

Ekibin benchmark'ında aynı ayarlar ekranı, React'te Base UI ve Ark UI ile tarayıcı araçları kullanılarak, UI SDK ile de köprü kullanılarak doldurulmuş:[^agents]

|            | Base UI | Ark UI | UI SDK + köprü |
| ---------- | ------- | ------ | -------------- |
| Tool call  | 17      | 19     | **7**          |
| Token      | 291.7k  | 330.9k | **69.5k**      |
| Süre       | 53 sn   | 65 sn  | **31 sn**      |
| Maliyet    | $0.139  | $0.144 | **$0.044**     |

Tablonun altındaki not bence en önemli kısım: UI SDK ekranı tarayıcı araçlarıyla çalıştırıldığında diğer kütüphanelerle hemen hemen aynı sonucu vermiş. Yani farkı kütüphane değil, köprü yaratıyor.[^agents]

## Yeni Bir Kapı mı?

İlk akla gelen soru şu: bu zaten her headless kütüphanenin vaadi değil mi? Bence de davranışı stilden ayırmak yeni bir fikir değil; UI SDK da kendini headless diye tanımlıyor.[^core] Yeni olan iki şey var: soyutlamanın bileşenin bir kat altına, davranışa inmesi ve kodu yazanın da arayüzü kullananın da ajan olabileceği varsayımı.

Bootstrap benzetmesi de buradan geliyor. Bootstrap'te herkes aynı buton, modal ve grid sınıflarını kullanıyordu; ortak olan görünümdü. UI SDK'da ortak olan görünüm değil, davranış: her ajan farklı bir arayüz üretebilir ama Escape'in popup'ı kapatması ya da silinen öğenin focus'unun kaybolmaması aynı kalır. shadcn'in deyişiyle arayüzler farklı, garantiler aynı.[^shadcn-behaviors]

Açık sorular da var. UI SDK beta; API'ler ve davranışlar genel sürümden önce değişebilir.[^readme] Primitive'i ajan yazsa da hata çıktığında okuyacak olan yine biziz; bence `definePrimitive` mantığını en az bir kez elle kurmak gerekiyor. Son olarak `allow` vermezseniz köprü desteklenen her aksiyonu kabul ediyor;[^permissions] ajanın neye basabileceği varsayılanlara bırakılacak bir karar değil.

[^shadcn-launch]: [shadcn: UI SDK duyurusu (X, 12 Kasım 2026)](https://x.com/shadcn/status/2120951116682682646)
[^readme]: [GitHub: vercel-labs/ui README](https://github.com/vercel-labs/ui)
[^home]: [UI SDK ana sayfası](https://ui-sdk.dev/)
[^shadcn-behaviors]: [shadcn: Aynı arayüz değil, aynı davranışlar (X, 15 Kasım 2026)](https://x.com/shadcn/status/2121778646956343344)
[^build]: [UI SDK: Build a Component](https://ui-sdk.dev/docs/core/build-a-component)
[^build-with-agent]: [UI SDK: Build with an Agent](https://ui-sdk.dev/docs/agents/build-with-an-agent)
[^connect]: [UI SDK: Connect an Agent](https://ui-sdk.dev/docs/agents/connect-an-agent)
[^permissions]: [UI SDK: Permissions](https://ui-sdk.dev/docs/agents/connect-an-agent/permissions)
[^history]: [UI SDK: History and Undo](https://ui-sdk.dev/docs/agents/connect-an-agent/history-and-undo)
[^agents]: [UI SDK: Built for Agents (Benchmark)](https://ui-sdk.dev/docs/agents)
[^core]: [UI SDK: Core, Introduction](https://ui-sdk.dev/docs/core)