Cursor SDK Eğitimi: TypeScript ile Kodlama Ajanlarını Çalıştırın

Cursor, Nisan 2026 sonunda TypeScript SDK’sını duyurdu ve herkese açık beta olarak yayımladı. Paket @cursor/sdk adıyla yayınlanır ve betikler, CI işleri ve arka uç servisleri gibi Node ortamlarında çalışır.

Editörde Cursor kullanmaya kıyasla temel fark, görevin nerede başladığıdır. Sohbet penceresi açıp istemi kendiniz yazmak yerine, kodunuz ajanı oluşturur, görevi gönderir, olayları akışla alır, sonucu bekler ve hataları ele alır.

Bu eğitimde SDK’yı kuruyor, yerel bir hızlı başlangıç çalıştırıyor, ardından ana projeyi inşa ediyoruz: GitHub deposundaki bir hatayı düzelten ve bir pull request açan bulut ajanı. SDK akışı görünür kalsın diye hatayı bilerek küçük tutuyorum. Sonrasında, deseni uyarlamadan önce gereken genişletme noktalarını ve güvenlik kontrollerini ele alıyoruz. Bulut projesi, başlatıcı betik ve hedef projeyi içeren bir eşlik deposu kullanır.

SDK herkese açık betadadır, bu kodu uzun vadeli bir projede yeniden kullanmadan önce resmi dokümanları kontrol edin.

Cursor SDK Nedir?

Cursor SDK, @cursor/sdk adlı bir TypeScript paketidir ve koddan Cursor ajanları oluşturup çalıştırmanıza olanak tanır. Şunlara erişim sağlar:

• Yerel ve bulut ajan çalıştırmaları.
• Cursor’ın kod tabanı araçları: indeksleme, arama, grep, MCP sunucuları, beceriler (skills), kancalar (hooks) ve alt ajanlar (subagents).
• Cursor hesabınız üzerinden erişebildiğiniz modeller, örneğin Composer 2, GPT-5.5 ve Claude.

SDK, Cursor IDE, CLI ve web uygulamasıyla aynı ajan sistemini kullanır. Fark, onu TypeScript’ten çağırmanızdır.

SDK ne zaman kullanılmalı

SDK, görevin editörde bir kişinin yazmasından değil de koddan başlaması gerektiği durumlara uygundur. Başarısız bir testi incelemesi için ajana soran bir CI işi, bir hata düzeltmesi için dal (branch) oluşturan bir webhook veya bir formdan sabit bir ajan görevini çalıştıran bir dahili araç için kullanmayı tercih ederim.

SDK ile Cursor uygulamasının farkı

SDK, Cursor IDE ve cursor agent CLI ile birlikte Cursor ajanlarını kullanmanın başka bir yoludur.

Editör sohbeti için IDE’yi kullanın. Terminal istemleri için CLI’yı kullanın. Ajanı oluşturması, görevi göndermesi ve sonucu işlemesi gerektiğinde SDK’yı kullanın. Yukarıda belirtildiği gibi, CLI harici sağlayıcı anahtarlarını desteklemez; SDK da yalnızca bir Cursor API anahtarı üzerinden kimlik doğrular.

Cursor SDK Nasıl Bir Araya Geliyor

Kod yazmadan önce, SDK’nın açığa çıkardığı birkaç nesneyi ve çalışma zamanı seçeneklerini bilmek faydalıdır.

Üç çalışma zamanı genelinde Cursor SDK mimarisi. Görsel: Yazar.

Üç çalışma zamanı

SDK, bir ajanın çalışabileceği üç yeri destekler.

Bu yazıda yereli ve Cursor bulutu kullanıyoruz. Yukarıda listelenen kendi barındırdığınız bulut daha çok Kurumsal planlar içindir. SDK kodu, verdiğiniz yapılandırma anahtarına göre değişir: local veya cloud.

Çalışma zamanı, araçlar ve modeller

SDK içindeki bir çalıştırma üç parçadan oluşur. Çalışma zamanı, yürütmenin gerçekleştiği yerdir. Ajan araçları; indeksleme, arama, MCP araç çağrıları, beceriler, kancalar ve alt ajanları içerir. Model, model: { id: "composer-2" } veya hesabınızın kullanabildiği başka bir id ile seçilir.

Bu parçaları ajan yapılandırmasında belirlersiniz.

Agent ve Run

SDK’daki iki ana nesne Agent ve Run’dır. Bir ajan; konuşma durumunu, çalışma alanı yapılandırmasını ve model ayarlarını tutar. Bir run, o ajana gönderilen tek bir istemdir; kendi akışına, durumuna, sonucuna ve iptal tutamacına sahiptir.

Bu ayrım önemlidir, çünkü bulut ajanları her ajan için bir etkin run zorunluluğu uygular. İlk çalışma sürerken ikinci bir istem göndermeye çalışırsanız, API 409 agent_busy döndürür. Paralel çalıştırmalar için ayrı run’lar değil, ayrı ajanlar oluşturursunuz.

Olayları akışla alma

Her run, bir async yineleyici olan run.stream() aracılığıyla bir olay akışı sunar. Her olayın bir type alanı vardır. Mevcut herkese açık betada SDK, system, user, assistant, tool_call, thinking, status, request ve task olayları yayar. Belgelenmiş bir connection:reconnecting olayı yoktur; yeniden bağlanmalar SDK içinde ele alınır.

Daha alt düzey güncellemeler için, agent.send() ayrıca onDelta ve onStep geri çağrılarını kabul eder.

Cursor SDK’yı Kurma

Kurulum sadece Node, TypeScript ve bir Cursor API anahtarından ibarettir.

Önkoşullar

Gerekenler:

• Node.js 22 veya daha yeni. Paket resmen Node 18 ve üzerini destekler, ancak Node 22 resmi yemek kitabı örnekleriyle eşleşir ve aşağıda --env-file bayrağıyla .env dosyasının yüklenmesini destekler.

• Bulut ajanları için Pro (aylık 20 ABD doları) veya üzeri bir Cursor hesabı.

• Temel TypeScript bilgisi.

• tsx ile TypeScript’i derlemeden çalıştırmak.

SDK’yı ve TypeScript araçlarını kurun:

SDK’yı yükleyin

Yeni bir klasörde:

npm init -y
npm install @cursor/sdk
npm install --save-dev typescript tsx @types/node

package.json dosyanıza "type": "module" ekleyin ki içe aktarmalar ESM olarak çalışsın. Ardından, üst düzey await ve açıkça async temizlemeyi destekleyen bir tsconfig.json ekleyin:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022", "ESNext.Disposable"],
    "strict": true,
    "esModuleInterop": true
  }
}

Bir Cursor API anahtarı alın

Anahtar başlangıçta cursor.com/dashboard/cloud-agents altında üretiliyordu, ancak taşındı ve artık cursor.com/dashboard/integrations adresindedir. Bir kılavuz “Cloud Agents”a işaret ediyorsa, bunun yerine Integrations’a bakın.

Integrations üzerinden User API Keys üretin. Görsel: Yazar.

Oradan bir Kullanıcı API Anahtarı üretin ve CURSOR_API_KEY olarak saklayın:

echo 'CURSOR_API_KEY=crsr_your_key_here' > .env

.env dosyasını .gitignore’a ekleyin. SDK doğrudan process.env okur; sizin için .env dosyalarını yüklemez.

Proje yapısı

Klasör düzeni: package.json, tsconfig.json, .env ve betikleriniz için src/. İhtiyaç duyduğunuzda kancalar, beceriler ve alt ajanlar için bir .cursor/ klasörü ekleyin.

İlk Yerel Cursor Ajanınız

İlk örnek kasıtlı olarak küçüktür. Yerel bir ajan oluşturur, tek bir istem gönderir, yanıtı akışla alır ve ajanı kapatır.

Yerel bir ajan oluşturun

Şunu oluşturun: src/01-quickstart.ts:

import { Agent, type SDKMessage } from "@cursor/sdk";

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
});

Agent.create(), ajan herhangi bir iş yapmadan önce bir tutamak döndürür. local: { cwd: process.cwd() } ajanı geçerli çalışma dizinine yönlendirir. SDK async temizlemeyi destekler; eğitim kodunda, await using sürüm sorularından kaçındığı için açık bir finally bloğunu tercih ederim.

Bir istem gönderin ve yanıtı akışla alın

Bir istem göndermek, kendi akışına ve durumuna sahip bir Run nesnesi döndürür. Bu örnek, akışı bir for await döngüsünde okur ve yalnızca assistant metnini yazdırır.

try {
  const run = await agent.send(
    `Write a terminal-friendly summary for a screenshot.

Output exactly:
Local agent summary
- Purpose: demonstrates a local Cursor SDK agent.
- Key files: src/01-quickstart.ts, package.json, tsconfig.json.
- SDK action: creates an agent and streams assistant text.

Rules:
Print exactly those three bullets.
No Markdown bold.
No extra explanation.`,
  );

  for await (const event of run.stream()) {
    if (event.type !== "assistant") continue;
    for (const block of event.message.content) {
      if (block.type === "text") {
        process.stdout.write(block.text);
      }
    }
  }

  const result = await run.wait();
  const duration = result.durationMs === undefined ? "" : `duration=${result.durationMs}ms`;
  console.log(`\n[done] status=${result.status}${duration}`);
} finally {
  await agent[Symbol.asyncDispose]();
}

Ajan, thinking, tool_call ve status dahil birkaç olay türü yayar. Bu örnek, görünür yanıt olduğu için assistant metnini filtreler. event.message.content akış için türlenmiştir ve kullanılabilirdir, ancak blok tabanlıdır ve araç çağrılarını içerebilir. Yalnızca nihai metne ihtiyacınız varsa, akışı atlayın ve run.wait() sonrasında result.result’ı okuyun. durationMs aleni ama isteğe bağlıdır, bu yüzden örnek onu isteğe bağlı olarak ele alır.

Hataları ele alın

SDK, CursorAgentError’ı genişleten türlenmiş hatalar fırlatır. Yaygın durumlar: hatalı anahtar için AuthenticationError, geçersiz model id için ConfigurationError, RateLimitError, IntegrationNotConnectedError ve NetworkError.

import { CursorAgentError } from "@cursor/sdk";

try {
  // ... agent code
} catch (error) {
  if (error instanceof CursorAgentError) {
    console.error([${error.code ?? "unknown"}] ${error.message});
    if (error.isRetryable) {
      console.error("Retryable. Try again in a moment.");
    }
  } else {
    throw error;
  }
}

isRetryable bayrağı, tekrar deneme mantığınızın kontrol etmesi gereken işarettir. Ağ hataları ve hız sınırlamaları yeniden denenebilir; hatalı yapılandırma ve kimlik doğrulama yeniden denenemez.

Çalıştırın

Dosyayı kaydedin ve Node’un .env yükleyicisi ve tsx ile çalıştırın.

node --env-file=.env --import tsx/esm src/01-quickstart.ts

--env-file=.env bayrağı, betik başlamadan önce CURSOR_API_KEY ’i yükler. Betik, assistant metnini yazdırmalı ve ardından tek satırlık bir durum altlığı göstermelidir. Kimlik doğrulama hatası görürseniz, .env ’nizi kontrol edin ve anahtarın Integrations panosundan üretildiğini doğrulayın.