Cursor 推出用于构建可编程编码代理的 TypeScript SDK，支持沙盒云虚拟机、子代理、钩子和基于代币的定价
I’m happy to translate the article for you, but I need the full text you’d like translated. Could you please paste the content (or the portion you want translated) here? I’ll keep the source line and all formatting exactly as you request.
概览
Cursor，这款 AI 驱动的代码编辑器，正向所有开发者开放其编码代理背后的核心技术。Cursor 团队宣布了 Cursor SDK 的公开测试版——这是一款 TypeScript 库，允许工程师以编程方式访问同一套运行时、工具链和模型，这些正是支撑 Cursor 桌面应用、CLI 和网页界面的动力。
这标志着 AI 编码工具定位方式的转变：它们不再仅仅是坐在开发者旁边的交互式助手，而是可以作为可部署的基础设施，组织能够将其接入现有系统。
如果你之前使用过 Cursor，你会把它当作一个 IDE，在那里实时与代理交互——让它编写函数、修复 bug 或解释代码。Cursor SDK 改变了访问模型。现在，代理不再需要开发者坐在键盘前手动操作，而是可以通过编程方式调用：从 CI/CD 流水线触发、后端服务，或直接嵌入到其他产品中。
核心理念： 以前必须“在” Cursor 中才能使用其代理。现在，你只需几行 TypeScript，即可在堆栈中的任何位置调用同样的代理。
入门
Installation is a single command:
npm install @cursor/sdkCreate an Agent instance, send it a task, and stream the response back — all in TypeScript:
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);
}The Agent.create() call accepts:
- apiKey – 您的 Cursor API 密钥。
- model – 要运行的模型标识符（例如
"composer-2"）。 - local 或 cloud 配置 – 决定执行位置。
解决的问题
构建快速、可靠且能够安全地在您的数据上运行的编码代理，需要大量的工程工作：
- 安全沙箱
- 持久化状态和会话管理
- 环境配置
- 上下文管理
当新模型发布时，团队通常必须重新编写代理循环才能利用它。Cursor SDK 消除这些复杂性，使团队能够专注于构建有用的代理，而不是维护底层基础设施。
Harness 功能
SDK 代理使用相同的 harness，该系统为 Cursor 自己的产品提供动力。这里的 “harness” 指的是一整套支持基础设施，使代理在单纯的 LLM 调用之外也能高效工作。关键组件包括：
代码库索引与检索
- 语义搜索、即时 grep 与索引，使代理在生成响应前能够检索到正确的代码上下文。
- 通过提供精准的检索，降低幻觉和不相关输出的概率。
外部工具集成
- 代理可以通过 stdio 或 HTTP 与外部工具和数据源连接。
- 配置可以通过
.cursor/mcp.json文件提供，或直接在 API 调用中内联。 - MCP（Model Context Protocol）是用于将工具接入代理运行时的开放标准。
可复用行为
- 代理会自动从仓库中的
.cursor/skills/目录读取行为定义。
钩子与可扩展性
.cursor/hooks.json文件允许你在云端、自托管或本地运行时观察、控制并扩展代理循环。- 这对于日志记录、护栏（guardrails）或自定义编排非常有用。
子代理、工具与多代理工作流
- 主代理可以通过 Agent 工具将子任务委派给 具名子代理，它们拥有自己的提示和模型。
- 实现多代理工作流，无需编写自定义编排代码。
- 子代理继承相同的 harness 能力，实现无缝协作。
定价模型（基于令牌）
SDK 采用基于令牌的定价结构，将费用与底层大语言模型的实际使用量对齐。开发者将根据代理交互过程中处理的令牌数量计费，无论是本地运行还是在云端运行。
结论
Cursor SDK 将 Cursor 强大的代码助手功能转化为可编程服务，可嵌入任何地方——从 CI 流水线到自定义开发工具。通过抽象掉沙箱、状态管理和上下文处理，它让团队专注于为产品带来真正价值的逻辑。