Cursor SDK 给 agent 装上「方向盘」：后台 subagent 不再丢结果，运行中可 steer 转向

10 月第一周，Cursor SDK 补上了两个关键拼图

2026 年 10 月第一周，Cursor SDK 随 1.0.31 / 1.0.32 版本发布了一组更新。官方 changelog（cursor.com/docs/sdk/changelog，我亲自打开核实）里有两条值得单独拎出来说：后台 subagent 的结果不再丢失，以及 run.steer() 可以在 agent 运行时"转向"。这两条加在一起，讲的是同一件事——agent 从"发出去就只能等结果"的黑盒，变成"中途可以干预、结果不会丢"的可协作系统。

先做口径说明：Cursor 官方 changelog 页面是累积列表，没有给每条更新打日期戳。1.0.31/1.0.32 发布于 10 月第一周的日期锚点，来自二级 changelog 跟踪页与 Cursor 官方 X 公告；正文中的功能描述全部来自官方 changelog 原文逐字核实，关键语句我会在下文给出英文原文。

拼图一：后台 subagent 的结果，终于回得来了

先讲痛点。用 Cursor SDK 编排多 agent 时，一个常见模式是：主 agent 通过 Task 工具启动一个后台 subagent 去干脏活累活（比如并行调研三个方案），自己继续往下走。问题出在"回来"这一步——在 1.0.31 之前，后台 subagent 的结果会在父 turn 结束时被丢弃。你派出去的侦察兵，回来发现营地已经散了，情报没人收。

1.0.31 的修复很直接，官方原话是："its result now returns to the parent as a follow-up turn on the same run instead of being dropped when the parent turn ends"（结果现在会作为同一 run 的 follow-up turn 回到父 agent，而不是在父 turn 结束时被丢弃）。配套的语义是：run.stream() 会持续输出穿过这些 turn，run.wait() 则在它们之后才 resolve。支持本地 agent 的 TypeScript 与 Python 双端。

图 1：新行为时序。主 agent 用 Task 启动后台 subagent；开发者中途调用 run.steer() 立即作为 next turn 执行；后台 subagent 完成后，结果以 follow-up turn 回流到同一 run，run.stream() 全程不断流。

这个改动的分量，要放在"fan-out/fan-in"编排模式里看。派三个 subagent 并行干活、等它们都回来再汇总——这是 agent 应用里最常见的并发模式。结果会丢，意味着这个模式在 SDK 层是残缺的，开发者只能自己在外面搭状态机接盘。现在 SDK 把"接盘"这件事收编了：run 有了"turn"的连续性语义，后台任务的完成不再是一个需要外部轮询的事件，而是 run 内部的一个 turn。对用 SDK 做客服 agent、运维 agent、代码评审流水线的人来说，这是从"能用"到"好用"的一步。

拼图二：给运行中的 agent 装上"方向盘"

第二条更新更耐人寻味。run.steer(text) 的语义变化，官方 changelog 写得非常具体："run.steer(text) used to resolve revert_to_followup when the agent had ended its turn to wait on background subagents, so your message waited until that work finished. Now the steer runs right away as the next turn, and background results still arrive afterward."（过去，当 agent 结束 turn 等待后台 subagent 时，steer 会 resolve 为 revert_to_followup，你的消息要等到后台做完才执行；现在 steer 立即作为下一个 turn 执行，后台结果随后照常到达。）限制条件：仅本地 TypeScript run。

图 2：新旧行为对照。旧行为下，等待后台 subagent 时的 steer 会被推迟到后台完成；新行为下 steer 立即作为 next turn 执行，后台结果随后以 follow-up turn 到达——"转向"不再被"等待"阻塞。

这个设计的哲学值得展开。steer 没有被设计成"打断"——它没有 kill 掉正在跑的后台 subagent，没有丢弃已产生的工作，而是"插队"成下一个 turn。这是一种很克制的干预语义：人类获得的是"改变方向"的权力，而不是"掀桌子"的权力。对比一下其他可能的设计：粗暴打断（后台工作全丢）、排队等待（旧行为，人只能干等）、静默注入（把指令塞进当前 turn，可能打乱模型思路）。Cursor 选了第四种：作为独立的 next turn 立即执行，前后 turn 的边界清晰，模型能明确区分"这是人类的新指令"和"这是后台的结果"。

为什么这件事重要？因为它对应着 agent 落地的一个真实场景：长任务中的人工接管。想象一个跑了 20 分钟的代码迁移 agent，你在中途发现它选错了方案——旧行为下，你要么等它跑完（浪费 20 分钟），要么杀掉重来（前功尽弃）；新行为下，一句 steer 让它"改用方案 B"，后台的调研结果随后还会回来，不浪费。这种"人在回路"的粒度，从"任务级"细化到了"turn 级"，是 agent 从 demo 走向生产的关键一步。

限制条件也要说清楚：steer 仅支持本地 TypeScript run，云端 run 和 detached 句柄不在此列。Python 本地 run 有后台结果回流，但没有 steer。这说明该功能还处在"先让一部分 run 先转起来"的阶段，跨 runtime 的一致性是下一步的事。

连带更新：SDK 正在"长大成人"

同一批 changelog 里还有几条，单独看不起眼，合在一起能看出 Cursor SDK 的成熟度曲线：

• Custom tool 支持 MCP annotations：annotations 可以把 MCP 工具注解（title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint）透传给模型。官方特意强调："They are descriptive hints only; the SDK does not enforce them."（这只是描述性提示，SDK 不做强制。）——诚实的设计：注解是给模型的"建议"，不是安全边界；真正的安全还得靠沙箱和审批。这句话值得所有做 agent 工具链的人抄下来：不要把"提示"当成"保证"。
• 长时本地 agent 自动刷新凭证：短期 access token 过期前自动刷新，跑超 1 小时的 agent 不再报鉴权失败。这是典型的"demo 时没人遇到、生产天天遇到"的问题，能进 changelog 说明用 SDK 跑长任务的人已经够多了。
• outputSchema 声明结构化输出：TypeScript 的 outputSchema / Python 的 output_schema 可以声明工具返回的 JSON Schema，并作为 MCP output schema 广告给模型——但结果不会被校验。又是"描述而非强制"的思路，和 annotations 一脉相承。
• 本地 agent 也能查用量了：agent.getUsage() / get_usage() 支持本地 agent，按 turn 拆分 token 用量。成本可观测性下沉到本地，意味着"在本地调优、到云端放量"的工作流被正式支持。
• TS 与 Python 同版本号发布：自 1.0.24 起，npm 的 @cursor/sdk 与 PyPI 的 cursor-sdk 同一次发布、共享版本号，Python 不再落后。这个细节对双栈团队是实打实的利好。

观点：agent 编排正在从"编排任务"转向"编排协作"

把这两版更新放在一起看，Cursor SDK 在回答一个问题：当 agent 开始并行干活、任务开始变长，人应该站在哪里？

旧答案是"站在外面"：人负责启动任务、收结果，中间是黑盒。黑盒的好处是简单，代价是中间态不可干预、结果可能丢失——1.0.31 之前后台结果被丢弃，就是"站在外面"的代价。新答案是"站在回路里"：run 有了 turn 的连续性，后台结果自动回流；人可以在任意时刻 steer，干预粒度细化到 turn。这不是功能点的堆砌，而是人机协作模型的升级——从"发号施令"到"途中协作"。

这个趋势不只属于 Cursor。回看近两个月：LiteLLM 开源 Moyai 讲成本、Anthropic 给 Claude Code 加 agents.md 讲规范、Google 给 MCP Toolbox 补 Java SDK 讲生态——agent 基础设施的竞争，已经从"模型能力"下沉到"工程体验"。Cursor 这次补的恰恰是工程体验里最痛的两块：结果不丢、随时可干预。对 vibe coder 来说，这意味着用 SDK 搭建"7×24 小时干活"的 agent 应用（定时代码评审、依赖巡检、客服值守）的门槛又低了一截：你不再需要自己写状态机去接后台任务，也不再需要为了一次纠偏而杀掉整个 run。

当然，路还很长。steer 目前只支持本地 TS run，多 subagent 的冲突解决（两个后台任务同时回来谁先谁后？）、steer 与后台结果的竞态（steer 的 next turn 和 follow-up turn 谁先执行？）——这些语义在 changelog 里没有展开，实际用起来可能还有坑。但方向是对的：好的 agent SDK，应该让"人在回路"成为默认项，而不是补丁项。Cursor 这两版更新，就是在往这个方向挪。

动手：新语义长什么样

纸上得来终觉浅，把新语义翻译成伪代码，感受一下变化：

// 1.0.31 之前：后台 subagent 结果可能"回来没人收"
const run = agent.send("并行调研 A/B/C 三个方案，汇总成对比表");
// 主 turn 结束，后台 Task 的结果无处可去（被丢弃）

// 1.0.31 之后：结果自动以 follow-up turn 回流
const run = agent.send("并行调研 A/B/C 三个方案，汇总成对比表");
for await (const delta of run.stream()) {
  render(delta); // 后台结果回来时，stream 不会断，继续输出
}
await run.wait(); // 所有 follow-up turn 完成后才 resolve

// 1.0.32：中途发现方向错了，直接 steer
setTimeout(() => {
  run.steer("C 方案不用调研了，重点对比 A 和 B 的成本");
}, 10 * 60 * 1000); // 10 分钟后介入：立即作为 next turn 执行，不用等后台

三段代码讲清了三件事：派出去（Task）、收回来（follow-up turn）、中途改主意（steer）——一个完整的长任务编排闭环，终于不需要开发者在外面手写状态机了。

横向对比一下：OpenAI 的 Agents SDK 强调"交接"（handoff）语义，LangGraph 强调"图+状态"，而 Cursor SDK 这次走的路是"run 即会话"——把一次 run 理解成一段有记忆、可干预的连续会话，而不是一次性的请求-响应。这个选择和它的产品形态是一致的：Cursor 的核心场景是 IDE 里的结对编程，人本来就坐在旁边，随时准备插话。SDK 只不过把 IDE 里的交互直觉，搬到了 API 层。

最后给准备用 Cursor SDK 做东西的读者三条建议：第一，后台 Task 适合"可独立验证"的子任务（调研、搜索、生成草稿），不适合强依赖主上下文的任务——follow-up turn 回来时，主 agent 的上下文可能已经变了，汇总逻辑要写得鲁棒些。第二，steer 是"方向盘"不是"刹车"，别指望它打断一个已经跑飞的后台任务；真正的熔断还得靠任务设计（超时、预算上限）。第三，MCP annotations 该写就写（readOnlyHint、destructiveHint 这些对模型的行为有真实影响），但永远不要把它当安全边界——官方自己都说了，descriptive hints only。