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

Cursor SDK का उपयोग करके एक लोकल एजेंट चलाएँ, फिर एक क्लाउड एजेंट चलाएँ जो GitHub रेपो में एक छोटा बग ठीक करता है और एक पुल रिक्वेस्ट खोलता है।

अपडेट किया गया 25 सित॰ 2026 · 12 मि॰ पढ़ें

AI के साथ खोजें

ChatGPT Claude Perplexity

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 तीन स्थानों का समर्थन करता है जहाँ एक एजेंट चल सकता है।

रनटाइम	क्या करता है	कब उपयोग करें
लोकल	आपकी Node प्रक्रिया में एजेंट को इनलाइन चलाता है, फाइलें डिस्क से पढ़ता है	डेव स्क्रिप्ट्स, वर्किंग ट्री पर CI जाँचें, तेज़ पुनरावृत्ति
Cursor क्लाउड	Cursor द्वारा प्रबंधित आइसोलेटेड VM में आपका रेपो क्लोन करके चलाता है	समानांतर एजेंट्स, लंबे टास्क, डिसकनेक्ट के बाद भी जारी रन
सेल्फ होस्टेड क्लाउड	क्लाउड जैसा ही ढांचा, लेकिन आपके VMs और नेटवर्क पर	वे टीमें जिन्हें कोड, सीक्रेट्स, और बिल्ड आउटपुट अपने वातावरण के भीतर ही रखने की ज़रूरत है

इस लेख में, हम लोकल और 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 डैशबोर्ड से जेनरेट की गई थी।

लोकल एजेंट से स्ट्रीमिंग इवेंट्स। वीडियो: लेखक।

क्लाउड बग फिक्सिंग एजेंट बनाना

अगला उदाहरण लोकल फ़ोल्डर से Cursor के क्लाउड में क्लोन किए गए GitHub रेपो पर जाता है। टास्क अभी भी छोटी है: फेल होती auth टेस्ट को ठीक करें और एक पुल रिक्वेस्ट खोलें।

कब क्लाउड चुनें

क्लाउड एजेंट Cursor द्वारा प्रबंधित VMs में चलते हैं। वे रेपो क्लोन करते हैं, डेवलपमेंट एनवायरनमेंट सेट करते हैं, और तब भी जारी रहते हैं जब आपकी लोकल स्क्रिप्ट बाहर निकल जाती है। खत्म होने पर वे ब्रांच पुश कर सकते हैं और पुल रिक्वेस्ट खोल सकते हैं। समझौता यह है कि छोटे लोकल रन की तुलना में स्टार्टअप समय और टोकन उपयोग अधिक होता है।

SDK से शुरू किया गया क्लाउड रन। वीडियो: लेखक।

क्लाउड रन काम करते समय Cursor Web और डेस्कटॉप Agents Window में दिखाई देते हैं। SDK क्लाउड एजेंट्स डिफ़ॉल्ट सूची से फ़िल्टर किए गए होते हैं। Cursor Web में Filter > Source > SDK का उपयोग करें। डेस्कटॉप Agents Window में, साइडबार फ़ूटर का उपयोग करें: Show > SDK। यदि आपके पास bc- एजेंट id है, तो आप इसे सीधे https://cursor.com/agents/bc-... पर या डेस्कटॉप डीप लिंक के माध्यम से भी खोल सकते हैं। एक सरल नियम: जब इनमें से कोई भी सही हो, तो क्लाउड का उपयोग करें:

टास्क लोकल स्क्रिप्ट सेशन से अधिक समय ले सकती है।
आप आउटपुट के रूप में सिर्फ टेक्स्ट नहीं, बल्कि PR या ब्रांच चाहते हैं।
आप एक ही रेपो के खिलाफ समानांतर में कई एजेंट्स चलाना चाहते हैं।
एजेंट को आइसोलेटेड वातावरण में कोड (टेस्ट, बिल्ड) चलाने की ज़रूरत है।

छोटी लोकल जाँचों के लिए, लोकल रनटाइम का उपयोग करें।

एजेंट कॉन्फ़िगर करें

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

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

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  name: "Cloud bug fixer",
  model: { id: "composer-2" },
  cloud: {
    repos: [
      { url: "https://github.com/your-org/your-repo", startingRef: "main" },
    ],
    autoCreatePR: true,
  },
});

console.log(Started cloud agent ${agent.agentId});

repos एक array है, लेकिन क्लाउड v1 वर्तमान में प्रति एजेंट एक ही रेपो सपोर्ट करता है। startingRef वह ब्रांच या कमिट है जहाँ से एजेंट शुरू करता है। autoCreatePR: true Cursor से रन समाप्त होने पर एक पुल रिक्वेस्ट खोलने का अनुरोध करता है। GitHub अनुमतियाँ, इंटीग्रेशन स्थिति, खाली डिफ्स, या रेपो नियम फिर भी आपको PR के बजाय एक ब्रांच के साथ छोड़ सकते हैं।

एजेंट के रेपो क्लोन करने के लिए, आपके Cursor अकाउंट में GitHub इंटीग्रेशन सेटअप होना चाहिए। यदि यह कनेक्टेड नहीं है, तो SDK एक IntegrationNotConnectedError लौटाता है जिसमें helpUrl फ़ील्ड होता है।

टास्क भेजें और बाद में फिर जुड़ें

नीचे दिया पैटर्न एक टास्क भेजता है और फिर Agent.getRun() के माध्यम से परिणाम का इंतज़ार करता है। इससे, यदि मूल स्क्रिप्ट बाहर निकल जाए, तो कोई दूसरी प्रक्रिया बाद में फिर से कनेक्ट कर सकती है।

const run = await agent.send(
  "Find the failing test in the auth module, fix the bug, and add a regression test.",
);
console.log(Run ${run.id} in progress.);

const handle = await Agent.getRun(run.id, {
  runtime: "cloud",
  agentId: agent.agentId,
  apiKey: process.env.CURSOR_API_KEY!,
});

const result = await handle.wait();

const branch = result.git?.branches?.[0];
console.log(Status: ${result.status});
if (branch?.prUrl) {
  console.log(PR: ${branch.prUrl});
} else if (branch?.branch) {
  console.log(Branch: ${branch.branch});
}

आप लाइव आउटपुट के लिए रन को स्ट्रीम कर सकते हैं, लेकिन जब आपको केवल परिणाम चाहिए तो wait() पर्याप्त है। जब PR बनता है, URL result.git?.branches[0]?.prUrl पर लौटाया जाता है; क्लाउड v1 अभी कई रेपो सपोर्ट नहीं करता, इसलिए इंडेक्स 0 वही ब्रांच है जिसे जाँचना चाहिए। यदि PR URL नहीं है, तो branch?.branch देखें और PR मैन्युअली खोलें। यदि आप बाद में फिर से जुड़ने की योजना बनाते हैं, तो run.id और agent.agentId संभालकर रखें।

क्लाउड एजेंट से GitHub PR। वीडियो: लेखक।

इस बिंदु पर, पुल रिक्वेस्ट को किसी अन्य कोड बदलाव की तरह ही रिव्यू करें।

लोकल बनाम क्लाउड एक नज़र में

दोनों रनटाइम एक ही SDK का उपयोग करते हैं लेकिन अलग तरह से व्यवहार करते हैं।

क्षमता	लोकल	क्लाउड
कहाँ चलता है	आपकी Node प्रक्रिया	एक VM जिसे Cursor प्रबंधित करता है
फ़ाइल एक्सेस	आपकी डिस्क	सिर्फ क्लोन किया हुआ रेपो
डिसकनेक्ट के बाद जारी	नहीं	हाँ
PR खोलता है	नहीं	हाँ, जब रेपो अनुमतियाँ अनुमति दें
आर्टिफैक्ट्स लौटाता है	नहीं	हाँ (15-मिनट presigned URLs)
किसके लिए उपयोग करें	इटरेशन, चेकआउट पर CI	लंबे टास्क, समानांतर रन, PR आउटपुट

त्वरित जाँचों के लिए लोकल रन का उपयोग करें। जब आपको ब्रांच, PR, या आर्टिफैक्ट चाहिए, तो क्लाउड रन का उपयोग करें।

अन्य उदाहरण

बग फिक्सर ने मुख्य SDK फ्लो का उपयोग किया: एजेंट बनाएँ, टास्क भेजें, परिणाम की प्रतीक्षा करें, और आउटपुट की समीक्षा करें। Cursor की कुकबुक बड़े उदाहरणों में वही SDK कॉल्स दिखाती है:

agent-kanban क्लाउड एजेंट्स की सूची देता है, उन्हें स्टेटस या रेपो के अनुसार समूहित करता है, और आर्टिफैक्ट्स का प्रीव्यू दिखाता है।
coding-agent-cli लोकल और क्लाउड एजेंट्स को एक टर्मिनल टूल में रैप करता है।
app-builder एक चैट UI से लोकल एजेंट चलाता है और जनरेटेड React कोड का प्रीव्यू दिखाता है।

एक विवरण जिसे स्पष्ट रखना है वह है आर्टिफैक्ट हैंडलिंग। आर्टिफैक्ट्स केवल क्लाउड रन पर उपलब्ध हैं। लोकल एजेंट टेक्स्ट आउटपुट और त्वरित जाँचों के लिए उपयुक्त हैं। क्लाउड एजेंट उन कार्यों के लिए उपयुक्त हैं जिन्हें आउटपुट के रूप में फाइलें, ब्रांचेज़, या PR चाहिए।

MCP, स्किल्स, hooks, और सबएजेंट्स

SDK उसी प्रोजेक्ट एजेंट कॉन्फ़िग को पढ़ सकता है जो Cursor IDE में उपयोग करता है। बग फिक्सर को इसकी सारी ज़रूरत नहीं है, लेकिन जब एजेंट किसी वास्तविक रेपो में काम करता है तो ये हिस्से मायने रखते हैं।

MCP सर्वर्स

जैसा कि पहले बताया गया, MCP सर्वर्स एजेंट्स को बाहरी टूल्स से जोड़ते हैं। आप सर्वर्स को Agent.create() में inline पास कर सकते हैं या उन्हें .cursor/mcp.json में परिभाषित कर सकते हैं। यदि आप agent.send() में फिर से mcpServers पास करते हैं, तो वह रन send() से दिए सर्वर्स का उपयोग करेगा, न कि Agent.create() से। होस्टेड टूल्स के लिए HTTP MCP सर्वर्स का उपयोग करें। एजेंट के पास चलने वाले टूल्स के लिए stdio MCP सर्वर्स का उपयोग करें।

स्किल्स

स्किल्स .cursor/skills/ में markdown फाइलें होती हैं जो एजेंट को प्रोजेक्ट इंस्ट्रक्शंस देती हैं, जैसे टेस्ट फ्रेमवर्क विकल्प, API कॉन्वेंशंस, या रिलीज़ नियम। उनका उपयोग उस मार्गदर्शन के लिए करें जो रेपो में हर रन पर लागू होना चाहिए।

hooks

hooks .cursor/hooks.json में होते हैं और एजेंट लूप के विशिष्ट बिंदुओं पर चलते हैं। आम उपयोगों में फाइल एडिट्स के बाद formatting और निष्पादन से पहले विनाशकारी शेल कमांड्स को ब्लॉक करना शामिल है। सुरक्षा hooks के लिए, फेल-क्लोज़्ड व्यवहार उपयोग करें ताकि टूटा हुआ hook कार्रवाई को ब्लॉक कर दे।

सबएजेंट्स

सबएजेंट्स नामित एजेंट्स होते हैं जिन्हें मुख्य एजेंट केंद्रित काम, जैसे कोड समीक्षा या टेस्ट लेखन, के लिए कॉल कर सकता है। उन्हें .cursor/agents/*.md में या Agent.create({ agents: { ... } }) में inline परिभाषित करें। क्लाउड एजेंट चेक-आउट रेपो से प्रोजेक्ट सबएजेंट्स लोड करते हैं। यदि आप चाहते हैं कि लोकल एजेंट प्रोजेक्ट .cursor/ कॉन्फ़िग पढ़ें, तो लोकल एजेंट्स को local.settingSources: ["project"] की ज़रूरत है। हर सबएजेंट को संकीर्ण रखें।

सुरक्षा जाँचें

एजेंट्स के वास्तविक रेपो को छूने से पहले, सीमाएँ पहले से निर्धारित करें। यह वह हिस्सा है जिसे मैं नहीं छोड़ूँगा।

परमिशन का दायरा कसा हुआ रखें। एजेंट्स फाइलें पढ़ सकते हैं, कमांड्स चला सकते हैं, और उन सभी क्रेडेंशियल्स का उपयोग कर सकते हैं जिन्हें आप उन्हें उजागर करते हैं। एजेंट्स को सर्विस-वाइड क्रेडेंशियल्स नहीं, बल्कि रेपो-स्कोप्ड एक्सेस दें।
सीक्रेट्स को प्रॉम्प्ट्स से दूर रखें। प्रॉम्प्ट्स ट्रांसक्रिप्ट्स में जा सकते हैं। CURSOR_API_KEY और किसी भी अन्य टोकन के लिए environment variables का उपयोग करें, और याद रखें कि stdio MCP env मान उस रनटाइम तक पहुँचते हैं जहाँ सर्वर निष्पादित होता है।
मानव समीक्षा आवश्यक करें। यदि कोई क्लाउड एजेंट PR खोल सकता है, तो ब्रांच प्रोटेक्शन को मर्ज से पहले मानव रिव्यूअर की आवश्यकता रखनी चाहिए। autoCreatePR: true को ऑटो मर्ज के साथ तब तक न मिलाएँ जब तक रेपो लो-रिस्क न हो।
कास्ट और मॉडल चयन पर नज़र रखें। SDK उपयोग Cursor के टोकन-आधारित उपयोग पूल से ड्रा करता है। जैसा कि पहले उल्लेख किया गया, Composer 2 कोडिंग कार्यों के लिए एक मॉडल विकल्प है; यदि आपको देखना है कि आपका अकाउंट किन मॉडल ids का उपयोग कर सकता है, तो Cursor.models.list() कॉल करें।
रन को लॉग करें। run.conversation() एजेंट के टर्न्स का एक संरचित दृश्य लौटाता है। उन रन के लिए इसे स्टोर करें जिन्हें आपको बाद में डीबग या ऑडिट करना पड़ सकता है।

निष्कर्ष

इस आलेख में npm install @cursor/sdk, एक लोकल क्विकस्टार्ट, एक क्लाउड एजेंट जो पुल रिक्वेस्ट खोलता है, और रेपो एजेंट व्यवहार के मुख्य एक्सटेंशन पॉइंट्स कवर किए गए।

जब कोड को एजेंट शुरू करना और प्रबंधित करना हो, तो SDK का उपयोग करें। यदि टास्क सिर्फ एडिटर बातचीत है, तो आमतौर पर Cursor ऐप पर्याप्त है।

तुलना के लिए, हमारे Claude Agent SDK और OpenAI Agents SDK पर गाइड अन्य इकोसिस्टम में एजेंट APIs कवर करते हैं।

Author

Khalid Abdelaty

मैं एक डेटा इंजीनियर और कम्युनिटी बिल्डर हूँ, जो डेटा पाइपलाइनों, क्लाउड, और AI टूलिंग के साथ काम करता/करती हूँ, साथ ही DataCamp और उभरते डेवलपर्स के लिए व्यावहारिक, असरदार ट्यूटोरियल लिखता/लिखती हूँ।

क्या Cursor SDK Python या किसी अन्य भाषा के साथ काम करता है?

क्या मैं फ्री Hobby प्लान पर SDK का उपयोग कर सकता/सकती हूँ?

जो रन बहुत समय ले रहा है, उसे मैं कैसे रद्द करूँ?

यदि SDK में कोई प्रोग्रामेटिक callback नहीं है, तो hooks कहाँ फिट होते हैं?

क्या SDK प्रोडक्शन उपयोग के लिए तैयार है?

विषय

कृत्रिम बुद्धिमत्ता

DataCamp के साथ सीखें

कोर्स

Cursor के साथ सॉफ्टवेयर डेवलपमेंट

1 घंटा 30 मिनट

4.3K

Cursor के साथ प्रोडक्शन-रेडी कोड बनाएं। AI प्रॉम्प्ट, रिफैक्टरिंग, टेस्टिंग और उन्नत वर्कफ़्लो सीखें।

विवरण देखें

पाठ्यक्रम शुरू करें

लर्निंग पाथ

एआई एजेंट मूलभूत बातें

6 घंटा

जानें कि AI एजेंट आपके काम करने के तरीके और आपके संगठन के लिए मूल्य प्रदान करने के तरीके को कैसे बदल सकते हैं!