Cloudflare Agents SDK v0.34.0:Pi 1.6 破坏性变更与等待工具
Agents - Agents SDK now supports Pi 1.6 with tools that wait without keeping your agent awake
致 Cloudflare Agent 开发者:v0.34.0 引入 Pi 1.6 破坏性变更且禁止回滚。请检查代码中是否使用了旧的 RunEndTask 或错误的 API 调用顺序,务必在生效前完成迁移。
Agents SDK v0.34.0 upgrades PiHarness to Pi 1.6 ↗︎. A Pi tool can now wait for a person, a deadline, or another session without keeping the Durable Object awake, and a session can start from a history that your application already has.
Agents SDK v0.34.0 将 PiHarness 升级至 Pi 1.6 ↗︎。Pi 工具现在可以等待人员、截止时间或另一个会话,而无需保持 Durable Object 处于唤醒状态,并且会话可以从应用程序已有的历史记录中启动。
Tools that wait
等待中的工具
- Park until a signal or a deadline. A tool can return a park instead of a result, and Pi runs it again when a signal arrives or the deadline passes. While it waits, the call holds no invocation, so the Durable Object can hibernate. Deliver signals with the new harness.signal(). Refer to Tools that wait.
- Wait for a subagent. submit() and continue() take notify, so a parked tool wakes when another session's input settles. Refer to Wait for a subagent.
- Approval gates. A beforeTool hook can park a tool call before it runs, for example until a person approves it.
- 暂停直到收到信号或到达截止时间。工具可以返回 park 而非结果,当信号到达或截止时间过后,Pi 会再次运行它。在等待期间,调用不占用任何实例,因此 Durable Object 可以休眠。使用新的 harness.signal() 发送信号。参见“等待中的工具”。
- 等待子代理。submit() 和 continue() 接受 notify 参数,因此当另一个会话的输入确定时,停泊的工具会被唤醒。参见“等待子代理”。
- 审批关卡。beforeTool 钩子可以在工具调用运行之前将其停泊,例如直到有人批准为止。
Session updates
会话更新
- Start a session from an existing history. harness.root(), sessions.create(), and sessions.fork() take Pi's init, which writes messages into the transcript in the commit that creates the session. The root session is now created on its first use, so harness.root() can seed it. Refer to Seed a session with an existing history.
- Keep queued input across an abort. With submit(input, { onAbort: "keep" }), stopping an answer does not drop the message that the user or another agent sent next.
- Steadier runs. Pi retries more dropped provider connections. When Anthropic can no longer continue a message thread, agents/models/pi-ai sends the whole conversation again instead of failing the turn. PiHarness.dispose() frees Pi AI's per-session state.
- 从现有历史启动会话。harness.root()、sessions.create() 和 sessions.fork() 接受 Pi 的 init 参数,该参数会在创建会话的提交中将消息写入对话记录。根会话现在在其首次使用时创建,因此 harness.root() 可以为其提供种子数据。参见“使用现有历史为会话提供种子数据”。
- 在中止期间保留排队输入。使用 submit(input, { onAbort: "keep" }),停止回答不会丢弃用户或其他代理随后发送的消息。
- 更稳定的运行。Pi 会重试更多掉线的提供商连接。当 Anthropic 无法继续消息线程时,agents/models/pi-ai 会重新发送整个对话,而不是导致回合失败。PiHarness.dispose() 释放 Pi AI 的每会话状态。
Wait for a person's answer
等待人员的回答
This tool asks the user a question, then parks until your agent delivers the answer:
此工具向用户提问,然后停泊直到你的代理接收并传递答案:
import { defineSignal } from "@earendil-works/pi-durable";
import { obj, str } from "@earendil-works/pi-schema";
const Answer = defineSignal({
name: "app.answer",
version: 1,
schema: obj({ text: str() }),
});
const AskParameters = obj({ question: str() });
const askUser = {
name: "ask_user",
description: "Ask the user a question and wait for the answer.",
parameters: AskParameters,
async execute({ question }, api, context) {
const answer = await api.readSignal(Answer, "answer", context);
if (answer !== undefined && "value" in answer) {
return { output: [{ type: "text", text: answer.value.text }] };
}
await showQuestion(api.taskId, question);
return { sleep: { signals: [Answer.key("answer")] } };
},
};
// Later, in your agent, when the user answers:
await this.harness.signal(taskId, Answer, "answer", { text: "Yes" });import {
defineSignal,
type ToolRegistration,
} from "@earendil-works/pi-durable";
import { obj, str } from "@earendil-works/pi-schema";
const Answer = defineSignal({
name: "app.answer",
version: 1,
schema: obj({ text: str() }),
});
const AskParameters = obj({ question: str() });
const askUser: ToolRegistration<typeof AskParameters> = {
name: "ask_user",
description: "Ask the user a question and wait for the answer.",
parameters: AskParameters,
async execute({ question }, api, context) {
const answer = await api.readSignal(Answer, "answer", context);
if (answer !== undefined && "value" in answer) {
return { output: [{ type: "text", text: answer.value.text }] };
}
await showQuestion(api.taskId, question);
return { sleep: { signals: [Answer.key("answer")] } };
},
};
// Later, in your agent, when the user answers:
await this.harness.signal(taskId, Answer, "answer", { text: "Yes" });While the question is open, the session's run is still going, and the object can hibernate or be evicted. harness.signal() wakes the object, and Pi runs the tool again with the answer.
在问题开放期间,会话的运行仍在继续,对象可以休眠或被驱逐。harness.signal() 唤醒对象,Pi 会使用答案再次运行该工具。
Other changes
其他更改
- MCP re-authorization. A request that needs the user to sign in again throws MCPAuthorizationRequiredError with a link. A failed server stays failed until you call the new reconnectMcpServer(id). Refer to Failures and reconnecting.
- Failed requests no longer send error details. A failed request gets a generic 500 response, and a failed WebSocket upgrade closes with code 1011. Use onFetchError() to choose the response. Refer to Failed requests.
- Chat fixes. Stop, clear, regenerate, and resume now work across tabs and during recovery.
- Scheduling fixes. A schedule, queue item, or Task run that is cancelled or replaced no longer runs again.
- Models. ai.image() and Pi AI's ai.images() run the FLUX.2 image models. claudeCode() defaults to claude-sonnet-5-5. Examples move off the Workers AI models retired on November 20, 2026.
- MCP 重新授权。需要用户重新登录的请求会抛出 MCPAuthorizationRequiredError 并提供链接。失败的服务器将保持失败状态,直到你调用新的 reconnectMcpServer(id)。参见“故障与重连”。
- 失败的请求不再发送错误详情。失败的请求会获得通用的 500 响应,失败的 WebSocket 升级将以代码 1011 关闭。使用 onFetchError() 来选择响应。参见“失败的请求”。
- 聊天修复。停止、清除、重新生成和恢复现在可以在标签页之间以及恢复期间正常工作。
- 调度修复。被取消或替换的计划、队列项或任务运行不再重复执行。
- 模型。ai.image() 和 Pi AI 的 ai.images() 运行 FLUX.2 图像模型。claudeCode() 默认使用 claude-sonnet-5-5。示例将不再使用于 2026 年 11 月 20 日退役的 Workers AI 模型。
Upgrade
升级
Once a conversation runs on Pi 1.6, Pi 1.5 cannot run its tool calls or model requests. After upgrading, roll forward to fix deployment issues rather than rolling back to Pi 1.5.
一旦对话在 Pi 1.6 上运行,Pi 1.5 将无法执行其工具调用或模型请求。升级后,请向前滚动以修复部署问题,而不是回滚到 Pi 1.5。
Deliver signals with harness.signal() instead of (await harness.pi()).signal(), and call harness.root() before you reach the root session through harness.pi(). If you use Pi Durable directly, RunEndTask is now HookTask, and code mode namespaces come from Extension.namespace. Refer to the Pi Durable 1.6.0 changelog ↗︎ for the full list of breaking changes.
请使用 harness.signal() 发送信号,而不是 (await harness.pi()).signal(),并在通过 harness.pi() 到达根会话之前调用 harness.root()。如果你直接使用 Pi Durable,RunEndTask 现在变为 HookTask,代码模式命名空间来自 Extension.namespace。有关所有破坏性更改的完整列表,请参阅 Pi Durable 1.6.0 更新日志 ↗︎。
If you use the MCP client, catch MCPAuthorizationRequiredError and send the user to error.authUrl, and give users a way to call reconnectMcpServer(id) for a failed server. If you relied on error details in failed responses, implement onFetchError().
如果你使用 MCP 客户端,请捕获 MCPAuthorizationRequiredError 并将用户重定向至 error.authUrl,并为失败的服务提供让用户调用 reconnectMcpServer(id) 的方式。如果你依赖失败响应中的错误详情,请实现 onFetchError()。
The Agents SDK v0.34.0 changelog ↗︎ has step-by-step upgrade instructions. Point your coding agent at them and upgrade today:
Agents SDK v0.34.0 更新日志 ↗︎ 包含逐步升级说明。将你的编码代理指向这些说明并立即升级:
Copy promptPrompt copied!
复制 promptPrompt 已复制!
更进一步:量化金融体系
看懂新闻只是起点——沿量化金融路径,把它变成能交付的工程能力