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

# `mastra.schedules`

**引入版本：** `@mastra/core@1.50.0`

`mastra.schedules` 是用于持久化 Cron 调度的 CRUD 服务。你可以用它为 Agent 或 Workflow 创建、列出、更新、暂停、恢复、手动运行和删除调度。

有关用法模式和概念，请参阅[调度](https://mastra.zisheng.pro/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 的 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 的提示词。

**name** (`string`): 自由格式标签，用于区分同一 Agent 或 thread 上的多个调度。

**timezone** (`string`): 用于确定 Cron 触发时间的 IANA 时区，例如 America/New\_York。

**threadId** (`string`): 接收调度信号的 thread。如果省略，每次触发都会通过 agent.generate() 在不使用 thread 的情况下运行。

**resourceId** (`string`): 使用 thread 的调度所对应的资源 ID。设置 threadId 时必填。

**signalType** (`AgentSignalType`): 使用 thread 的调度触发时所用的信号类型。默认为 notification。

**tagName** (`string`): 用于渲染调度信号的 XML 标签名称。默认为 schedule。

**attributes** (`AgentSignalAttributes`): 渲染到调度信号 XML 标签上的属性。

**providerOptions** (`Record<string, unknown>`): 每次触发时合并到调度信号 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 运行的请求上下文。

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

列出调度。不指定 filter 时，会返回 Agent 和 Workflow 调度。

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

**filter** (`ListSchedulesFilter`): 列表操作的可选 filter。

**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 周期。