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

# `mastra.schedules`

**추가된 항목:** `@mastra/core@1.50.0`

`mastra.schedules`지속적인 크론 일정을 위한 CRUD 서비스입니다. 이를 사용하여 Agent 또는 Workflow에 대한 일정을 생성, 나열, 업데이트, 일시 중지, 재개, 수동 실행 및 삭제합니다.

사용 패턴 및 개념은 다음을 참조하세요.[Schedules](https://mastra.zisheng.pro/ko/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' },
})
```

일정에는 일정 도메인을 구현하는 스토리지 어댑터가 필요합니다. 지원되는 어댑터는 다음과 같습니다.`@mastra/libsql`, `@mastra/pg`, `@mastra/mysql`, `@mastra/mongodb`, `@mastra/convex`, 그리고`@mastra/spanner`.

## 행동 양식

### 일정 만들기

#### `create(input)`

Agent 또는 Workflow 일정을 만듭니다. Agent 일정을 만들려면 `agentId`를 전달하고, Workflow 일정을 만들려면 `workflowId`를 전달하세요.

```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 또는 스레드의 여러 일정을 구분하는 자유 형식 레이블입니다.

**timezone** (`string`): cron 실행 시간을 계산하는 데 사용되는 IANA 시간대입니다(예: America/New\_York).

**threadId** (`string`): 예약된 신호를 수신하는 스레드입니다. 생략하면 각 실행은 agent.generate()를 사용하여 스레드 없이 실행됩니다.

**resourceId** (`string`): 스레드 기반 일정의 리소스 ID입니다. threadId가 설정된 경우 필수입니다.

**signalType** (`AgentSignalType`): 스레드 기반 일정 실행의 신호 유형입니다. 기본값은 notification입니다.

**tagName** (`string`): 예약된 신호를 렌더링하는 데 사용되는 XML 태그 이름입니다. 기본값은 schedule입니다.

**attributes** (`AgentSignalAttributes`): 예약된 신호의 XML 태그에 렌더링되는 속성입니다.

**providerOptions** (`Record<string, unknown>`): 매 실행 시 일정 신호 페이로드에 병합되는 JSON 안전 Provider 옵션입니다.

**ifActive** (`ScheduleIfActive`): 대상 스레드가 활발히 스트리밍 중일 때의 동작입니다. threadId가 필요합니다.

**ifIdle** (`ScheduleIfIdle`): 대상 스레드가 유휴 상태일 때의 동작입니다. 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 실행에 전달되는 요청 컨텍스트입니다.

**metadata** (`Record<string, unknown>`): 일정 행과 함께 저장되는 임의의 메타데이터입니다.

**status** (`'active' | 'paused'`): 초기 수명 주기 상태입니다. 기본값은 active입니다. (Default: `'active'`)

### 일정 읽기

#### `get(id)`

ID별로 일정을 가져옵니다. 베어 Agent 일정 ID도 정규화된 일정 ID로 확인됩니다.`agent_<slug>` form.

```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`): 이 스레드의 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 일정 패치에서는 `cron`, `timezone`, `prompt`, `name`, `signalType`, `tagName`, `attributes`, `providerOptions`, `ifActive`, `ifIdle`, `metadata`, `status`를 업데이트할 수 있습니다. `threadId`와 `resourceId`는 패치할 수 없습니다. 스레드 대상을 변경해야 한다면 새 일정을 만드세요. Workflow 일정 패치에서는 `cron`, `timezone`, `inputData`, `initialState`, `requestContext`, `metadata`, `status`를 업데이트할 수 있습니다. `prompt`, `signalType`, `ifIdle` 같은 Agent 전용 패치 필드를 Workflow 일정에 사용하면 오류가 발생합니다.

### 수명주기

#### `pause(id)`

일정을 일시 중지합니다. 일시 중지는 지속적이고 멱등적입니다.

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

#### `resume(id)`

일시 중지된 일정을 재개하고 현재 시간에서 다음 실행 시간을 다시 계산합니다.

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

#### `run(id)`

크론 주기를 변경하지 않고 즉시 일정을 한 번 실행합니다.

```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_` 접두사가 사용됩니다.
- 스레드 기반 Agent 일정에서는 `threadId`가 설정된 경우 `resourceId`가 필요합니다.
- `signalType`, `ifActive`, `ifIdle`, `resourceId`에는 `threadId`가 필요합니다.
- Workflow 일정은 `prompt`, `signalType`, `ifIdle` 같은 Agent 전용 패치 필드를 허용하지 않습니다.
- `run()`은 수동 실행을 즉시 게시하며 저장된 cron 주기를 변경하지 않습니다.