# Cursor Features and Practical Usage 🧩 What if you could call Cursor's AI agent from inside your own scripts and CI checks? The `@cursor/sdk` package grants that wish with a scriptable TypeScript interface to the agent. 🏷️ Title: @cursor/sdk (TypeScript) 🔗 URL: 📘 Overview `@cursor/sdk` exposes the same Cursor agent that powers the IDE, CLI, and web app as a scriptable TypeScript interface. It's built for CI automation, embedded products, and orchestrating custom workflows. It's Node-first, and local agent code loads lazily so cloud-only consumers don't pay the startup cost. ⚙️ How It Works The core concepts are Agent (a stateful container holding conversation context and workspace config), Run (a single prompt submission with its own stream, status, and result), and SDKMessage (normalized stream events emitted during a run). ・`Agent.create()`: validates options and returns a handle immediately; you send prompts via `agent.send()`. ・local / cloud keys: choose where execution happens. `local` runs the agent loop inline in your Node process, while `cloud` runs it in a Cursor-hosted isolated VM with the repo cloned in (a self-hosted VM pool is also supported). ・"Local" only describes where the agent loop runs; model inference goes through Cursor's backend in both modes. ・`local.customTools` lets you expose your own functions as tools (local only). `Agent.prompt()` is a one-shot shortcut. 🛠️ Practical Usage Install with the exact, scoped package name via `npm install @cursor/sdk`. For a CI check against your local working tree, call `Agent.create()` with your `apiKey`, a `model` id, and a `local` cwd, then `agent.send()` a prompt, `await run.wait()`, and check `result.status === "finished"`. To run in the cloud, use the `cloud` key and set `autoCreatePR: true` to open a PR on finish. Authenticate via the `CURSOR_API_KEY` env var or an explicit `apiKey`, using either a user key or a service account key. 💡 Use Cases Run `Agent.prompt()` in PR CI to automate a security audit; use the `cloud` key to spin up many parallel agents that open PRs on separate branches for a large refactor; or wire an internal deployment-check API into the agent via `local.customTools` to embed it in your own workflow. ⚠️ Caveats In local mode, the agent runs shell commands and file edits without approval unless you configure sandboxing or hooks, so consider `local.sandboxOptions: { enabled: true }` in CI. There is no Python SDK; for other languages use the SDK Bridge, or call the Cloud Agents REST API directly. `Agent.resume()` drops inline `mcpServers`, so re-pass them, and model IDs can change, so confirm via `Cursor.models.list()`. #Cursor# #SDK#