《Cursor文档》-在评测中运行 Cursor

使用 Cursor SDK，在自己的评测框架中运行 Cursor 的智能体循环。为 Cursor IDE、命令行界面和网页端提供支持的同一智能体可通过 TypeScript 编写脚本，因此你可以在自己的基准测试中为 Grok 4.6 (及我们支持的其他模型) 评分。

Artificial Analysis 和 SWE-rebench 等基准测试作者已使用它在排行榜上为 Cursor 评分。

为什么使用 SDK¶

评测框架需要通过稳定的编程接口与智能体交互：传入任务，获取会话记录和最终状态，并对结果评分。SDK 无需调用命令行界面即可满足这些需求：

真实的智能体循环。 工具调用、文件编辑、终端命令和推理均通过与产品相同的代码路径执行。
Grok 优先，支持多模型。 默认使用 Grok 4.6 进行评测，但 Cursor 模型目录中的任何模型都可通过同一 API 使用。
本地或沙盒化云端运行环境。 可在磁盘上的工作树中运行以快速迭代，也可使用 Cursor 托管的 VM 进行隔离、并行运行。
结构化流和结果。 提供带类型的 SDKMessage 事件、每步增量，以及包含模型、耗时和 Git 信息的最终 RunResult。

有关完整的 API，请参阅 Cursor SDK 参考文档。

设置¶

安装 SDK¶

npm install @cursor/sdk

获取 API 密钥¶

在 Cursor 仪表盘 → API 密钥中创建密钥。团队设置中的服务账户密钥同样可用。

export CURSOR_API_KEY="your-key"

选择运行环境¶

运行环境	功能	适用场景
本地	在磁盘上的工作树中运行智能体。	可复现的仓库任务，且你可控制检出内容。
云端	在已克隆仓库的 Cursor 托管隔离 VM 中运行。	并行运行、执行不受信任的代码，或本地没有仓库的框架。

评测 Grok 4.6¶

在本地工作树上针对 Grok 4.6 进行的单任务评测：

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

const result = await Agent.prompt(
  "Implement the failing tests in tests/string_utils.test.ts. Do not modify the tests.",
  {
    apiKey: process.env.CURSOR_API_KEY!,
    model: { id: "grok-4.6" },
    local: { cwd: "/path/to/task/checkout" },
  },
);

console.log(result.status);     // "finished" | "error" | "cancelled"
console.log(result.result);     // 最终的助手文本
console.log(result.durationMs); // 实际耗时（墙钟时间）

Agent.prompt() 会创建一个智能体，发送一条提示词，等待运行结束后释放资源。对于无状态评测任务，这是合适的基本操作。

运行完成后，使用现有框架中的任意方式对工作树评分 (测试运行器、评判模型、精确匹配检查器等) 。

获取会话记录的流式事件¶

大多数框架需要完整的会话记录，而非最终文本。启动一个长期运行的智能体，并流式接收 SDKMessage 事件：

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

await using agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "grok-4.6" },
  local: { cwd: taskCwd },
});

const run = await agent.send(taskPrompt);
const transcript: SDKMessage[] = [];

for await (const event of run.stream()) {
  transcript.push(event);

  if (event.type === "assistant") {
    for (const block of event.message.content) {
      if (block.type === "text") process.stdout.write(block.text);
    }
  }
  if (event.type === "tool_call" && event.status === "completed") {
    console.log(`[tool] ${event.name}`);
  }
}

const final = await run.wait();
saveTranscript(transcript, final);

run.stream() 会生成类型化事件，包括助手文本、思考过程、工具调用 (开始和完成) 及生命周期状态。流结束后，可从 Run 中读取最终元数据 (模型、时长、Git 信息) 。完整事件架构请参阅流事件。

评测其他模型¶

同一套评测框架代码可用于评测 Cursor 模型目录中的任何模型。只需替换 id：

const models = ["grok-4.6", "composer-2.5", "gpt-5.6-sol", "claude-opus-5", "gemini-3.1-pro"];

for (const id of models) {
  const result = await Agent.prompt(taskPrompt, {
    apiKey: process.env.CURSOR_API_KEY!,
    model: { id },
    local: { cwd: taskCwd },
  });

  recordScore(id, scoreTask(result));
}

智能体循环、工具 schema、提示词和流的结构在不同模型间保持一致，因此你衡量的是模型层面的差异，而非框架本身的变化。使用 Cursor.models.list() 列出支持的 ID。

在云端并行运行任务¶

对于大型评测集，可在隔离的云端 VM 中运行各项任务。VM 会克隆仓库、运行智能体，并将 Git 结果返回到您的框架。

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

async function runTask(task: EvalTask) {
  await using agent = await Agent.create({
    apiKey: process.env.CURSOR_API_KEY!,
    model: { id: "grok-4.6" },
    cloud: {
      repos: [{ url: task.repoUrl, startingRef: task.baseRef }],
    },
  });

  const run = await agent.send(task.prompt);
  const result = await run.wait();

  return {
    taskId: task.id,
    status: result.status,
    branch: result.git?.branches[0]?.branch,
    durationMs: result.durationMs,
  };
}

const results = await Promise.all(tasks.map(runTask));

每个智能体都在独立的 VM 中运行，因此你可以在速率限制和请求池允许的范围内尽可能扩大并行执行规模。有关 VM 的行为、生命周期和产物处理，请参阅云端代理。

任务级配置¶

SDK 提供了评测框架通常需要的配置能力：

自定义工具集。 在 Agent.create() 中内联配置 MCP 服务器，以限制或扩展工具。
子智能体。 定义主智能体可在任务执行期间生成的具名子智能体。
取消与超时。 调用 run.cancel() 以强制遵守实际时间限额。状态会变为 "cancelled"，部分输出仍可读取。
每步回调。 在 agent.send() 中使用 onStep 和 onDelta 选项，实现更细粒度的日志记录。

隐私与计费¶

SDK 运行适用与 IDE 和 Cloud Agents 运行相同的定价、请求池和隐私模式规则。评测流量会被标记，并显示在团队用量仪表盘的 SDK 标签下。为避免评测数据用于模型训练，请为运行框架的账户或团队开启隐私模式。

更高的速率限制¶

要大规模运行基准测试？¶

默认 API 速率限制适用于开发工作负载，而非完整的评测。如果您要在公开排行榜上对 Cursor 进行基准测试，或运行大规模内部评测，请发送电子邮件至 leerob@cursor.com，我们将为您提高限额。

后续步骤¶

浏览完整的 Cursor SDK 参考文档，了解所有选项、事件类型和错误类。
了解 Grok 4.6 以及 Cursor 的其他模型。
探索云端代理，了解如何在沙盒环境中并行运行。