编程式提交

持久接受 Think 轮次并在推理运行前返回。对 webhook 处理程序、RPC 调用方以及需要快速确认、安全重试与后续状态检查的父 Worker，使用 submitMessages()。

声明式定时提示词任务在底层使用相同的持久提交路径。触发为循环且由代码声明时使用 getScheduledTasks()；外部调用方或 webhook 创建一次性工作时应直接使用 submitMessages()。若要内联等待响应，请改用 saveMessages()。

submitMessages

async submitMessages(
	messages: UIMessage[],
	options?: {
		submissionId?: string;
		idempotencyKey?: string;
		metadata?: Record<string, unknown>;
	},
): Promise<SubmitMessagesResult>

submitMessages() 接受可序列化的 UIMessage[]。它不支持 saveMessages((messages) => ...) 的函数形式，因为持久提交会在执行前持久化工作，无法存储闭包。数组必须至少包含一条消息。

const submission = await this.submitMessages(
	[
		{
			id: crypto.randomUUID(),
			role: "user",
			parts: [{ type: "text", text: "Process webhook event 123" }],
		},
	],
	{ idempotencyKey: "webhook-event-123" },
);

return Response.json({
	submissionId: submission.submissionId,
	status: submission.status,
	accepted: submission.accepted,
});

const submission = await this.submitMessages(
	[
		{
			id: crypto.randomUUID(),
			role: "user",
			parts: [{ type: "text", text: "Process webhook event 123" }],
		},
	],
	{ idempotencyKey: "webhook-event-123" },
);

return Response.json({
	submissionId: submission.submissionId,
	status: submission.status,
	accepted: submission.accepted,
});

提交状态

状态	含义
`pending`	已接受并等待轮次
`running`	已被 Agent 认领并执行
`completed`	Think 轮次成功完成
`aborted`	提交已取消
`skipped`	提交运行前轮次状态已重置
`error`	执行失败或恢复不安全

幂等重试

从外部系统传入 idempotencyKey。使用相同 key 重试会返回现有提交且 accepted: false，而不是插入重复消息：

const first = await this.submitMessages(messages, {
	idempotencyKey: payload.id,
});

const retry = await this.submitMessages(messages, {
	idempotencyKey: payload.id,
});

console.log(first.submissionId === retry.submissionId); // true
console.log(retry.accepted); // false

const first = await this.submitMessages(messages, {
	idempotencyKey: payload.id,
});

const retry = await this.submitMessages(messages, {
	idempotencyKey: payload.id,
});

console.log(first.submissionId === retry.submissionId); // true
console.log(retry.accepted); // false

若同时传入 submissionId 与 idempotencyKey，它们必须标识同一提交。若指向不同现有提交，submitMessages() 会抛出错误。

检查、列出、取消与删除

使用提交 API 检查活跃工作、取消持久提交并清理终态记录：

const current = await this.inspectSubmission(submission.submissionId);

const active = await this.listSubmissions({
	status: ["pending", "running"],
});

await this.cancelSubmission(submission.submissionId, "No longer needed");

await this.deleteSubmissions({
	status: ["completed", "error", "aborted"],
	completedBefore: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
});

const current = await this.inspectSubmission(submission.submissionId);

const active = await this.listSubmissions({
	status: ["pending", "running"],
});

await this.cancelSubmission(submission.submissionId, "No longer needed");

await this.deleteSubmissions({
	status: ["completed", "error", "aborted"],
	completedBefore: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
});

跨 Worker 与 Durable Object RPC 边界进行持久取消时使用 cancelSubmission(submissionId)。仅当调用方在运行轮次的 Durable Object 内创建 signal 时，才对 saveMessages() 或 continueLastTurn() 使用 AbortSignal。

Session 行为

Think 先将已接受的提交存入提交账本。仅在提交开始执行时才将提交的消息追加到对话会话。后续已接受的提交在其轮次开始前对模型不可见，从而保持先进先出轮次语义。

若在消息应用前取消提交（包括已被认领但仍等待轮次的提交），这些消息不会持久化到对话。

若在 pending 提交运行前清空聊天或重置轮次状态，提交会被标记为 skipped。

与 Workflows 对比

对多步骤编排、每步重试、长等待、外部事件、人工审批，或可能将 Think 作为更大流程一部分的 pipeline，使用 Workflows。请参阅 Think Workflows。