Cursor SDK ट्यूटोरियल: TypeScript के साथ कोडिंग एजेंट चलाएँ

Cursor ने अप्रैल 2026 के अंत में अपना TypeScript SDK घोषित किया और इसे पब्लिक बीटा के रूप में जारी किया। यह पैकेज @cursor/sdk के रूप में प्रकाशित है और स्क्रिप्ट्स, CI जॉब्स, और बैकएंड सर्विसेज जैसे Node परिवेशों से चलता है।

एडिटर में Cursor इस्तेमाल करने से मुख्य अंतर यह है कि टास्क कहाँ से शुरू होती है। चैट खोलकर खुद प्रॉम्प्ट टाइप करने के बजाय, आपका कोड एजेंट बनाता है, टास्क भेजता है, इवेंट्स स्ट्रीम करता है, परिणाम की प्रतीक्षा करता है और त्रुटियों को संभालता है।

इस ट्यूटोरियल में, हम SDK सेटअप करेंगे, एक लोकल क्विकस्टार्ट चलाएँगे, फिर मुख्य प्रोजेक्ट बनाएँगे: एक क्लाउड एजेंट जो GitHub रेपो में बग ठीक करता है और एक पुल रिक्वेस्ट खोलता है। मैं जानबूझकर बग छोटा रखता हूँ ताकि SDK का फ्लो स्पष्ट रहे। इसके बाद, हम उन एक्सटेंशन पॉइंट्स और सुरक्षा जाँचों को कवर करते हैं जिनकी पैटर्न अपनाने से पहले ज़रूरत होती है। क्लाउड प्रोजेक्ट एक सहायक रेपो का उपयोग करता है जिसमें लॉन्चर स्क्रिप्ट और लक्ष्य प्रोजेक्ट है।

SDK पब्लिक बीटा में है, इसलिए इसे किसी दीर्घकालिक प्रोजेक्ट में पुनः उपयोग करने से पहले आधिकारिक दस्तावेज़ जाँच लें।

Cursor SDK क्या है?

Cursor SDK एक TypeScript पैकेज है, @cursor/sdk, जो आपको कोड से Cursor एजेंट बनाने और चलाने देता है। यह आपको इन तक पहुँच देता है:

• लोकल और क्लाउड एजेंट रन।
• Cursor के कोडबेस टूल्स, जिनमें इंडेक्सिंग, सर्च, grep, MCP सर्वर्स, स्किल्स, hooks, और सबएजेंट्स शामिल हैं।
• आपके Cursor अकाउंट के माध्यम से उपलब्ध मॉडल्स, जिनमें Composer 2, GPT-5.5, और Claude शामिल हैं।

SDK Cursor IDE, CLI, और वेब ऐप जैसी ही एजेंट प्रणाली का उपयोग करता है। फर्क सिर्फ इतना है कि आप इसे TypeScript से कॉल करते हैं।

SDK कब उपयोग करें

SDK उन कार्यों के लिए उपयुक्त है जो किसी व्यक्ति द्वारा एडिटर में टाइप करने के बजाय कोड से शुरू होने चाहिए। मैं इसे ऐसे CI जॉब के लिए चुनूँगा जो किसी एजेंट से फेल होती टेस्ट की जाँच करने को कहे, ऐसे webhook के लिए जो बग फिक्स के लिए ब्रांच बनाए, या ऐसे इंटरनल टूल के लिए जो किसी फॉर्म से निश्चित एजेंट टास्क चलाए।

SDK बनाम Cursor ऐप

SDK, Cursor IDE और cursor agent CLI के साथ Cursor एजेंट्स का उपयोग करने का एक और तरीका है।

एडिटर चैट के लिए IDE का उपयोग करें। टर्मिनल प्रॉम्प्ट्स के लिए CLI का उपयोग करें। जब TypeScript कोड को एजेंट बनाना, टास्क भेजना, और परिणाम संभालना हो, तो SDK का उपयोग करें। ऊपर बताया गया है कि CLI बाहरी प्रोवाइडर कीज़ को सपोर्ट नहीं करता; SDK भी केवल Cursor API key से ऑथेंटिकेट करता है।

Cursor SDK कैसे एक साथ काम करता है

कोड लिखने से पहले, यह जानना उपयोगी है कि SDK किन कुछ ऑब्जेक्ट्स और रनटाइम विकल्पों को उजागर करता है।

तीन रनटाइम्स में Cursor SDK आर्किटेक्चर। चित्र: लेखक।

तीन रनटाइम

SDK तीन स्थानों का समर्थन करता है जहाँ एक एजेंट चल सकता है।

इस लेख में, हम लोकल और Cursor क्लाउड का उपयोग करते हैं। ऊपर सूचीबद्ध सेल्फ होस्टेड क्लाउड मुख्यतः एंटरप्राइज प्लान के लिए है। SDK कोड उस कॉन्फ़िग कुंजी से बदलता है जिसे आप पास करते हैं: local या cloud।

रनटाइम, टूल्स, और मॉडल्स

SDK के भीतर एक रन के तीन हिस्से होते हैं। रनटाइम वह जगह है जहाँ यह निष्पादित होता है। एजेंट टूल्स में इंडेक्सिंग, सर्च, MCP टूल कॉल्स, स्किल्स, hooks, और सबएजेंट्स शामिल हैं। मॉडल को model: { id: "composer-2" } या आपके अकाउंट द्वारा उपयोग किए जा सकने वाले किसी अन्य id से चुना जाता है।

आप इन हिस्सों को एजेंट कॉन्फ़िग में सेट करते हैं।

एजेंट और रन

SDK में दो मुख्य ऑब्जेक्ट्स हैं Agent और Run। एक एजेंट में बातचीत की स्थिति, वर्कस्पेस कॉन्फ़िग, और मॉडल सेटिंग्स होती हैं। एक रन वह एकल प्रॉम्प्ट है जो उस एजेंट को भेजा जाता है, जिसका अपना स्ट्रीम, स्टेटस, परिणाम, और कैंसिल हैंडल होता है।

यह विभाजन इसलिए मायने रखता है क्योंकि क्लाउड एजेंट एक एजेंट पर एक समय में केवल एक सक्रिय रन की अनुमति देते हैं। यदि आप पहले रन के दौरान दूसरा प्रॉम्प्ट भेजने की कोशिश करते हैं, तो API 409 agent_busy लौटाता है। चीजों को समानांतर में चलाने के लिए, आपको अलग-अलग रन के बजाय अलग-अलग एजेंट बनाने चाहिए।

स्ट्रीमिंग इवेंट्स

हर रन run.stream() के माध्यम से इवेंट्स की एक स्ट्रीम उजागर करता है, जो एक async iterator है। हर इवेंट में type फ़ील्ड होता है। वर्तमान पब्लिक बीटा में, SDK system, user, assistant, tool_call, thinking, status, request, और task इवेंट्स एमिट करता है। कोई दस्तावेजीकृत connection:reconnecting इवेंट नहीं है; री-कनेक्ट्स SDK के भीतर संभाले जाते हैं।

निम्न-स्तरीय अपडेट्स के लिए, agent.send() onDelta और onStep कॉलबैक्स भी स्वीकार करता है।

Cursor SDK सेटअप करना

सेटअप में सिर्फ Node, TypeScript, और एक Cursor API key चाहिए।

आवश्यकताएँ

आपको चाहिए:

• Node.js 22 या नया। पैकेज औपचारिक रूप से Node 18 या नया सपोर्ट करता है, लेकिन Node 22 आधिकारिक कुकबुक उदाहरणों से मेल खाता है और नीचे प्रयुक्त --env-file फ्लैग को सपोर्ट करता है ताकि .env लोड हो सके।

• क्लाउड एजेंट्स के लिए Pro ($20/माह) या उससे ऊपर का Cursor अकाउंट।

• मूलभूत TypeScript जानकारी।

• tsx ताकि TypeScript को बिना कंपाइल किए चलाया जा सके।

SDK और TypeScript टूल्स इंस्टॉल करें:

SDK इंस्टॉल करें

एक नए फ़ोल्डर में:

npm init -y
npm install @cursor/sdk
npm install --save-dev typescript tsx @types/nodeसंचालित द्वारा

अपने package.json में "type": "module" जोड़ें ताकि इम्पोर्ट्स ESM के रूप में काम करें। फिर एक tsconfig.json जोड़ें जो टॉप-लेवल await और explicit async disposal का समर्थन करे:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022", "ESNext.Disposable"],
    "strict": true,
    "esModuleInterop": true
  }
}संचालित द्वारा

Cursor API key प्राप्त करें

कुंजी मूल रूप से cursor.com/dashboard/cloud-agents के तहत जेनरेट की जाती थी, लेकिन यह स्थानांतरित होकर cursor.com/dashboard/integrations पर आ गई है। यदि कोई गाइड "Cloud Agents" की ओर इशारा करे, तो Integrations देखें।

Integrations से User API Keys जेनरेट करें। चित्र: लेखक।

वहाँ से एक User API Key जेनरेट करें और इसे CURSOR_API_KEY के रूप में स्टोर करें:

echo 'CURSOR_API_KEY=crsr_your_key_here' > .envसंचालित द्वारा

अपने .gitignore में .env जोड़ें। SDK सीधे process.env पढ़ता है; यह आपके लिए .env फाइल्स लोड नहीं करता।

प्रोजेक्ट संरचना

फ़ोल्डर लेआउट: package.json, tsconfig.json, .env, और src/ आपकी स्क्रिप्ट्स के लिए। जब ज़रूरत हो, hooks, स्किल्स, और सबएजेंट्स के लिए एक .cursor/ फ़ोल्डर जोड़ें।

आपका पहला लोकल Cursor एजेंट

पहला उदाहरण जानबूझकर छोटा है। यह एक लोकल एजेंट बनाता है, एक प्रॉम्प्ट भेजता है, प्रतिक्रिया को स्ट्रीम करता है, और एजेंट को dispose करता है।

एक लोकल एजेंट बनाएँ

यह बनाएँ: 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() कोई भी काम शुरू होने से पहले एक हैंडल लौटाता है। local: { cwd: process.cwd() } एजेंट को वर्तमान वर्किंग डायरेक्टरी की ओर इंगित करता है। SDK async disposal सपोर्ट करता है; ट्यूटोरियल कोड में, मैं एक स्पष्ट finally ब्लॉक पसंद करता हूँ क्योंकि इससे await using वर्ज़न से जुड़े सवालों से बचा जा सकता है।

प्रॉम्प्ट भेजें और प्रतिक्रिया स्ट्रीम करें

प्रॉम्प्ट भेजने पर एक Run ऑब्जेक्ट मिलता है जिसका अपना स्ट्रीम और स्टेटस होता है। यह उदाहरण for await लूप में स्ट्रीम पढ़ता है और सिर्फ assistant टेक्स्ट प्रिंट करता है।

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]();
}संचालित द्वारा

एजेंट कई प्रकार के इवेंट एमिट करता है, जिनमें thinking, tool_call, और status शामिल हैं। यह उदाहरण दृश्यमान उत्तर होने के कारण assistant टेक्स्ट को फ़िल्टर करता है। event.message.content टाइप्ड है और स्ट्रीमिंग के लिए उपयोगी है, लेकिन यह ब्लॉक-आधारित है और इसमें टूल कॉल्स भी हो सकते हैं। यदि आपको केवल अंतिम टेक्स्ट चाहिए, तो स्ट्रीम छोड़ें और run.wait() के बाद result.result पढ़ें। durationMs पब्लिक है पर वैकल्पिक, इसलिए उदाहरण इसे वैकल्पिक के रूप में हैंडल करता है।

त्रुटियाँ संभालें

SDK टाइप्ड एरर्स फेंकता है जो CursorAgentError को एक्सटेंड करते हैं। आम मामलों में खराब key के लिए AuthenticationError, गलत model id के लिए ConfigurationError, RateLimitError, IntegrationNotConnectedError, और 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;
  }
}संचालित द्वारा

वह फ़्लैग जिसे आपकी retry लॉजिक को जाँचना चाहिए, वह isRetryable है। नेटवर्क एरर्स और रेट लिमिट्स retryable हैं; खराब कॉन्फ़िगरेशन और ऑथेंटिकेशन नहीं।

चलाएँ

फ़ाइल सेव करें और Node के .env लोडर और tsx के साथ चलाएँ।

node --env-file=.env --import tsx/esm src/01-quickstart.tsसंचालित द्वारा

--env-file=.env फ्लैग स्क्रिप्ट शुरू होने से पहले CURSOR_API_KEY लोड करता है। स्क्रिप्ट को assistant टेक्स्ट प्रिंट करना चाहिए, फिर एक लाइन का स्टेटस फ़ूटर। यदि आपको ऑथेंटिकेशन एरर दिखे, तो अपनी .env जाँचें और पुष्टि करें कि कुंजी Integrations डैशबोर्ड से जेनरेट की गई थी।