Hướng dẫn Cursor SDK: Chạy tác nhân viết mã với TypeScript

Cursor công bố TypeScript SDK vào cuối tháng 4 năm 2026 và phát hành bản beta công khai. Gói được phát hành dưới tên @cursor/sdk và chạy từ các môi trường Node như script, job CI và dịch vụ backend.

Khác biệt chính so với dùng Cursor trong trình soạn thảo là nơi tác vụ bắt đầu. Thay vì mở chat và tự gõ prompt, mã của bạn sẽ tạo tác nhân, gửi tác vụ, stream sự kiện, chờ kết quả và xử lý lỗi.

Trong hướng dẫn này, chúng ta thiết lập SDK, chạy quickstart cục bộ, rồi xây dựng dự án chính: một tác nhân đám mây sửa lỗi trong repo GitHub và mở pull request. Tôi cố tình giữ lỗi nhỏ để luồng SDK dễ quan sát. Sau đó, chúng ta sẽ đề cập đến các điểm mở rộng và kiểm tra an toàn cần có trước khi áp dụng mẫu này. Dự án đám mây sử dụng một repo đi kèm chứa script khởi chạy và dự án mục tiêu.

SDK đang ở giai đoạn beta công khai, vì vậy hãy kiểm tra tài liệu chính thức trước khi tái sử dụng mã này trong dự án dài hạn.

Cursor SDK là gì?

Cursor SDK là một gói TypeScript, @cursor/sdk, cho phép bạn tạo và chạy các tác nhân Cursor từ mã. Nó cung cấp quyền truy cập vào:

• Chạy tác nhân cục bộ và trên đám mây.
• Các công cụ codebase của Cursor, bao gồm indexing, search, grep, máy chủ MCP, skills, hooks và subagent.
• Các mô hình khả dụng qua tài khoản Cursor của bạn, bao gồm Composer 2, GPT-5.5 và Claude.

SDK sử dụng cùng hệ thống tác nhân như Cursor IDE, CLI và ứng dụng web. Khác biệt là bạn gọi nó từ TypeScript.

Khi nào nên dùng SDK

SDK phù hợp với các tác vụ nên được khởi chạy từ mã thay vì từ người dùng gõ trong trình soạn thảo. Tôi sẽ dùng cho một job CI yêu cầu tác nhân kiểm tra bài kiểm thử thất bại, một webhook tạo nhánh để sửa lỗi, hoặc một công cụ nội bộ chạy tác vụ cố định của tác nhân từ một biểu mẫu.

SDK so với ứng dụng Cursor

SDK là một cách khác để dùng tác nhân Cursor, bên cạnh Cursor IDE và cursor agent CLI.

Dùng IDE cho chat trong trình soạn thảo. Dùng CLI cho prompt trong terminal. Dùng SDK khi mã TypeScript cần tạo tác nhân, gửi tác vụ và xử lý kết quả. Như đã đề cập ở trên, CLI không hỗ trợ khóa nhà cung cấp bên ngoài; SDK cũng chỉ xác thực qua khóa API của Cursor.

Cách các thành phần của Cursor SDK kết nối với nhau

Trước khi viết mã, nên nắm vài đối tượng và lựa chọn runtime mà SDK cung cấp.

Kiến trúc Cursor SDK trên ba runtime. Hình do Tác giả thực hiện.

Ba runtime

SDK hỗ trợ ba nơi một tác nhân có thể chạy.

Trong bài này, chúng ta dùng cục bộ và đám mây Cursor. Tự lưu trữ đám mây, như trên, chủ yếu dành cho gói Enterprise. Mã SDK thay đổi qua khóa cấu hình bạn truyền: local hoặc cloud.

Runtime, công cụ và mô hình

Một lượt chạy trong SDK có ba phần. Runtime là nơi thực thi. Công cụ tác nhân gồm indexing, search, gọi công cụ MCP, skills, hooks và subagent. Mô hình được chọn với model: { id: "composer-2" } hoặc id khác mà tài khoản của bạn có thể dùng.

Bạn thiết lập các phần này trong cấu hình tác nhân.

Agent và Run

Hai đối tượng chính trong SDK là Agent và Run. Một tác nhân giữ trạng thái hội thoại, cấu hình workspace và thiết lập mô hình. Một run là một prompt gửi tới tác nhân đó, với luồng, trạng thái, kết quả và tay cầm hủy riêng.

Phân tách này quan trọng vì tác nhân đám mây chỉ cho phép một run hoạt động trên mỗi tác nhân. Nếu bạn cố gửi prompt thứ hai khi prompt đầu còn chạy, API trả về 409 agent_busy. Để chạy song song, bạn tạo các tác nhân riêng, không phải nhiều run trên cùng một tác nhân.

Stream sự kiện

Mỗi run cung cấp một luồng sự kiện qua run.stream(), là một async iterator. Mỗi sự kiện có trường type. Trong bản beta công khai hiện tại, SDK phát ra các sự kiện system, user, assistant, tool_call, thinking, status, request và task. Không có sự kiện connection:reconnecting được tài liệu hóa; việc kết nối lại được xử lý bên trong SDK.

Để nhận cập nhật mức thấp hơn, agent.send() cũng chấp nhận callback onDelta và onStep.

Thiết lập Cursor SDK

Thiết lập chỉ cần Node, TypeScript và một khóa API Cursor.

Điều kiện tiên quyết

Bạn cần:

• Node.js 22 hoặc mới hơn. Gói chính thức hỗ trợ Node 18 trở lên, nhưng Node 22 khớp với ví dụ cookbook chính thức và hỗ trợ cờ --env-file dùng bên dưới để nạp .env.

• Tài khoản Cursor gói Pro (20 USD/tháng) hoặc cao hơn để dùng tác nhân đám mây.

• Hiểu biết cơ bản về TypeScript.

• tsx để chạy TypeScript không cần biên dịch.

Cài SDK và công cụ TypeScript:

Cài đặt SDK

Trong một thư mục mới:

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

Thêm "type": "module" vào package.json để import hoạt động theo ESM. Sau đó thêm tsconfig.json hỗ trợ await cấp cao và giải phóng async tường minh:

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

Lấy khóa API Cursor

Khóa ban đầu được tạo tại cursor.com/dashboard/cloud-agents, nhưng nó đã chuyển sang cursor.com/dashboard/integrations. Nếu một hướng dẫn trỏ tới "Cloud Agents", hãy kiểm tra mục Integrations thay thế.

Tạo User API Keys từ Integrations. Hình do Tác giả thực hiện.

Tạo User API Key tại đó và lưu dưới dạng CURSOR_API_KEY:

echo 'CURSOR_API_KEY=crsr_your_key_here' > .env

Thêm .env vào .gitignore. SDK đọc trực tiếp process.env; nó không nạp tệp .env cho bạn.

Cấu trúc dự án

Bố cục thư mục: package.json, tsconfig.json, .env và src/ cho các script của bạn. Thêm thư mục .cursor/ cho hooks, skills và subagent khi cần.

Tác nhân Cursor cục bộ đầu tiên của bạn

Ví dụ đầu tiên cố ý nhỏ gọn. Nó tạo một tác nhân cục bộ, gửi một prompt, stream phản hồi và giải phóng tác nhân.

Tạo tác nhân cục bộ

Tạo 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() trả về một handle trước khi tác nhân làm bất kỳ việc gì. local: { cwd: process.cwd() } trỏ tác nhân vào thư mục làm việc hiện tại. SDK hỗ trợ giải phóng async; trong mã hướng dẫn, tôi thích dùng khối finally tường minh vì tránh các câu hỏi về phiên bản await using.

Gửi prompt và stream phản hồi

Gửi prompt trả về một đối tượng Run với luồng và trạng thái riêng. Ví dụ này đọc luồng trong vòng lặp for await và chỉ in văn bản của 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]();
}

Tác nhân phát ra một số loại sự kiện, gồm thinking, tool_call và status. Ví dụ này lọc lấy văn bản assistant vì đó là câu trả lời hiển thị. event.message.content có kiểu và dùng được cho stream, nhưng theo dạng block và có thể bao gồm lệnh gọi công cụ. Nếu bạn chỉ cần văn bản cuối cùng, hãy bỏ qua stream và đọc result.result sau run.wait(). durationMs là công khai nhưng tùy chọn, nên ví dụ xử lý như thuộc tính tùy chọn.

Xử lý lỗi

SDK ném ra các lỗi có kiểu, kế thừa từ CursorAgentError. Các trường hợp thường gặp gồm AuthenticationError với khóa sai, ConfigurationError khi id mô hình không hợp lệ, RateLimitError, IntegrationNotConnectedError và 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;
  }
}

Cờ isRetryable là thứ logic retry của bạn nên kiểm tra. Lỗi mạng và giới hạn tốc độ có thể retry; cấu hình sai và xác thực sai thì không.

Chạy

Lưu tệp và chạy bằng bộ nạp .env của Node và tsx.

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

Cờ --env-file=.env nạp CURSOR_API_KEY trước khi script chạy. Script sẽ in văn bản của assistant, rồi một dòng trạng thái chân trang. Nếu bạn thấy lỗi xác thực, hãy kiểm tra .env và xác nhận khóa được tạo từ bảng điều khiển Integrations.