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

# 예약된 Workflow

선언하다`schedule`필드를 입력하면 Mastra는 사용자가 지정한 cron에서 이를 실행합니다. 동일한 Workflow를 직접 호출할 수 있습니다.`workflow.start()`, 예약된 실행 및 수동 실행은 단일 실행 경로를 공유합니다.

## 빠른 시작

다음 Workflow는 뉴욕 시간으로 매일 오전 9시에 실행됩니다. 다른 Workflow와 마찬가지로 `Mastra`에 등록하면 스케줄러가 자동으로 감지합니다.

```typescript
import { createWorkflow, createStep } from '@mastra/core/workflows'
import { z } from 'zod'

const sendReport = createStep({
  id: 'send-report',
  inputSchema: z.object({ userId: z.string() }),
  outputSchema: z.object({ ok: z.boolean() }),
  execute: async ({ inputData }) => {
    // ...send the report for inputData.userId
    return { ok: true }
  },
})

export const dailyReport = createWorkflow({
  id: 'daily-report',
  inputSchema: z.object({ userId: z.string() }),
  outputSchema: z.object({ ok: z.boolean() }),
  schedule: {
    cron: '0 9 * * *',
    timezone: 'America/New_York',
    inputData: { userId: 'system' },
  },
})
  .then(sendReport)
  .commit()
```

별도의 "일정 등록" 호출은 없습니다. `Mastra`가 부팅될 때 스케줄러가 Workflow의 `schedule`을 직접 읽습니다.

## 무엇`schedule` changes

`schedule`을 선언한 Workflow는 자동으로 **이벤트 기반 실행 엔진**으로 승격됩니다. 공개 API(`workflow.start()`, `workflow.startAsync()`, `streamLegacy()`, `resume()`)는 변경되지 않습니다. `EventedWorkflow extends Workflow`는 일치하는 시그니처로 각 메서드를 재정의합니다. 코드에서는 예약 실행과 수동 실행을 구분할 수 없습니다. 이 승격에는 한 가지 실질적인 영향이 있습니다. 이벤트 기반 실행에는 동시 업데이트를 지원하는 스토리지 어댑터가 필요합니다. 예를 들면 `@mastra/libsql`이 있습니다. 어댑터가 이를 지원하지 않으면 `createRun()`이 `schedule` 필드를 가리키는 명확한 오류를 발생시킵니다. 어댑터를 변경하거나 일정을 제거하세요.

## 단일 일정

하나의 주기로 실행되는 Workflow에는 `schedule` 객체를 전달하세요.

```typescript
const dailyReport = createWorkflow({
  id: 'daily-report',
  schedule: {
    cron: '0 9 * * *',
    timezone: 'America/New_York',
    inputData: { userId: 'system' },
  },
  // ...
})
```

전지:

- `cron`(필수): 5, 6 또는 7개 부분으로 구성된 cron 표현식입니다. Workflow 생성 시 검증됩니다.
- `timezone`(선택 사항): IANA 시간대(예: `America/New_York`)입니다. 기본값은 호스트의 로컬 시간대입니다. 실행 시간이 서버 로캘에 좌우되지 않도록 프로덕션에서는 명시적으로 설정하세요.
- `inputData`(선택 사항): 실행할 때마다 Workflow 입력으로 전달되는 페이로드입니다.
- `initialState`(선택 사항): 실행의 초기 상태입니다.
- `requestContext`(선택 사항): 실행에 연결되는 요청 컨텍스트입니다.
- `metadata`(선택 사항): 일정 행과 함께 영속화되는 임의의 메타데이터입니다.

## 여러 일정

여러 케이던스에서 동일한 Workflow를 실행하려면 배열을 전달하세요. 각 항목에는 고유한 마구간이 필요합니다.`id`:

```typescript
const statusCheck = createWorkflow({
  id: 'status-check',
  schedule: [
    { id: 'morning', cron: '0 9 * * *', inputData: { window: 'morning' } },
    { id: 'evening', cron: '0 18 * * *', inputData: { window: 'evening' } },
  ],
  // ...
})
```

각 항목은 독립적인 일정 행을 생성하고 자체 크론에서 실행되며 Studio 일정 보기에 별도로 표시됩니다.

## Studio에서 일정 보기

Studio 표면 일정은 Workflow 내부의 탭이 아닌 최상위 영역으로 표시됩니다.

- **모든 일정**: `/workflows/schedules`를 열어 Workflow 전체의 목록을 확인하세요. 각 행에는 Workflow ID, cron, 다음 실행 시각 및 가장 최근 실행 상태가 표시되므로 "문제가 있는 일정이 있는가?"를 한눈에 확인할 수 있습니다.
- **Workflow로 필터링**: `?workflowId=<id>`를 추가해 목록을 하나의 Workflow로 한정하세요. 예: `/workflows/schedules?workflowId=daily-report`.
- **일정 세부 정보**: 행을 선택해 `/workflows/schedules/:scheduleId`를 여세요. 이 페이지에는 일정 메타데이터와 **Pause** / **Resume** 컨트롤이 표시되고, 그 아래에 전체 트리거 기록이 이어집니다. Workflow에 일정이 하나 이상 있으면 Workflow 헤더에 **Schedules** 작업이 표시됩니다.
- 하나의 일정이 일치하면 작업이 해당 세부 정보 페이지로 바로 연결됩니다.
- 여러 일정: 작업은 다음 위치의 Workflow 필터링 목록에 연결됩니다.`/workflows/schedules?workflowId=<id>`.
- 일정 없음: 작업이 숨겨집니다.

### 트리거 기록

모든 화재는 실행 ID, 예약 시간, 실제 화재 시간 및 게시 상태가 포함된 트리거 행을 기록합니다. 일정 세부 정보 페이지는 각 트리거를 해당 Workflow 실행에 연결하고 다음을 표시합니다.

- 실행 상태(`running`, `success`, `failed`, `suspended`, `canceled`)가 배지로 표시됩니다.
- 실행의 시작 시각과 지속 시간입니다.
- `/workflows/:workflowId/graph/:runId`에 있는 실행의 전체 그래프 보기 링크입니다.
- 트리거 게시와 실행 스냅샷 사이의 경합으로 실행 레코드가 아직 작성되지 않은 트리거에는 `pending` 배지가 표시됩니다.
- 스케줄러가 실행을 전혀 대기열에 넣지 못한 경우 게시 오류와 함께 `publish failed` 배지가 표시됩니다. 비종료 상태의 트리거는 패널이 터미널 상태에 도달할 때까지 5초마다 폴링하도록 합니다. 목록에는 페이지가 매겨져 있으므로 장기 실행 일정은 수천 개의 행을 앞에 로드하지 않습니다.

## 런타임 시 일정 일시 중지

프로덕션 환경에서 예약된 Workflow가 잘못 실행되는 경우 데이터베이스를 다시 배포하거나 직접 편집할 필요가 없습니다. SDK에서 일시중지합니다.

```typescript
import { MastraClient } from '@mastra/client-js'

const client = new MastraClient({ baseUrl: 'http://localhost:4111' })

// Schedule ids are derived from the workflow id: `wf_<workflowId>` for a
// single declarative schedule, or `wf_<workflowId>__<scheduleId>` when you
// declare multiple schedules per workflow as an array.
await client.pauseSchedule('wf_daily-report')
// ...investigate, ship a fix, then:
await client.resumeSchedule('wf_daily-report')
```

Studio에서 일정 세부 정보 페이지를 열고 헤더의 **Pause** 또는 **Resume**을 선택하세요. 알아야 할 몇 가지 규칙:

- 일시 중지 상태는 영속화됩니다. 상태가 일정 테이블에 기록되므로 프로세스 재시작과 재배포 후에도 유지됩니다. 선언적 구성의 upsert는 `cron`, `timezone` 또는 다른 필드를 변경하더라도 사용자가 설정한 상태를 덮어쓰지 않습니다.
- 재개하면 현재 시각을 기준으로 `nextFireAt`이 다시 계산됩니다. 일주일 동안 일시 중지된 일정도 재개하는 순간 밀린 실행 일곱 개를 시작하지 않습니다. 다음 정규 cron 시점에 실행됩니다.
- `resumeSchedule` 또는 Studio의 **Resume** 버튼으로 일시 중지를 해제하세요. Workflow의 `schedule` 구성을 수정해도 일시 중지된 행은 재개되지 않습니다.
- 일시 중지와 재개는 멱등적입니다. 이미 일시 중지된 일정에서 일시 중지를 호출해도 아무 변화가 없습니다.
- 이러한 명령형 작업은 기존 일정을 제어합니다. 선언적 일정은 코드에서 작성합니다. 선언적 일정은 `createWorkflow`의 `schedule` 필드를 통해 코드에서 생성, 삭제 및 수정됩니다. 대신 런타임에 명령형으로 일정을 만들려면 `workflowId`와 함께 통합 [`mastra.schedules`](https://mastra.zisheng.pro/ko/docs/long-running-agents/schedules) 서비스를 사용하세요. 기본 HTTP 경로는 `POST /api/schedules/:scheduleId/pause`와 `POST /api/schedules/:scheduleId/resume`입니다. 두 경로 모두 `schedules:write` 권한이 필요합니다.

## 변경 사항을 적용하여 재배포

`schedule` 구성을 변경하고 다시 배포하면 Mastra는 기존 일정 행과 새 구성의 차이를 비교합니다.

- `cron` 또는 `timezone`이 변경되면 `nextFireAt`이 다시 계산됩니다.
- `inputData`, `initialState` 또는 `metadata`가 변경되면 행이 제자리에서 패치되고 다음 실행 시각은 유지됩니다.
- 사용자가 설정한 상태(예: `client.pauseSchedule`을 통한 일시 중지)와 실행 기록은 절대 덮어쓰지 않습니다. Workflow의 `schedule` 배열에서 일정 항목을 제거하면 다음 부팅 시 해당 행이 삭제됩니다.

## 배포 토폴로지

내장 스케줄러는 `setInterval` 틱 루프를 사용해 일정 테이블을 폴링하고 실행 시점이 된 행을 확보합니다. 그런 다음 프로세스 내 pubsub을 통해 Workflow 실행을 디스패치합니다. 이 방식은 호스트 프로세스가 장시간 실행된다고 가정합니다.

### 장기 호스트(권장)

Fly Machines, Railway, Render, AWS ECS, GKE 또는 자체 서버 같은 대상에 배포하면 cron 틱 사이에도 Mastra 프로세스가 활성 상태로 유지됩니다. 별도의 설정 없이 일정이 작동합니다. 프로덕션 배포에서는 스케줄러를 [전용 워커 프로세스](https://mastra.zisheng.pro/ko/docs/deployment/workers)로 실행해 API 계층과 격리할 수 있습니다.

### 서버리스 플랫폼

Vercel, Netlify, AWS Lambda 및 Cloudflare Workers와 같은 서비스로서의 기능 플랫폼은 각 요청 후에 프로세스를 종료합니다. 틱 루프는 두 번째 틱을 얻지 못하기 때문에 코드에 선언된 일정은 현재 내장된 스케줄러가 있는 이러한 플랫폼에서 실행되지 않습니다.

이러한 플랫폼에서는 대신 [`@mastra/inngest`](#inngest-workflows)를 사용하세요. Inngest는 서버리스 네이티브이며 cron 상태를 대신 보관합니다.

## 수집 Workflow

이 페이지에서 설명하는 `schedule` 필드는 Mastra의 내장 스케줄러를 구동합니다. `@mastra/inngest`를 사용하면 예약된 Workflow는 `createFunction`에 있는 Inngest 자체 `cron` 필드를 통해 구성되며 Inngest 스케줄러에서 실행됩니다. 실제적인 의미:

- Inngest 일정은 Studio의 `/workflows/schedules` 보기에 표시되지 않습니다.
- Inngest Workflow에는 Workflow 헤더의 **Schedules** 작업이 표시되지 않습니다.
- `client.pauseSchedule`과 `client.resumeSchedule`은 Inngest 일정을 제어하지 않습니다. Inngest 일정은 [Inngest 대시보드](https://www.inngest.com/docs/guides/scheduled-functions)에서 관리하세요. 예약을 처음부터 끝까지 Mastra에서 관리하려면 Mastra 일정을 사용하세요.

## 관련된

- [Workflow 개요](https://mastra.zisheng.pro/ko/docs/workflows/overview)
- [일시 중지 및 재개](https://mastra.zisheng.pro/ko/docs/workflows/suspend-and-resume)
- [워커](https://mastra.zisheng.pro/ko/docs/deployment/workers): [스케줄러 워커](https://mastra.zisheng.pro/ko/docs/deployment/workers)는 전용 프로세스에서 cron 일정을 실행합니다.
- [Agent 일정](https://mastra.zisheng.pro/ko/docs/long-running-agents/schedules): cron 일정에 따라 Workflow 대신 Agent를 실행하고 `mastra.schedules`를 통해 런타임에 두 일정 유형을 모두 관리합니다.