SDK 模型与运行选项

用 Cursor.models.list() 查询当前 API key 的模型目录，再选择 ID 与参数。目录受团队策略影响，文档中的示例模型不保证对所有账号开放。TypeScript 本地首次 send 前必须指定模型，云端可使用服务端默认。

Router 选择

Cursor Router 对 Teams 和 Enterprise 提供，Enterprise 管理员须先启用。SDK 使用 auto-smart，且必须明确传 optimize_for。

const model = {
  id: "auto-smart",
  params: [{ id: "optimize_for", value: "balanced" }],
};

先检查目录存在 auto-smart，再检查 parameters 中允许的值。不能省略 optimize_for 或传旧 default 值。auto 是服务端选择 Auto 的回退，不等于指定 Router 模式。团队模型 allowlist 会影响路由池，所选底层模型可能随请求变化，按实际模型价格计费。

SDK 文档说明 Composer 2 已退役，composer-2/composer-2-fast 会在认证阶段转到 Composer 2.5；需要 fast 语义时按目录明确选择并验证，不能依赖旧名字保证行为。

每轮覆盖

send 的 model 覆盖具有持续性：成功后更新 agent.model，后续不传 model 会沿用；run.model 保留该轮实际选择。mode 可选 agent/plan，创建时设置首轮模式，后续省略时沿用会话模式。官方将显式每轮 mode 描述为该轮覆盖，不应自行推断与 model 完全相同的持久策略。

每轮 mcpServers 完全替代创建时 inline 定义，不做合并。TypeScript local.force 默认 false，可过期一个卡住的本地轮再启动；Python 对应 local.force 默认未设置。不要在正常运行时把 force 当作常规并发机制。

云端环境变量

创建时 cloud.envVars（Python env_vars）与 Agent 同生命周期，加密保存、注入 shell 并随 Agent 删除；不能与自供 agentId 同时使用，名称不能以 CURSOR_ 开头。

send 时的 cloud.envVars 仅本轮存在，结束后移除。同名值覆盖创建时变量，下一轮恢复 Agent 级值。公共仓库任务不支持每轮变量。本地运行继承进程环境，应在 send 前设置。

自定义 metadata

cloud.metadata 是持久字符串标签，可用于用户、工单或工作流关联，get/list 返回。它不同于 VM 内的metadata API。

Python 官方文档给出最多 50 项，key 非空且不超过 255 字符，value 不超过 4096 bytes，可为空字符串。空 mapping 视为没有 metadata；未开放该功能的账号提供非空 mapping 会返回 403 feature_unavailable。

系统提示替换

TypeScript systemPrompt 仅支持本地且按账号开放，必须非空。它替换主 Agent 的内建系统提示，原有编码身份、工具调用协议与表达指南需要自行补足；工具 schema、rules、Skills 仍加载，subagents 保留自身提示。该值不随恢复持久化，resume 时需要再传。