Schedules

新增于： @mastra/core@1.50.0

schedule 按 cron 节奏运行 agent。每次触发时，Mastra 会将提示词作为 signal发送到 thread，或作为无 thread 的 agent.generate() 运行。schedule 适用于重复性工作，例如每日摘要和定期检查，包括向对话中发送定时提醒。

Schedules 会被持久化，因此能在重启和重新部署后保留。在运行时通过 mastra.schedules管理它们，这是创建、读取、更新和删除（CRUD）的规范接口。同一接口也管理 workflow schedules（传入 workflowId 而不是 agentId 来调度 workflow）。

备注

Schedules 需要实现了 schedules 域的存储适配器。支持的适配器和 API 行为请参阅 mastra.schedules 参考。

快速开始

以下 schedule 每小时运行一次 pinger agent。它没有 thread，因此每次触发都是一次独立的 agent.generate() 运行。

src/mastra/schedules.ts

import { Mastra } from '@mastra/core'
import { Agent } from '@mastra/core/agent'
import { LibSQLStore } from '@mastra/libsql'

const pinger = new Agent({
  id: 'pinger',
  name: 'Pinger',
  instructions: 'Report the current system status in one sentence.',
  model: 'openai/gpt-5.6-sol',
})

const mastra = new Mastra({
  agents: { pinger },
  storage: new LibSQLStore({ id: 'mastra-storage', url: 'file:./mastra.db' }),
})

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

Mastra 在首次创建 schedule 时启动调度器，然后按你指定的 cron 触发 agent。

节奏

Schedules 按 cron 表达式触发。cron 字段接受标准的 5、6 或 7 段 cron 表达式，并在创建或更新 schedule 时进行验证。

croner 的别名也可用，例如 @hourly、@daily、@weekly、@monthly 和 @midnight。对于日期与时间的组合，请直接编写 cron 字段：

// Every weekday at 9am
await mastra.schedules.create({
  agentId: 'pinger',
  cron: '0 9 * * 1-5',
  prompt: 'Start-of-day check.',
})

将 timezone 设置为 IANA 时区，例如 America/New_York，这样触发时间就不依赖主机的 locale。省略时，cron 按主机的本地时区解析。

若希望更易读地构造 cron，可以使用 cron-time-generator 等用户态构建器，并将其输出传给 cron。

无 thread 与有 thread 的 schedule

agent schedule 以两种模式之一触发，取决于你是否传入 threadId。

无 thread

不传 threadId 时，每次触发都是一次独立的 agent.generate() 运行，不会写入对话 thread。这是最简单的模式，适用于状态检查、报告等不需要对话上下文的工作。

有 thread

传入 threadId 时，schedule 会向该 thread 发送一个 signal。提示词会加入 agent 的对话。有 thread 的 schedule 需要同时提供 resourceId 和 threadId。

src/mastra/schedules.ts

await mastra.schedules.create({
  agentId: 'pinger',
  cron: '0 9 * * *',
  prompt: 'Summarize anything new since yesterday.',
  threadId: 'thread-123',
  resourceId: 'user-456',
})

有 thread 的 schedules 接受额外的字段来控制 signal 行为，包括 signal 类型、XML 标签、标签属性和活跃/空闲时的投递行为。它们与 agent.sendSignal()接受的选项一致，且保持 JSON 可序列化，以便随 schedule 一起持久化。

这些字段需要 threadId。完整的有 thread 输入结构请参阅 agent schedule 输入参考。

await mastra.schedules.create({
  agentId: 'pinger',
  cron: '0 9 * * *',
  prompt: 'Summarize anything new since yesterday.',
  threadId: 'thread-123',
  resourceId: 'user-456',
  tagName: 'check-in', // renders as <check-in>…</check-in>
  attributes: { source: 'cron' },
  ifActive: { behavior: 'discard' }, // skip if the thread is mid-stream
  ifIdle: {
    behavior: 'wake', // wake the agent if the thread is idle
    streamOptions: { requestContext: { locale: 'en-US' } },
  },
})

providerOptions 会在每次触发时合并到 signal payload 中，并同时适用于有 thread 和无 thread 的 schedules。

管理 schedules

使用 mastra.schedules 执行所有 schedule 操作。该服务可以创建、读取、更新、暂停、恢复、手动运行和删除 schedules。

const schedule = await mastra.schedules.create({
  agentId: 'pinger',
  cron: '0 * * * *',
  prompt: 'Status check.',
})

await mastra.schedules.pause(schedule.id)
await mastra.schedules.resume(schedule.id)
await mastra.schedules.run(schedule.id) // Fire once now, off-schedule

pause 和 resume 是持久化的。run 会立即触发一次 schedule，而不影响其节奏。完整的方法列表、过滤器和 patch 字段请参阅 mastra.schedules 参考。

Workflow schedules

同一服务也可以创建运行 workflow 而不是 agent 的 schedules。传入 workflowId 和 workflow 形态的字段：

await mastra.schedules.create({
  workflowId: 'daily-report',
  cron: '0 9 * * *',
  inputData: { userId: 'system' },
})

以这种方式创建的 workflow schedules 独立于 createWorkflow 上的声明式 schedule 字段；声明式形式及 Studio 视图请参阅定时 workflow。

自定义 ID

当你需要一个可预测的标识以便之后查找、更新或删除时，请传入 id。

await mastra.schedules.create({
  id: 'nightly-summary',
  agentId: 'pinger',
  cron: '0 9 * * *',
  prompt: 'Summarize anything new since yesterday.',
})

ID 规范化规则和重复 ID 行为请参阅 create(input) 参考。

从客户端调用

同样的操作可通过 @mastra/client-js 经由 /api/schedules 路由使用，因此你可以从单独的进程或 UI 管理 schedules。客户端方法列表请参阅 client-js agent schedules 参考。

生命周期钩子

钩子让你在 agent schedule 生命周期的关键节点运行代码，例如计算触发时参数或对结果作出反应。请在 Mastra 构造函数的 schedules 下配置它们。这些钩子是一个单一的扁平包，会为每个 agent 的 schedules 运行；每个钩子上下文都携带触发的 agentId，因此在你需要针对不同 agent 定制行为时可以据此分支。钩子位于 Mastra 层级，因此同时适用于代码定义的和已存储的 agents。

src/mastra/index.ts

const mastra = new Mastra({
  agents: { pinger },
  storage: new LibSQLStore({ id: 'mastra-storage', url: 'file:./mastra.db' }),
  schedules: {
    prepare: async ({ agentId, schedule, trigger }) => {
      // Return overrides, null to skip this fire, or undefined for defaults
      return { prompt: `Status as of ${trigger.firedAt.toISOString()}` }
    },
    onFinish: async ({ agentId, outcome, runId }) => {
      // Runs on any non-error, non-abort outcome
    },
    onError: async ({ agentId, phase, error }) => {
      // Runs when prepare, the signal, or the agent run threw
    },
    onAbort: async ({ agentId, runId }) => {
      // Runs when the run was aborted mid-stream
    },
  },
})

这些钩子包括：

• prepare：在触发前运行。返回一个对象以覆盖 prompt 或 threadId 等触发时参数，返回 null 跳过本次触发，或返回 undefined 使用已存储的默认值。
• onFinish：对每个达到非错误、非中止终态的触发器运行一次。
• onError：在 prepare 或 signal 失败后运行。agent 运行失败时也会运行。
• onAbort：在运行中途被中止时运行。

每个钩子上下文都包含 agentId（该 schedule 触发的 agent）以及 schedule 和 trigger。

钩子异常会被捕获并记录日志。它们绝不会重新路由 worker 或触发另一个钩子。

Mastra Code 中的重复提示词

Mastra Code 提供 /schedules 命令，可将重复提示词附加到当前对话 thread。与 mastra.schedules 不同，这些 schedules 仅存在于创建它们的 Mastra Code 进程中：不会写入存储，每次触发都通过 agent.sendSignal() 直接发送到 thread。

运行 /schedules 会打开一个菜单，其中包含 Create schedule 以及当前 thread 上每个 schedule 对应的一行。创建 schedule 会经历以下步骤：

1. 选择每次触发发送的内容：Prompt、每次触发都会重新读取的 Prompt file，或每次触发都会运行的 Script。
2. 输入提示词文本或文件路径。路径从项目根目录解析。对于脚本，你可以添加在脚本输出之后发送的提示词。
3. 从 1m 到 1d 中选择节奏，或输入 20m、3h 等。分钟步长必须能整除一小时，小时步长必须能整除一天。
4. 确认。

脚本从项目根目录运行，超时时间为 60 秒，其 stdout、stderr 和退出码会成为提示词。附加提示词绝不会传给脚本。

选择现有 schedule 会提供 Run now、Pause 或 Resume 以及 Delete。Run now 会立即触发一次而不改变节奏，对已暂停的 schedules 也有效，若同一 schedule 的某次触发仍在运行则会跳过。

每次触发都会以 user 类型 signal 到达 thread，并在对话记录中显示为 schedule 条目，包含该 schedule 的 id、节奏、来源和脚本退出状态。如果 thread 正忙，正在运行的 agent 会将提示词作为下一次输入接收，就像你在运行中途输入消息一样。如果 thread 空闲，它会唤醒并运行。Schedules 会在进程中的任何 thread 上触发，而不仅是终端中聚焦的那个。执行 /new 后，新 schedule 会绑定到新 thread。

须知：

• 会话作用域。 Schedules 仅存在于创建它们的 Mastra Code 进程中，并在该进程退出时停止。共享同一数据库的其他 Mastra Code 进程永远不会看到或触发它们。
• 时钟边界。 5m 会在 :00、:05、:10 等时刻触发，而不是在创建后的五分钟；1d 会在本地午夜触发。小时和天节奏像 cron 一样遵循跨越夏令时变化的挂钟时间。机器休眠期间错过的触发，或其计时器延迟超过一分钟的触发会被跳过，schedule 会在下一个边界恢复。
• 重叠触发会被跳过。 如果下一个边界到来时脚本仍在运行，则该次触发不会执行。

Agent schedule 工具

在 /settings 中开启 Experimental schedule tools（需要重启）后，agent 会获得管理相同 schedules 的工具：schedule_create、schedule_list、schedule_update（暂停或删除）、schedule_resume 和 schedule_run。这些工具只能查看和更改调用它们的运行所在 thread 上的 schedules。由于 schedule 每次触发都可能运行脚本，除非开启 YOLO 模式，schedule_create、schedule_resume 和 schedule_run 需要与运行 shell 命令相同的审批。agent 创建的 schedules 会在对话记录中标记为 created by agent。

相关内容

• mastra.schedules：创建和管理 schedules 的 API 参考。
• Signals：有 thread 的 schedules 背后的投递机制。
• 定时 workflow：在 workflow 定义上声明 cron schedule。