cqbase.net · 中英双语

CQBase 上下文库

Context & Query Base

工作流

Cursor 宣布 Agent SDK

官方帖说明可以用代码定义代理:提示写在 Markdown,工具写在 TypeScript。

Cursor 官方账号在 2026 年 10 月 26 日发帖,说 Agent SDK 已经可用:用代码定义代理,提示放在 Markdown,工具用 TypeScript 写,可以部署在他们的托管环境,也可以跑在你自己的机器上,并带有评测,方便比较每次修改。

这是产品公告,不是教程正文。要上手就跟着帖子里的文档链接走,把提示和工具放进版本库,密钥留在环境变量里。评测要使用你自己的任务,不要只用公告里的演示。互动数字采集于 2026 年 11 月 15 日。

本页是导读,不是原文。

注意(核验日期 2026-11-15):这是产品发布向的帖子,时效性强。本次复查没有重新打开原帖,也没有核对 Cursor 是否已改名或调整 Agent SDK 的入口。

解决什么问题

本站这条条目来自 Cursor 官方账号 2026-10-26 的产品公告,不是某个开源仓库。今天要找的产品是 Cursor 的 Agent SDK:用版本库里的 Markdown 和 TypeScript 定义、测试、评估并部署一个代理。提示可以写在 bot/instructions.md,工具写成 bot/tools/ 下的 TypeScript,评测放在项目根目录的 evals/。官方说明它使用与 Bugbot、Security Review 等产品相同的 Cursor SDK harness。文档在 cursor.com/docs/agent-sdk。

它不是 Cursor 编辑器里的 Agent 或 Chat 面板,也不是让你在 IDE 里改当前仓库代码的那套界面。官方文档还把它和 Cursor Automations、以及无需写代码即可配置的 Grok Bot 做了对照:Agent SDK 适合你希望把指令、工具和评测当作可审查、可版本管理的代码来维护,并且可以部署到 Cursor 托管环境或自己的基础设施。

适合谁

适合已经有明确代理任务(例如评审 Pull Request、分诊 issue),并希望把提示词、工具和回归评测放进 Git 的团队。你可以用官方 CLI 在本地开发,用 agent-sdk deploy 部署到 Cursor 托管,或按文档用 agent-sdk serve 自托管。它不适合只想在 Cursor 窗口里随手提问、并不准备维护一个代理项目的人。

请先在本地完成登录、脚手架和一次不产生外部副作用的 run,再连接 GitHub、Slack 等通道。密钥和 Cursor 凭据只放在环境变量或官方文档列出的登录状态里,不要写进仓库。本页依据的是官方文档和 npm 包装说明,不是条目里那则公告的原文转载。

怎么装

核验日期为 2026-11-16(Asia/Shanghai)。命令以官方文档为准。需要 Node.js 22.13 或更新。当前安装包是 undefined;文档写明它此前名为 @cursor/bdk。当天 npm 上 @grok/agent-sdk 与 @cursor/bdk 的 latest 都是 0.6.0(发布时间约为 2026-11-04 00:45 Asia/Shanghai)。不要把它和另一个仍在发布的 npm 包 undefined 混为一谈,后者的简介是 “TypeScript SDK for Cursor agents”,并不是这套 Agent SDK 文档里的安装包。@cursor/agent-sdk 在当天返回 404。

npm install --global @grok/agent-sdk
agent-sdk login
agent-sdk init ./my-bot
cd my-bot
agent-sdk dev

agent-sdk login 会走浏览器登录。官方写明:本地的 run 和 eval 需要 Cursor 凭据。项目布局以 bot/ 为主,评测在旁边的 evals/。CLI 参考见 Agent SDK CLI。旧命令 bdk 仍然可用。

许可证不是开源 SPDX。npm 上写的是 SEE LICENSE IN LICENSE.md;0.6.0 包装内的 LICENSE.md 标题为 “Cursor SDK License”,声明版权归 Anysphere Inc.,使用须遵守 Cursor 服务条款。本文只转述这一包装说明,不作额外授权解释。

自托管时,官方要求在 Node 22.13 或更新的环境下运行 agent-sdk serve,并明确写了不要使用 Bun。部署到 Cursor 托管前,文档强调 deploy 构建的是已经推送的 Git 引用,未提交的改动不会发布。这些步骤涉及密钥和网络暴露,请按 Deployment 原文操作,本文不展开成可直接上线的清单。

一个实际例子

下面只做一个本地脚手架和一次自我介绍式的 run,用来确认 CLI 和登录是否可用。不要在这一步连接真实的仓库写操作。本次没有实跑,因此不编造代理回复。

  1. 确认 node -v 为 22.13 或更新,然后执行 npm install --global @grok/agent-sdk。
  2. 运行 agent-sdk login,在浏览器里完成登录。
  3. 执行 agent-sdk init ./pr-reviewer-demo && cd pr-reviewer-demo。
  4. 打开 bot/instructions.md,把它改成几行你自己的说明,例如:只介绍自己是一个演示用评审代理,在没有被要求调用工具时不要访问外部系统。
  5. 另开一个终端运行:
agent-sdk validate --dir .
agent-sdk run --dir . --message "Introduce yourself in one sentence. Do not call any tools."
  1. 预期效果:validate 能通过项目检查,run 在已登录的前提下返回一句简介,并且没有调用需要写权限的工具。若登录未完成,官方说明模型回合会失败。完整的 PR 评审教程见 Quickstart,其中的 GitHub 示例在未得到你明确允许前不要对真实 Pull Request 发表评论。

常见坑

  • 把 Agent SDK 当成 Cursor 编辑器内置 Agent 的另一个名字。二者都能「用模型做事」,但 SDK 维护的是独立的 Markdown / TypeScript 项目,入口是 agent-sdk CLI,不是编辑器聊天框。
  • 安装错包。当前文档要求 @grok/agent-sdk(曾用名 @cursor/bdk)。@cursor/sdk 是另一个包;@cursor/agent-sdk 在核验当天并不存在。
  • 未登录就执行 run 或 eval。官方写明这两类命令需要 Cursor 凭据。
  • 在低于 22.13 的 Node,或用 Bun 去自托管。文档明确了运行时要求。
  • 在本地改完代码后直接 deploy,却没有先推送 Git 引用。官方写明未提交改动不会随部署发布。
  • 把专有许可当成可以任意再分发的开源许可证。包装内的 LICENSE.md 指向 Cursor 服务条款。

FAQ

这是 Cursor 编辑器,还是一套独立的代理 SDK?

这是独立的 Agent SDK:用代码定义可部署的代理。它可以使用 Cursor 的托管或自托管运行时,但不是编辑器里的 Agent 面板,也不是本站可能另收的编辑器规则或技能条目。

为什么安装包叫 @grok/agent-sdk?

这是 2026-11-16 官方文档和 npm 上的现行包名。文档写明它以前叫 @cursor/bdk,该旧名当天仍能在 npm 上解析到相同的 0.6.0。本文以官方文档为准,不猜测更名原因。

可以自由再分发这个 SDK 吗?

不能按开源许可证来假设。npm 指向包装内的 LICENSE.md,该文件称为 Cursor SDK License,并要求遵守 Cursor 服务条款。请阅读该文件和条款后再决定使用范围。

官方文档里的 Grok Bot 和 Agent SDK 是一回事吗?

不是。官方对照表把它们分成两列:Grok Bot 适合在应用里配置指令和工具、不必写代码;Agent SDK 适合把 Markdown 和 TypeScript 项目纳入版本控制和评测。本文只介绍 Agent SDK。

必须部署到 Cursor 托管吗?

不是。你可以先在本地用 agent-sdk dev 和 agent-sdk run 开发。官方也提供 agent-sdk serve 自托管,以及 agent-sdk deploy 发布到托管环境。自托管前请阅读部署文档中的密钥、鉴权和 Node 版本要求。

来源与许可

本条目的原始来源是 Cursor 官方账号的产品公告,上手路径以 Agent SDK 文档 和 npm 包 @grok/agent-sdk 为准。许可为包装内 LICENSE.md 所述的 Cursor SDK License,使用须遵守 Cursor 服务条款。本文依据 2026-11-16 查阅的官方文档、CLI 说明、Quickstart 和 npm 元数据,用自己的话写成,供 CQBase 上下文库使用。若包名、运行时或条款有变,以官网为准。

订阅 CQBase 周刊

每周一封,介绍本周新收录的公开 AI 技能、提示词、MCP 和用法。可随时退订。我们不会把邮箱交给第三方作其营销之用。