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

# `mastra.schedules`

**追加バージョン：** `@mastra/core@1.50.0`

`mastra.schedules` は、永続化された cron schedules の CRUD サービスです。Agent または Workflow の schedules を作成、一覧取得、更新、一時停止、再開、手動実行、削除できます。

使用パターンと概念については、[Schedules](https://mastra.zisheng.pro/ja/docs/long-running-agents/schedules)を参照してください。

## 使用例

Agent schedule を作成します。

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

Workflow schedule を作成します。

```typescript
const schedule = await mastra.schedules.create({
  workflowId: 'daily-report',
  cron: '0 9 * * *',
  inputData: { reportType: 'summary' },
})
```

Schedules には、schedules ドメインを実装したストレージアダプターが必要です。対応するアダプターには、`@mastra/libsql`、`@mastra/pg`、`@mastra/mysql`、`@mastra/mongodb`、`@mastra/convex`、`@mastra/spanner` があります。

## メソッド

### Schedules の作成

#### `create(input)`

Agent または Workflow の schedule を作成します。Agent schedule を作成するには `agentId`、Workflow schedule を作成するには `workflowId` を渡します。

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

##### Agent schedule の入力

**id** (`string`): 省略可能な固定 schedule ID。値は agent\_\<slug> に正規化されます。省略すると、Mastra が agent\_\<uuid> ID を生成します。

**agentId** (`string`): schedule の実行ごとに起動する Agent の ID。

**cron** (`string`): schedule の cron 式。5、6、7パートの cron 式と Croner のニックネームを使用できます。

**prompt** (`string`): schedule の実行ごとに Agent へ送信するプロンプト。

**name** (`string`): 同じ Agent またはスレッド上の複数の schedules を区別する自由形式のラベル。

**timezone** (`string`): cron の実行時刻の解決に使用する IANA タイムゾーン（America/New\_York など）。

**threadId** (`string`): スケジュールされた signal を受信するスレッド。省略すると、各実行は agent.generate() によりスレッドなしで動作します。

**resourceId** (`string`): スレッド付き schedules のリソース ID。threadId を設定する場合は必須です。

**signalType** (`AgentSignalType`): スレッド付き schedule の実行に使用する signal タイプ。デフォルトは notification です。

**tagName** (`string`): スケジュールされた signal のレンダリングに使用する XML タグ名。デフォルトは schedule です。

**attributes** (`AgentSignalAttributes`): スケジュールされた signal の XML タグにレンダリングする属性。

**providerOptions** (`Record<string, unknown>`): 実行ごとに schedule の signal payload へマージする、JSON で安全に扱える Provider オプション。

**ifActive** (`ScheduleIfActive`): 対象スレッドがストリーミング中の場合の動作。threadId が必要です。

**ifIdle** (`ScheduleIfIdle`): 対象スレッドがアイドル状態の場合の動作。threadId が必要です。

**metadata** (`Record<string, unknown>`): schedule の行とともに保存する任意のメタデータ。

**status** (`'active' | 'paused'`): 初期ライフサイクルステータス。デフォルトは active です。 (Default: `'active'`)

##### Workflow schedule の入力

**id** (`string`): 省略可能な固定 schedule ID。値は schedule\_\<slug> に正規化されます。省略すると、Mastra が schedule\_\<uuid> ID を生成します。

**workflowId** (`string`): schedule の実行ごとに開始する Workflow の ID。

**cron** (`string`): schedule の 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>`): schedule の行とともに保存する任意のメタデータ。

**status** (`'active' | 'paused'`): 初期ライフサイクルステータス。デフォルトは active です。 (Default: `'active'`)

### Schedules の取得

#### `get(id)`

ID で schedule を取得します。プレフィックスのない Agent schedule ID も、正規化された `agent_<slug>` 形式として解決されます。

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

#### `list(filter?)`

Schedules の一覧を取得します。filter を指定しない場合、Agent と Workflow の schedules を返します。

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

**filter** (`ListSchedulesFilter`): 一覧取得処理に使用する省略可能な filter。

**filter.agentId** (`string`): この Agent の Agent schedules のみを返します。

**filter.workflowId** (`string`): この Workflow の Workflow schedules のみを返します。

**filter.threadId** (`string`): このスレッドの Agent schedules のみを返します。

**filter.resourceId** (`string`): このリソースの Agent schedules のみを返します。

**filter.name** (`string`): このラベルを持つ Agent schedules のみを返します。

**filter.status** (`'active' | 'paused'`): このステータスの schedules のみを返します。

### Schedules の更新

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

Schedule を更新します。`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 schedule の patch では、`cron`、`timezone`、`prompt`、`name`、`signalType`、`tagName`、`attributes`、`providerOptions`、`ifActive`、`ifIdle`、`metadata`、`status` を更新できます。`threadId` と `resourceId` は patch できません。対象スレッドを変更する場合は、新しい schedule を作成してください。

Workflow schedule の patch では、`cron`、`timezone`、`inputData`、`initialState`、`requestContext`、`metadata`、`status` を更新できます。`prompt`、`signalType`、`ifIdle` など Agent 専用の patch フィールドを Workflow schedule に指定するとエラーがスローされます。

### ライフサイクル

#### `pause(id)`

Schedule を一時停止します。一時停止は永続的かつ冪等です。

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

#### `resume(id)`

一時停止中の schedule を再開し、現在時刻から次回の実行時刻を再計算します。

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

#### `run(id)`

cron の実行間隔を変更せず、schedule を即座に1回実行します。

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

Agent schedules の `claimId` は `manual_<scheduleId>_<timestamp>` 形式です。Workflow schedules の `claimId` は `sched_<scheduleId>_<timestamp>` 形式で、Workflow の run ID として再利用されます。

#### `delete(id)`

Schedule を削除します。存在しない schedule を削除しても何も起こりません。

```typescript
await mastra.schedules.delete('pinger')
```

## Schedule の動作

- Agent schedule ID には `agent_` プレフィックスを使用します。`mastra.schedules.create()` で作成した Workflow schedule ID には `schedule_` プレフィックスを使用します。
- スレッド付き Agent schedules で `threadId` を設定する場合は、`resourceId` が必要です。
- `signalType`、`ifActive`、`ifIdle`、`resourceId` には `threadId` が必要です。
- Workflow schedules は、`prompt`、`signalType`、`ifIdle` など Agent 専用の patch フィールドを受け付けません。
- `run()` は手動実行を即座に発行し、保存されている cron の実行間隔は変更しません。