Tutorial Cursor SDK: Menjalankan Agen Koding dengan TypeScript

Cursor mengumumkan TypeScript SDK pada akhir April 2026 dan merilisnya sebagai public beta. Paket ini dipublikasikan sebagai @cursor/sdk dan berjalan di lingkungan Node seperti skrip, job CI, dan layanan backend.

Perbedaan utama dari penggunaan Cursor di editor adalah titik awal tugas. Alih-alih membuka chat dan mengetik prompt sendiri, kode Anda membuat agen, mengirim tugas, melakukan streaming event, menunggu hasil, dan menangani error.

Dalam tutorial ini, kita menyiapkan SDK, menjalankan quickstart lokal, lalu membangun proyek utama: agen cloud yang memperbaiki bug di repo GitHub dan membuka pull request. Saya sengaja membuat bugnya kecil agar alur SDK tetap terlihat jelas. Setelah itu, kita membahas titik ekstensi dan pemeriksaan keamanan yang diperlukan sebelum mengadaptasi polanya. Proyek cloud menggunakan repo pendamping dengan skrip peluncur dan proyek target.

SDK ini berstatus public beta, jadi periksa dokumentasi resmi sebelum menggunakan ulang kode ini dalam proyek jangka panjang.

Apa itu Cursor SDK?

Cursor SDK adalah paket TypeScript, @cursor/sdk, yang memungkinkan Anda membuat dan menjalankan agen Cursor dari kode. Ini memberi Anda akses ke:

• Jalankan agen secara lokal dan di cloud.
• Alat codebase Cursor, termasuk pengindeksan, pencarian, grep, server MCP, skills, hook, dan subagent.
• Model yang tersedia melalui akun Cursor Anda, termasuk Composer 2, GPT-5.5, dan Claude.

SDK menggunakan sistem agen yang sama seperti Cursor IDE, CLI, dan web app. Bedanya, Anda memanggilnya dari TypeScript.

Kapan menggunakan SDK

SDK cocok untuk tugas yang seharusnya dimulai dari kode alih-alih dari seseorang yang mengetik di editor. Saya akan memilihnya untuk job CI yang meminta agen memeriksa tes yang gagal, webhook yang membuat branch untuk perbaikan bug, atau alat internal yang menjalankan tugas agen tetap dari sebuah formulir.

SDK versus aplikasi Cursor

SDK adalah cara lain untuk menggunakan agen Cursor, di samping Cursor IDE dan cursor agent CLI.

Gunakan IDE untuk chat di editor. Gunakan CLI untuk prompt di terminal. Gunakan SDK ketika kode TypeScript perlu membuat agen, mengirim tugas, dan menangani hasil. Seperti disebutkan di atas, CLI tidak mendukung kunci penyedia eksternal; SDK juga hanya melakukan autentikasi melalui kunci API Cursor.

Cara Kerja Keseluruhan Cursor SDK

Sebelum menulis kode, ada baiknya memahami beberapa objek dan pilihan runtime yang diekspos SDK.

Arsitektur Cursor SDK pada tiga runtime. Gambar oleh Penulis.

Tiga runtime

SDK mendukung tiga tempat eksekusi agen.

Dalam artikel ini, kita menggunakan lokal dan Cloud Cursor. Cloud self-hosted, seperti tercantum di atas, terutama untuk paket Enterprise. Kode SDK berubah melalui kunci konfigurasi yang Anda berikan: local atau cloud.

Runtime, alat, dan model

Satu run di dalam SDK memiliki tiga bagian. Runtime adalah tempat eksekusinya. Alat agen mencakup pengindeksan, pencarian, pemanggilan alat MCP, skills, hook, dan subagent. Model dipilih dengan model: { id: "composer-2" } atau id lain yang dapat digunakan akun Anda.

Anda menetapkan bagian-bagian ini di konfigurasi agen.

Agent dan Run

Dua objek utama dalam SDK adalah Agent dan Run. Agen menyimpan status percakapan, konfigurasi workspace, dan pengaturan model. Run adalah satu prompt yang dikirim ke agen tersebut, dengan stream, status, hasil, dan handle pembatalannya sendiri.

Pemisahan ini penting karena agen cloud memberlakukan satu run aktif per agen. Jika Anda mencoba mengirim prompt kedua saat yang pertama masih berjalan, API mengembalikan 409 agent_busy. Untuk menjalankan secara paralel, buat agen terpisah, bukan run terpisah pada agen yang sama.

Streaming event

Setiap run mengekspos stream event melalui run.stream(), yang merupakan async iterator. Setiap event memiliki field type. Dalam public beta saat ini, SDK memancarkan event system, user, assistant, tool_call, thinking, status, request, dan task. Tidak ada event terdokumentasi connection:reconnecting; reconnect ditangani di dalam SDK.

Untuk pembaruan level lebih rendah, agent.send() juga menerima callback onDelta dan onStep.

Menyiapkan Cursor SDK

Persiapannya hanya Node, TypeScript, dan kunci API Cursor.

Prasyarat

Anda memerlukan:

• Node.js 22 atau lebih baru. Paket ini secara formal mendukung Node 18 atau lebih baru, tetapi Node 22 sesuai dengan contoh cookbook resmi dan mendukung flag --env-file yang digunakan di bawah untuk memuat .env.

• Akun Cursor pada Pro ($20/bulan) atau di atasnya untuk agen cloud.

• Pemahaman dasar TypeScript.

• tsx untuk menjalankan TypeScript tanpa kompilasi.

Instal SDK dan alat TypeScript:

Instal SDK

Di folder baru:

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

Tambahkan "type": "module" ke package.json agar import bekerja sebagai ESM. Lalu tambahkan tsconfig.json yang mendukung top level await dan disposal async eksplisit:

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

Dapatkan kunci API Cursor

Kunci awalnya dihasilkan di cursor.com/dashboard/cloud-agents, namun kini telah dipindahkan ke cursor.com/dashboard/integrations. Jika ada panduan yang menunjuk ke "Cloud Agents", periksa Integrations sebagai gantinya.

Hasilkan User API Keys dari Integrations. Gambar oleh Penulis.

Hasilkan User API Key dari sana dan simpan sebagai CURSOR_API_KEY:

echo 'CURSOR_API_KEY=crsr_your_key_here' > .env

Tambahkan .env ke .gitignore Anda. SDK membaca process.env secara langsung; SDK tidak memuat file .env untuk Anda.

Struktur proyek

Tata letak folder: package.json, tsconfig.json, .env, dan src/ untuk skrip Anda. Tambahkan folder .cursor/ untuk hook, skills, dan subagent saat Anda membutuhkannya.

Agen Cursor Lokal Pertama Anda

Contoh pertama sengaja dibuat kecil. Ini membuat agen lokal, mengirim satu prompt, melakukan streaming respons, dan membuang agen.

Buat agen lokal

Buat 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() mengembalikan handle sebelum agen melakukan pekerjaan apa pun. local: { cwd: process.cwd() } mengarahkan agen ke direktori kerja saat ini. SDK mendukung pembuangan async; dalam kode tutorial, saya lebih suka blok finally eksplisit karena menghindari pertanyaan versi await using.

Kirim prompt dan stream respons

Mengirim prompt mengembalikan objek Run dengan stream dan statusnya sendiri. Contoh ini membaca stream dalam loop for await dan hanya mencetak teks asisten.

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

Agen memancarkan beberapa tipe event, termasuk thinking, tool_call, dan status. Contoh ini memfilter teks assistant karena itulah jawaban yang terlihat. event.message.content bertipe dan dapat digunakan untuk streaming, tetapi berbasis blok dan mungkin menyertakan pemanggilan alat. Jika Anda hanya memerlukan teks akhir, lewati stream dan baca result.result setelah run.wait(). durationMs bersifat publik tetapi opsional, jadi contoh menanganinya sebagai opsional.

Tangani error

SDK melempar error bertipe yang memperluas CursorAgentError. Kasus umum termasuk AuthenticationError untuk kunci yang salah, ConfigurationError untuk id model yang tidak valid, RateLimitError, IntegrationNotConnectedError, dan 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;
  }
}

Flag isRetryable adalah yang harus diperiksa oleh logika retry Anda. Error jaringan dan rate limit dapat dicoba ulang; konfigurasi buruk dan autentikasi tidak.

Jalankan

Simpan file dan jalankan dengan loader .env milik Node dan tsx.

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

Flag --env-file=.env memuat CURSOR_API_KEY sebelum skrip dimulai. Skrip harus mencetak teks asisten, lalu footer status satu baris. Jika Anda melihat error autentikasi, periksa .env Anda dan pastikan kunci dihasilkan dari dasbor Integrations.