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

# `mastra.schedules`

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

`mastra.schedules` 是用於持久保存 cron 排程的 CRUD 服務。你可以用它為 Agent 或 Workflow 建立、列出、更新、暫停、恢復、手動執行及刪除排程。

有關使用模式和概念，請參閱[排程](https://mastra.zisheng.pro/zh-HK/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' },
})
```

排程需要實作 schedules domain 的儲存適配器。支援的適配器包括 `@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 的提示詞。

**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。 (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 執行的請求 context。

**metadata** (`Record<string, unknown>`): 與排程記錄一同儲存的任意 metadata。

**status** (`'active' | 'paused'`): 初始生命週期狀態。預設為 active。 (Default: `'active'`)

### 讀取排程

#### `get(id)`

按 ID 取得排程。未加前綴的 Agent 排程 ID 亦會解析為標準化的 `agent_<slug>` 格式。

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

#### `list(filter?)`

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

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

**filter** (`ListSchedulesFilter`): 列表操作的可選篩選條件。

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

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

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

**filter.resourceId** (`string`): 只傳回此資源的 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 執行 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 執行週期。