《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 的其他模型。
探索雲端代理，瞭解如何在沙盒環境中並行運行。