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 的儲存適配器。支援的適配器包括 @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

接收排程 signal 的 thread。如省略，每次觸發都不使用 thread，並透過 agent.generate() 執行。

resourceId?:

string

有 thread 排程的資源 ID。設定 threadId 時必須提供。

signalType?:

AgentSignalType

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

tagName?:

string

用於呈現排程 signal 的 XML 標籤名稱。預設為 schedule。

attributes?:

AgentSignalAttributes

在排程 signal 的 XML 標籤上呈現的屬性。

providerOptions?:

Record<string, unknown>

每次觸發時合併至排程 signal 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 執行的請求 context。

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?)

列出排程。如未指定篩選條件，會傳回 Agent 和 Workflow 排程。

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

filter?:

ListSchedulesFilter

列表操作的可選篩選條件。

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 執行週期。