예약된 Workflow

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

빠른 시작

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

src/mastra/workflows/daily-report.ts

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 객체를 전달하세요.

src/mastra/workflows/daily-report.ts

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:

src/mastra/workflows/status-check.ts

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에서 일시중지합니다.

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 서비스를 사용하세요. 기본 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 프로세스가 활성 상태로 유지됩니다. 별도의 설정 없이 일정이 작동합니다. 프로덕션 배포에서는 스케줄러를 전용 워커 프로세스로 실행해 API 계층과 격리할 수 있습니다.

서버리스 플랫폼

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

이러한 플랫폼에서는 대신 @mastra/inngest를 사용하세요. 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 대시보드에서 관리하세요. 예약을 처음부터 끝까지 Mastra에서 관리하려면 Mastra 일정을 사용하세요.

관련된

• Workflow 개요
• 일시 중지 및 재개
• 워커: 스케줄러 워커는 전용 프로세스에서 cron 일정을 실행합니다.
• Agent 일정: cron 일정에 따라 Workflow 대신 Agent를 실행하고 mastra.schedules를 통해 런타임에 두 일정 유형을 모두 관리합니다.