Cursor SDK: TypeScript за програмни AI агенти [2026]

На 29 април 2026 г. Anysphere пусна Cursor SDK — TypeScript библиотека, която позволява на разработчиците да build-ват собствени AI агенти със същия runtime, harness и модели, които задвижват самия Cursor IDE. Дотук агентите бяха „вътре" в IDE-то — отваряте Cursor, казвате какво искате, агентът работи. С новия SDK Cursor се превръща в програмен инструмент: пускате агенти от CI/CD pipeline, вграждате ги в собствен SaaS продукт или ги run-вате на изолиран cloud VM. Идва точно тогава, когато OpenAI Agents Python още няма TypeScript версия и Claude Agent SDK работи единствено с Anthropic модели.

Накратко: Cursor SDK е TypeScript SDK на Anysphere в public beta за build-ване на програмни AI агенти, със същата infrastructure като Cursor IDE — codebase indexing, MCP сървъри, sandboxed cloud VMs, hooks и subagents. Подходящ за CI/CD автоматизация, custom developer tools и SaaS продукти с вградени агенти.

Ключови факти:

• Дата на пускане: 29 април 2026 г. (public beta за всички потребители)
• npm пакет: @cursor/sdk — npm install @cursor/sdk
• Default модел: Composer 2 — 200 000 context window, 200+ tokens/s, $0.50/$2.50 на M tokens
• Runtime опции: локален процес, Cursor cloud (dedicated VM със strong sandboxing), self-hosted workers
• Cursor планове: Hobby (безплатен), Pro $20/месец, Pro+ $60, Ultra $200, Teams $40/потребител
• Pricing модел на SDK-то: token-based consumption, по стандартните Cursor model rates
• Конкуренти: Claude Agent SDK (Sonnet 4.6 на $3/$15 + $0.08/session час), OpenAI Agents Python v0.14.8 (TypeScript все още не е наличен)

Какво е Cursor SDK и какъв проблем решава?

Cursor SDK е TypeScript библиотека, публикувана на 29 април 2026 г. от Anysphere, която експортира агентното ядро на Cursor IDE като програмна повърхност. Според официалния блог пост: „Същите агенти, които задвижват desktop приложението, CLI-то и web app-а, са достъпни с няколко реда TypeScript."

Cursor SDK решава реален бизнес проблем: build-ването на production AI агенти от нула изисква екип, който да реши secure sandboxing, durable session state, environment setup и context management — често 6-12 месеца инженерна работа за нещо, което не е core продукт. SDK-то предоставя това като commodity. Според MarkTechPost, точно това е competitive positioning-ът — не да се конкурира с GitHub Copilot като IDE, а да измести custom agent infrastructure-а на enterprise teams.

Cursor SDK идва в момент, в който пазарът на agent SDKs започва да се консолидира около три играча: Claude Agent SDK (преименуван от @anthropic-ai/claude-code на @anthropic-ai/claude-agent-sdk в началото на 2026 г.), OpenAI Agents Python v0.14.8 (Python-only към април 2026 г., TypeScript версия „планирана за бъдещ release") и сега Cursor SDK. Първият е обвързан с Anthropic моделите. Вторият — само за Python екипи. Cursor SDK е TypeScript-first с Composer 2 като default модел и достъп до всички модели, поддържани в Cursor IDE (включително GPT-5.5), през стандартните Cursor model rates.

Anysphere — компанията зад Cursor — има над 1 милион ежедневни потребители и около $2 милиарда годишни приходи (ARR) към март 2026 г.. Това дава на SDK-то нещо важно: гаранция, че infrastructure-ът е тестван от милион developers всеки ден — не е празна обвивка.

Какво включва Cursor SDK harness и какво остава извън него?

Cursor SDK експортира четири основни концепции, наследени от IDE-то: agent harness, runtime опции, extensibility points и session lifecycle. Всяка от тях има конкретно значение за production употреба.

Agent harness е „багажникът" — codebase indexing, semantic search, прозрачно управление на context-а. Агентът автоматично разбира кой файл е релевантен за конкретния prompt, без разработчикът да го inject-ва ръчно. Това е същата логика, която Cursor IDE използва — пренесена в програмен интерфейс.

Runtime опции са три:

• Локален runtime — local: { cwd: process.cwd() }. Агентът работи на машината, която го стартира. Бърз iteration loop, минимална latency. Подходящ за dev tools и CLI инструменти.
• Cloud runtime — Cursor предоставя dedicated VM със strong sandboxing, автоматично cloning на repository-то, configurable starting reference, full dev environment и auto PR creation. Сесиите оцеляват network drops и laptop sleep — рестартирате и продължавате.
• Self-hosted workers — за компании, които изискват network-isolated execution. Полезно при regulated workflows и data sovereignty изисквания.

Extensibility points — три механизма за customization:

• MCP сървъри — конфигурирате през .cursor/mcp.json или inline. Агентът автоматично получава достъп до external tools (databases, APIs, internal services).
• Skills — auto-loaded definitions от .cursor/skills/ директория в repository-то. Преизползваема логика без duplication между агенти.
• Hooks — .cursor/hooks.json файл за loop observation и control през всички runtimes. Подходящ за audit logging, custom guardrails, programmatic intervention.

Какво НЕ може Cursor SDK към момента: няма documented rate limits в официалната документация (важно за production planning), TypeScript-only (Python екипите трябва да чакат), и pricing-ът зависи изцяло от Cursor — което създава vendor lock-in върху model choice и cloud runtime.

Как работи Cursor SDK на практика?

Cursor SDK има минимален API, който прикрива по-голямата част от complexity-то. Ето пълен пример от инсталация до първи агент.

Стъпка 1: Инсталация и authentication.

npm install @cursor/sdk
export CURSOR_API_KEY="your_api_key"

API ключът се генерира от Cursor settings → API Keys. Ключовете са вързани към плана на акаунта — Pro план = Pro rate limits и model access.

Стъпка 2: Първи локален агент.

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

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

const run = await agent.send("Summarize what this repository does");
for await (const event of run.stream()) {
  console.log(event);
}

Очакван резултат: агентът индексира codebase-а, анализира файлове и stream-ва summary в console-а. Latency-то на първия prompt е по-високо (initial indexing), последващите са по-бързи.

Стъпка 3: Превключване към cloud runtime.

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  cloud: {
    repository: "https://github.com/myorg/myrepo",
    startRef: "main",
  },
});

const run = await agent.send("Add a /health endpoint and open a PR");

При cloud режим Cursor автоматично clone-ва repository-то на dedicated VM, изпълнява агента в sandbox-а и при успех push-ва branch + отваря PR. Подходящ за nightly tasks или CI/CD jobs.

Стъпка 4: CI/CD интеграция. Според Cursor community thread-а, типична GitHub Actions workflow изпълнява агент върху всеки PR за summarization, code review или CI failure root cause analysis. SDK-то се пуска като TypeScript script в actions/setup-node@v4 runner — токенът идва от GitHub secrets, output-ът се commit-ва обратно като comment.

Стъпка 5: Subagents за multi-agent workflows. Subagent-ите се delegate-ват през named Agent tool calls с custom prompts и модели. Главният агент може да extract-не задача, да я pass-не на specialized subagent (например „security review subagent" или „test generation subagent") и да агрегира резултатите. Полезно за large refactors, които изискват разделяне на отговорности.

За кого е подходящ Cursor SDK?

Cursor SDK е целево позициониран за конкретни use cases. Преди да платите $20-200 на месец за Cursor план, проверете дали попадате в правилната група.

Подходящ за:

• Платежоспособни TypeScript екипи, които вече използват Cursor IDE и искат същата експертиза в production агенти — без да build-ват infrastructure от нула.
• DevOps и платформени екипи, които автоматизират CI/CD, change management или infrastructure tasks. Cloud runtime-ът покрива изискванията за security и persistence.
• SaaS компании, които вграждат AI агенти в собствените си продукти — например за customer support automation или onboarding workflows.
• Бутикови consultancy фирми, които build-ват custom AI решения за клиенти — SDK-то ускорява time-to-market значително.

НЕ е подходящ за:

• Python-first екипи — изчакайте OpenAI Agents Python или хибридна архитектура; Cursor SDK няма Python алтернатива към април 2026 г.
• Single-developer hobby проекти — при инцидентна употреба, Claude Agent SDK с Pro/Max абонамент е по-евтин от Cursor Pro план.
• Регулирани отрасли с задължителна data sovereignty — въпреки self-hosted workers опцията, default cloud runtime-ът работи на Cursor infrastructure (САЩ-базирана). Legal review е задължителен.
• Екипи, които искат специфичен model lock-in (например „само Claude Opus 4.7") — Cursor SDK работи най-добре с Composer 2 default; смяна на моделите минава през Cursor pricing layer.

Сравнение на Cursor SDK с алтернативите

Към 29 април 2026 г. на пазара има три сериозни TypeScript/Python agent SDK-та. Според Cursor community thread-а и OpenAI Agents GitHub repo-то v0.14.8 (април 2026), картата на цените изглежда така: Cursor SDK с Composer 2 на $0.50/$2.50 е най-евтиният; Claude Agent SDK с Sonnet 4.6 на $3/$15 предлага най-голям context; OpenAI Agents с GPT-5.5 на $5/$30 плюс sandbox $0.03-$1.92 на сесия е най-скъпият за heavy agentic употреба:

Cursor SDK печели за TypeScript-only екипи, които искат out-of-the-box codebase indexing и persistent cloud sessions без infrastructure setup. Composer 2 като default модел дава най-евтини tokens в категорията — $0.50/$2.50 е значително под Claude Sonnet 4.6 ($3/$15) и десетократно под GPT-5.5 ($5/$30 след поскъпването на 23 април 2026 г.).

Claude Agent SDK печели за екипи, които вече плащат Anthropic API, искат най-високо reasoning quality и могат да поемат $0.08/session час за Managed Agents. Sonnet 4.6 има 1M context window на standard pricing — приоритет за enterprise агенти, които работят с огромни codebases.

OpenAI Agents Python печели за Python-first екипи, които искат maximum model flexibility (100+ LLM-та през LiteLLM-style integration) и MIT-licensed open-source SDK. Минусът е липсата на TypeScript и sandbox costs, които стартират от $0.03/20-минутна сесия и стигат до $1.92 за 64GB containers.

Третата опция, която заслужава споменаване, е @anthropic-ai/claude-agent-sdk — преименуван от стария @anthropic-ai/claude-code пакет в началото на 2026 г. Migration пътят е документиран в официалния migration guide. Този SDK е инфраструктурата зад Claude Code, така че stability-та и quality bar-а са високи — но lock-in-ът към Anthropic моделите е реален trade-off.

Колко струва Cursor SDK и работи ли в България?

Cursor SDK използва Cursor account-а за authentication — pricing-ът наследява плановете на самия Cursor. Според официалната документация, към април 2026 г. плановете са:

SDK-то се таксува на token-based consumption — за всеки модел токените се мултиплицират по официалните Cursor rates от Models & Pricing страницата. При Composer 2 — $0.50 на M input + $2.50 на M output. При „faster" варианта на Composer 2 — $1.50/$7.50. При Auto mode (избира модел според задачата) — около $0.25/M cache read, $1.25/M input, $6.00/M output.

Работи ли от България? Да, без географски ограничения. Stripe приема карти, издадени от българските банки в еврозоната. От 1 януари 2026 г. България е в еврозоната — плащанията в EUR се обработват без конверсии.

Локален пример за БГ. Софийска fintech компания, която build-ва SaaS платформа за SME-клиенти, може да използва Cursor SDK за вграждане на customer onboarding agent — агентът обработва KYC документи, извлича данни и попълва форми. При средно 200 onboarding-а на месец и около 50 000 input + 30 000 output токена на сесия с Composer 2: input разход е $0.50 × 50 000 / 1 000 000 = $0.025 на сесия; output разход — $2.50 × 30 000 / 1 000 000 = $0.075 на сесия. Общо $0.10 на сесия × 200 сесии = около $20 на месец за токени, плюс Pro план $20 — общо около 40 EUR/месец. Сравнимо с part-time human onboarding agent.

Практически съвети за напреднали разработчици

Cursor SDK е нов, но няколко patterns вече се очертават като best practices от early adopters в community thread-а и Cursor cookbook repository.

1. Prefer cloud runtime за дълги задачи. Локалният runtime прекъсва, ако затворите laptop-а. Cloud runtime persist-ва — агентът може да run-не 30 минути, вие да тръгнете на обяд, и резултатът ви чака. За nightly automation, infrastructure changes или large refactors — винаги cloud.

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  cloud: { repository: process.env.GITHUB_REPO!, startRef: "main" },
  hooks: { onLongTask: (event) => console.log("Cloud session active:", event.sessionId) },
});

2. Използвайте .cursor/skills/ за reusable logic. Скилът е markdown файл със система от инструкции и tool definitions. Един скил може да дефинира „security review" процес, който се преизползва от 5 различни агента в monorepo-то — без duplication.

3. Hook-ове за audit logging. Production агенти трябва да оставят следа за compliance. .cursor/hooks.json поддържа onToolCall, onModelResponse и onError events — push-вайте ги към собствен logging stack (Datadog, Loki, OpenSearch). Това е задължително за GDPR-compliant deployments.

4. Subagents за разделяне на отговорности. Един master agent + 3-5 specialized subagents (security, tests, docs, refactor) дава по-добри резултати от един general-purpose агент. Pattern-ът: master delegate-ва, всеки subagent връща structured JSON, master агрегира.

const result = await agent.send("Refactor auth module + add tests + update docs", {
  subagents: ["test-generator", "doc-updater", "security-reviewer"],
});

5. Не разчитайте на default token limits. Cursor SDK pricing-ът се базира на token consumption — лесно е да изхарчите над $50 за час с Composer 2 Faster в production loop. Сложете budget caps в hooks (maxTokensPerSession) или external rate limiter, преди да push-нете в production.

Често задавани въпроси за Cursor SDK

Заключение: Заслужава ли си TypeScript SDK на Anysphere?

Cursor SDK решава реален проблем — TypeScript-екипите вече не трябва да build-ват agent infrastructure от нула. Composer 2 като default модел на $0.50/$2.50 е най-евтиното frontier-tier coding inference на пазара, а cloud runtime-ът с sandbox VM и persistent sessions покрива production needs без external dependencies. За екипи, които вече използват Cursor IDE, switch към SDK-то е low-friction — same models, same harness, same UX.

За кого определено да: TypeScript-first developer-екипи и платформени екипи с поне $20/месец usage budget; SaaS компании, които вграждат агенти в собствени продукти; CI/CD automation projects с persistence изисквания. Официалният launch блог на Cursor цитира customer story:

"We're excited about the SDK as a path to running our own programmatic agents on that same cloud runtime." — George Jacob, Senior Engineering Manager, Faire

Този customer story показва pattern, в който Cursor SDK замества custom-built agent infrastructure в e-commerce компания.

За кого определено не: Python-first екипи (OpenAI Agents Python е по-зрял избор); регулирани отрасли с strict data sovereignty (default cloud runtime е базиран в САЩ); екипи, които искат model lock-in извън Cursor (Claude Agent SDK или директен OpenAI API е по-евтин за specific-model deployments).

Конкретен следващ ход: инсталирайте npm install @cursor/sdk, генерирайте API key от Cursor settings и run-нете 5-минутния Hello World от официалния cookbook repository. Ако се вписва във workflow-а ви, започнете с локален runtime в hobby проект, преди да migrate-нете към cloud runtime в production.

Cursor SDK е в public beta — внимавайте с rate limits и pin-вайте версиите. Но като производствена инфраструктура, базирана на 1M+ daily Cursor users, той започва живота си с по-висок quality bar от повечето SDK launches на пазара. Препоръчван с резерви за beta status.

Допълнителни ресурси и документация

• Build programmatic agents with the Cursor SDK — официален launch блог
• @cursor/sdk npm пакет — current version, install command, basic API
• Cursor Models & Pricing документация — точните token rates за всеки модел
• Cursor SDK & Cloud Agents API community announcement
• Composer 2 Technical Report — model architecture, benchmarks, training methodology
• Claude Agent SDK Migration Guide — за сравнение
• OpenAI Agents Python GitHub repo — alternative за Python екипи