> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# `mastra.schedules`

**新增於：** `@mastra/core@1.50.0`

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

使用模式與概念請參閱 [Schedules](https://mastra.zisheng.pro/zh-TW/docs/long-running-agents/schedules)。

## 使用範例

建立 Agent 排程：

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

建立 Workflow 排程：

```typescript
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 排程。

```typescript
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。 (Default: `'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。 (Default: `'active'`)

### 讀取排程

#### `get(id)`

依 ID 取得排程。不含前綴的 Agent 排程 ID 也會解析為正規化的 `agent_<slug>` 形式。

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

#### `list(filter?)`

列出排程。未提供 filter 時，會傳回 Agent 與 Workflow 排程。

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

**filter** (`ListSchedulesFilter`): list 操作的選填 filter。

**filter.agentId** (`string`): 僅傳回此 Agent 的 Agent 排程。

**filter.workflowId** (`string`): 僅傳回此 Workflow 的 Workflow 排程。

**filter.threadId** (`string`): 僅傳回此 thread 的 Agent 排程。

**filter.resourceId** (`string`): 僅傳回此 resource 的 Agent 排程。

**filter.name** (`string`): 僅傳回具有此標籤的 Agent 排程。

**filter.status** (`'active' | 'paused'`): 僅傳回具有此狀態的排程。

### 更新排程

#### `update(id, patch)`

更新排程。變更 `cron` 或 `timezone` 會重新計算下次觸發時間。將 `status` 從 `paused` 更新為 `active` 也會重新計算下次觸發時間。

```typescript
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)`

暫停排程。暫停操作具有持久性與等冪性。

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

#### `resume(id)`

繼續已暫停的排程，並從目前時間重新計算下次觸發時間。

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

#### `run(id)`

立即觸發排程一次，不變更其 cron 執行週期。

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

Agent 排程的 `claimId` 使用 `manual_<scheduleId>_<timestamp>`。Workflow 排程的 `claimId` 使用 `sched_<scheduleId>_<timestamp>`，並會重複用作 Workflow run ID。

#### `delete(id)`

刪除排程。刪除不存在的排程不會執行任何操作。

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