mastra.schedules

新增於： @mastra/core@1.50.0

mastra.schedules 是持久化 cron 排程的 CRUD 服務。可用來建立、列出、更新、暫停、繼續、手動執行及刪除 Agent 或 Workflow 的排程。

使用模式與概念請參閱 Schedules。

使用範例

建立 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' },
})

Schedule 需要實作 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 的 prompt。

name?:

string

用來區分同一 Agent 或 thread 上多個排程的自由格式標籤。

timezone?:

string

用來解析 cron 觸發時間的 IANA 時區，例如 America/New_York。

threadId?:

string

接收排程 signal 的 thread。省略時，每次觸發都會以 agent.generate() 執行，不使用 thread。

resourceId?:

string

thread 排程的 resource ID。設定 threadId 時必須提供。

signalType?:

AgentSignalType

thread 排程觸發時使用的 signal 類型。預設為 notification。

tagName?:

string

用來呈現排程 signal 的 XML tag 名稱。預設為 schedule。

attributes?:

AgentSignalAttributes

呈現在排程 signal XML tag 上的 attribute。

providerOptions?:

Record<string, unknown>

每次觸發時合併至排程 signal payload，且可安全序列化為 JSON 的 Provider 選項。

ifActive?:

ScheduleIfActive

目標 thread 正在串流時的行為。必須設定 threadId。

ifIdle?:

ScheduleIfIdle

目標 thread 閒置時的行為。必須設定 threadId。

metadata?:

Record<string, unknown>

與排程資料列一同儲存的任意中繼資料。

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 執行作業的 request context。

metadata?:

Record<string, unknown>

與排程資料列一同儲存的任意中繼資料。

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

list 操作的選填 filter。

ListSchedulesFilter

agentId?:

string

僅傳回此 Agent 的 Agent 排程。

workflowId?:

string

僅傳回此 Workflow 的 Workflow 排程。

threadId?:

string

僅傳回此 thread 的 Agent 排程。

resourceId?:

string

僅傳回此 resource 的 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 run 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 執行週期。