mastra.schedules

引入版本： @mastra/core@1.50.0

mastra.schedules 是用于持久化 Cron 调度的 CRUD 服务。你可以用它为 Agent 或 Workflow 创建、列出、更新、暂停、恢复、手动运行和删除调度。

有关用法模式和概念，请参阅调度。

用法示例

创建 Agent 调度：

src/mastra/schedules.ts

const schedule = await mastra.schedules.create({
  agentId: 'pinger',
  cron: '0 * * * *',
  prompt: 'Give me a status update.',
})

创建 Workflow 调度：

src/mastra/schedules.ts

const schedule = await mastra.schedules.create({
  workflowId: 'daily-report',
  cron: '0 9 * * *',
  inputData: { reportType: 'summary' },
})

调度需要一个实现 schedules domain 的 Storage adapter。支持的 adapter 包括 @mastra/libsql、@mastra/pg、@mastra/mysql、@mastra/mongodb、@mastra/convex 和 @mastra/spanner。

方法

创建调度

create(input)

创建 Agent 或 Workflow 调度。传入 agentId 可创建 Agent 调度，传入 workflowId 可创建 Workflow 调度。

const schedule = await mastra.schedules.create({
  agentId: 'pinger',
  cron: '0 * * * *',
  prompt: 'Give me a status update.',
})

Agent 调度输入

id?:

string

可选的稳定调度 ID。该值会规范化为 agent_<slug>。如果省略，Mastra 会生成一个 agent_<uuid> ID。

agentId:

string

每次触发调度时要运行的 Agent ID。

cron:

string

调度的 Cron 表达式。接受由 5、6 或 7 个部分组成的 Cron 表达式以及 Croner 昵称。

prompt:

string

每次触发调度时发送给 Agent 的提示词。

name?:

string

自由格式标签，用于区分同一 Agent 或 thread 上的多个调度。

timezone?:

string

用于确定 Cron 触发时间的 IANA 时区，例如 America/New_York。

threadId?:

string

接收调度信号的 thread。如果省略，每次触发都会通过 agent.generate() 在不使用 thread 的情况下运行。

resourceId?:

string

使用 thread 的调度所对应的资源 ID。设置 threadId 时必填。

signalType?:

AgentSignalType

使用 thread 的调度触发时所用的信号类型。默认为 notification。

tagName?:

string

用于渲染调度信号的 XML 标签名称。默认为 schedule。

attributes?:

AgentSignalAttributes

渲染到调度信号 XML 标签上的属性。

providerOptions?:

Record<string, unknown>

每次触发时合并到调度信号 payload 中、可安全用于 JSON 的 Provider 选项。

ifActive?:

ScheduleIfActive

目标 thread 正在主动进行流式传输时的行为。需要 threadId。

ifIdle?:

ScheduleIfIdle

目标 thread 空闲时的行为。需要 threadId。

metadata?:

Record<string, unknown>

与调度记录行一同存储的任意 metadata。

status?:

'active' | 'paused'

= 'active'

初始生命周期状态。默认为 active。

Workflow 调度输入

id?:

string

可选的稳定调度 ID。该值会规范化为 schedule_<slug>。如果省略，Mastra 会生成一个 schedule_<uuid> ID。

workflowId:

string

每次触发调度时要启动的 Workflow ID。

cron:

string

调度的 Cron 表达式。接受由 5、6 或 7 个部分组成的 Cron 表达式以及 Croner 昵称。

timezone?:

string

用于确定 Cron 触发时间的 IANA 时区。

inputData?:

unknown

传递给 Workflow 运行的输入数据。

initialState?:

unknown

调度运行时 Workflow 的初始状态。

requestContext?:

Record<string, unknown>

传递给 Workflow 运行的请求上下文。

metadata?:

Record<string, unknown>

与调度记录行一同存储的任意 metadata。

status?:

'active' | 'paused'

= 'active'

初始生命周期状态。默认为 active。

读取调度

get(id)

按 ID 获取调度。未带前缀的 Agent 调度 ID 也会解析为规范化的 agent_<slug> 形式。

const schedule = await mastra.schedules.get('pinger')

list(filter?)

列出调度。不指定 filter 时，会返回 Agent 和 Workflow 调度。

const schedules = await mastra.schedules.list({
  agentId: 'pinger',
  status: 'active',
})

filter?:

ListSchedulesFilter

列表操作的可选 filter。

ListSchedulesFilter

agentId?:

string

仅返回此 Agent 的 Agent 调度。

workflowId?:

string

仅返回此 Workflow 的 Workflow 调度。

threadId?:

string

仅返回此 thread 的 Agent 调度。

resourceId?:

string

仅返回此资源的 Agent 调度。

name?:

string

仅返回具有此标签的 Agent 调度。

status?:

'active' | 'paused'

仅返回具有此状态的调度。

更新调度

update(id, patch)

更新调度。更改 cron 或 timezone 会重新计算下次触发时间。将 status 从 paused 更新为 active 时，也会重新计算下次触发时间。

const updated = await mastra.schedules.update('pinger', {
  cron: '*/30 * * * *',
  prompt: 'Give me a status update every 30 minutes.',
})

Agent 调度的 patch 可以更新 cron、timezone、prompt、name、signalType、tagName、attributes、providerOptions、ifActive、ifIdle、metadata 和 status。threadId 和 resourceId 无法通过 patch 更新。当 thread 目标需要更改时，请创建新的调度。

Workflow 调度的 patch 可以更新 cron、timezone、inputData、initialState、requestContext、metadata 和 status。对 Workflow 调度传入 prompt、signalType 和 ifIdle 等仅限 Agent 的 patch 字段时，会抛出错误。

生命周期

pause(id)

暂停调度。暂停操作是持久且幂等的。

const paused = await mastra.schedules.pause('pinger')

resume(id)

恢复已暂停的调度，并根据当前时间重新计算下次触发时间。

const active = await mastra.schedules.resume('pinger')

run(id)

立即触发一次调度，但不更改其 Cron 周期。

const run = await mastra.schedules.run('pinger')

对于 Agent 调度，claimId 使用 manual_<scheduleId>_<timestamp>。对于 Workflow 调度，claimId 使用 sched_<scheduleId>_<timestamp>，并会复用为 Workflow 运行 ID。

delete(id)

删除调度。删除不存在的调度时不会执行任何操作。

await mastra.schedules.delete('pinger')

调度行为

• Agent 调度 ID 使用 agent_ 前缀。通过 mastra.schedules.create() 创建的 Workflow 调度 ID 使用 schedule_ 前缀。
• 设置 threadId 时，使用 thread 的 Agent 调度需要 resourceId。
• signalType、ifActive、ifIdle 和 resourceId 需要 threadId。
• Workflow 调度不接受 prompt、signalType 或 ifIdle 等仅限 Agent 的 patch 字段。
• run() 会立即发布一次手动触发，且不会更改存储的 Cron 周期。