일정

파일 기반 Agent가 검색합니다.schedules그로부터schedules/예배 규칙서. 각 파일은 하나의 반복 작업, 즉 cron 표현식과 Agent가 실행될 때 수행해야 하는 작업을 선언합니다. Mastra는 시작 시 이를 일정 저장소에 등록하므로 예약된 Agent에는 런타임 등록 코드가 필요하지 않습니다.

파일 기반 규칙에 대해서는 이 페이지를 사용하십시오. 대신 런타임에 일정을 생성하려면 다음을 참조하세요.Schedules.

파일 기반 Agent가 하나의 가져오기 경로만 사용하도록 defineSchedule이 @mastra/core/agent에서 다시 내보내집니다. @mastra/core/schedules에서도 이를 내보냅니다.

빠른 시작

Agent 아래에 파일을 추가합니다.schedules/ directory:

src/mastra/agents/support/schedules/heartbeat.ts

import { defineSchedule } from '@mastra/core/agent'

export default defineSchedule({
  cron: '*/5 * * * *',
  prompt: 'Check system health and report any failures.',
})

Mastra는 5분마다 해당 Prompt로 support Agent를 실행합니다.

일정 신원

일정 ID는 schedules/를 기준으로 확장자를 제거한 상대 경로입니다. 따라서 중첩된 디렉터리로 관련 일정을 그룹화할 수 있습니다.

Schedule layout

src/mastra/agents/
└── support/
    ├── config.ts
    ├── instructions.md
    └── schedules/
        ├── heartbeat.ts      # id: heartbeat
        ├── cleanup.md        # id: cleanup
        └── billing/
            └── sweep.ts      # id: billing/sweep

해당 ID는 빌드 전체에서 안정적이므로 Mastra가 편집된 일정과 새 일정을 알릴 수 있습니다. 파일 이름을 바꾸거나 파일을 이동하는 것은 하나의 일정을 삭제하고 다른 일정을 만드는 것으로 간주됩니다.

heartbeat.ts와 heartbeat.md는 같은 id로 해석되므로 둘 다 선언하면 빌드 오류가 발생합니다.

실행 모드

일정은 정확히 하나의 실행 모드를 설정합니다. 둘 다 설정하거나 둘 다 설정하지 않으면 빌드가 실패합니다.

Prompt 모드

prompt고정된 메시지로 소유 Agent를 실행합니다. 이것은 실행 후 잊어버리는 방식입니다. 아무것도 결과를 기다리지 않습니다.

src/mastra/agents/support/schedules/digest.ts

import { defineSchedule } from '@mastra/core/agent'

export default defineSchedule({
  cron: '0 9 * * 1',
  timezone: 'America/New_York',
  prompt: 'Summarize last week and post the digest.',
})

핸들러 모드

handler일정이 시작될 때 화재의 매개변수를 계산합니다. Prompt가 현재 상태에 따라 달라지는 경우, 일부 실행을 건너뛰어야 하는 경우 또는 실행에 채널 전달 컨텍스트가 필요한 경우 이를 사용하세요.

src/mastra/agents/support/schedules/billing/sweep.ts

import { defineSchedule } from '@mastra/core/agent'

export default defineSchedule({
  cron: '0 3 * * *',
  handler: async ({ mastra, agentId }) => {
    const overdue = await findOverdueInvoices()

    // Returning null skips this fire; nothing runs and the trigger is
    // recorded with outcome 'skipped'.
    if (overdue.length === 0) return null

    return {
      prompt: `Chase these overdue invoices: ${overdue.join(', ')}`,
      threadId: 'billing-ops',
      resourceId: agentId,
    }
  },
})

핸들러의 반환 값은 일정에 저장된 필드와 병합됩니다. undefined를 반환하면 재정의가 적용되지 않으므로 해당 실행은 저장된 필드를 사용합니다. 핸들러 모드 일정은 prompt를 선언할 수 없기 때문에 Prompt 누락으로 실행이 실패합니다. 실행하려면 prompt를 반환하고, 건너뛰려면 null을 반환하세요. 처리기는 함수이므로 저장된 일정 행에서 지속될 수 없습니다. Mastra는 일정이 시작될 때 프로세스 중에 문제를 해결합니다. Prompt를 제공하지 않고 아무것도 선언하지 않는 핸들러 모드 일정은 Agent에 빈 메시지를 보내는 대신 이유 때문에 실패합니다.

해당 프로세스 내 조회는 스케줄러를 실행하는 프로세스에 소유 Agent가 등록되어 있어야 함을 의미합니다. 일반 배포에서는 단일 항목을 부팅하고 무료로 가져옵니다. 독립 실행형 작업자에는 서버와 동일한 항목이 필요합니다. 잘린 항목에서 하나를 부팅하면 호출할 핸들러가 없으므로 실행이 아닌 실패가 발생합니다.

마크다운 일정

.md 일정은 frontmatter에 cron을 지정하고 문서 본문을 Prompt로 사용합니다. 더 넉넉한 공간에 작성할 수 있는 Prompt 모드입니다.

src/mastra/agents/support/schedules/cleanup.md

---
cron: '0 3 * * *'
timezone: 'UTC'
name: 'nightly cleanup'
---

Review tickets untouched for 30 days.

Close the ones that are clearly resolved and summarize the rest.

cron은 항상 따옴표로 감싸세요. 선행 *는 YAML 별칭이므로 cron: */5 * * * *는 구문 분석 오류가 발생하지만 cron: "*/5 * * * *"는 올바릅니다. Frontmatter에서는 아래의 모든 옵션을 사용할 수 있지만 handler는 제외됩니다. 함수가 필요하므로 .ts 또는 .js 일정 모듈에서 사용해야 합니다. 본문이 Prompt이므로 prompt도 설정할 수 없습니다. 알 수 없는 frontmatter 필드는 조용히 무시되지 않고 빌드를 실패시키므로 ifIdel 같은 오타를 빌드 시점에 발견할 수 있습니다.

옵션

cron:

string

표준 5개 필드 cron 표현식입니다. 필수입니다. 스케줄러는 틱 루프에서 일정을 평가하므로 실질적인 최소 단위는 1분입니다. 1분 미만 단위의 필드는 지원되지 않습니다.

prompt?:

string

실행할 때마다 Agent가 처리하는 메시지입니다. 이 필드 또는 handler 중 하나만 설정하세요.

handler?:

(ctx) => ScheduleOverrides | null | undefined

트리거 시점에 실행 내용을 계산합니다. 적용할 재정의 값을 반환하거나, 이번 실행을 건너뛰려면 null을 반환하세요. 아무것도 반환하지 않으면 재정의가 적용되지 않으며 핸들러 모드에는 저장된 Prompt가 없으므로 실행이 실패합니다. 이 필드 또는 prompt 중 하나만 설정하세요.

timezone?:

string

cron을 평가할 IANA 시간대입니다(예: America/New_York). 기본값은 배포 환경마다 달라지는 호스트 프로세스의 시간대이므로, 특정 시각에 민감한 작업에는 명시적으로 설정하세요. DST 전환은 시간대 규칙에 따라 처리되므로 0 9 * * *는 전환 후에도 현지 시각 오전 9시로 유지됩니다.

name?:

string

Studio에 표시되며 mastra.schedules.list({ name })로 필터링할 수 있는 자유 형식 레이블입니다.

threadId?:

string

새 실행을 시작하는 대신 기존 스레드에 신호로 실행 내용을 전송합니다. resourceId가 필요합니다.

resourceId?:

string

대상 스레드의 소유자입니다. threadId를 설정할 때 필요합니다.

signalType?:

'user' | 'state' | 'reactive' | 'notification' | 'user-message' | 'system-reminder'

= 'notification'

실행 신호의 범주입니다. 스레드형 일정에서만 사용할 수 있습니다.

tagName?:

string

= 'schedule'

신호를 렌더링할 XML 태그입니다. 따라서 실행 내용은 <schedule>…</schedule> 형식으로 Agent에 전달됩니다.

attributes?:

Record<string, string | number | boolean | null>

신호 XML 태그에 렌더링되는 속성입니다.

providerOptions?:

Record<string, unknown>

실행할 때마다 일정 신호 페이로드에 병합되는 Provider 옵션입니다. JSON으로 안전하게 직렬화할 수 있어야 합니다.

ifActive?:

ScheduleIfActive

대상 스레드가 이미 스트리밍 중일 때 수행할 작업입니다. deliver, persist, discard 중 하나입니다. 스레드형 일정에서만 사용할 수 있습니다.

ifIdle?:

ScheduleIfIdle

대상 스레드가 유휴 상태일 때 수행할 작업입니다. wake, persist, discard 중 하나입니다. 스레드형 일정에서만 사용할 수 있습니다.

status?:

'active' | 'paused'

= 'active'

행을 생성할 때 지정할 상태입니다. 동기화 과정에서는 status를 패치하지 않아 API를 통한 일시 중지가 재배포 후에도 유지되므로 최초 생성 시에만 적용됩니다. 나중에 코드에서 이 값을 변경해도 기존 일정에는 영향을 주지 않습니다.

metadata?:

Record<string, unknown>

일정 행과 함께 저장되는 임의의 JSON 안전 데이터입니다.

개발 일정 테스트

반복하는 동안 실용적이지 않은 크론 케이던스에 따라 실행을 예약합니다. 대신 ID별로 요청 시 하나를 실행합니다.

# List schedules to find the id
curl http://localhost:4111/api/schedules

# Fire one now, out-of-band from its cron
curl -X POST http://localhost:4111/api/schedules/<scheduleId>/run

이 작업은 트리거를 triggerKind: "manual"로 기록하고 nextFireAt을 갱신하지 않으므로 정규 실행 주기는 영향을 받지 않습니다. Studio에는 동일한 일정과 해당 트리거 기록이 표시됩니다. 저장된 ID에는 네임스페이스가 지정되고 URL 인코딩이 적용됩니다. support Agent의 billing/sweep은 fsa_support__billing%2Fsweep이 되므로 ID를 직접 조합하지 말고 목록 응답에서 복사하세요.

등록 및 수명주기

Mastra는 시작 시 선언된 일정을 일정 저장소에 동기화하고 나중에 Agent가 등록될 때마다 다시 동기화합니다. 일정을 선언하는 것만으로도 스케줄러를 시작할 수 있습니다.scheduler: { enabled: true } needed.

동기화는 선언된 각 일정을 저장된 행과 비교하고 변경된 내용만 기록합니다.

• 새 일정 파일은 행을 생성합니다.
• cron 또는 timezone을 편집하면 행이 패치되고 다음 실행 시각이 다시 계산되므로, 편집된 일정은 이전 주기로 실행되지 않습니다.
• 일정 파일을 삭제하거나 이름을 바꾸면 해당 행이 삭제됩니다.
• API를 통해 일정을 일시 중지하면 재배포 후에도 유지됩니다. 동기화 과정에서는 의도적으로 status를 변경하지 않습니다. 동기화는 현재 프로세스에 등록된 Agent에 속한 행만 제거하므로 Agent의 하위 집합을 보유하는 프로세스는 다른 Agent의 일정을 삭제하지 않습니다. Agent가 프로젝트에서 완전히 제거되면 남은 행은 스케줄러가 실행할 Agent를 찾지 못한 다음 실행 시 정리됩니다.

런타임에 mastra.schedules.create(...)로 생성한 일정은 별도의 네임스페이스에 있으며 이 동기화의 영향을 받지 않습니다.

제한

루트 Agent만 해당됩니다.일정은 최상위 Agent에서 선언해야 합니다. subagents/ 아래에 schedules/ 디렉터리가 있으면 빌드 오류가 발생합니다. 하위 Agent는 Mastra 인스턴스에 등록되지 않고 상위 Agent에 연결되므로 스케줄러가 이를 대상으로 해석할 수 없기 때문입니다. 상위 Agent에 일정을 지정하고 하위 Agent에 위임하도록 하세요. 스토리지가 필요합니다.일정은 영구 저장되는 행이므로 인스턴스에 스토리지를 구성해야 합니다. 인메모리 스토어의 행은 재시작 후 유지되지 않습니다. 호스팅.스케줄러는 Mastra 프로세스 내에서 백그라운드 작업자로 실행되므로 해당 프로세스를 활성 상태로 유지하는 호스트가 필요합니다. 장기 실행 노드 서버 및 컨테이너가 작동합니다. 대부분의 서버리스 기능 플랫폼을 포함하여 요청 간 프로세스를 동결하거나 재활용하는 환경에서는 화재가 발생하지 않습니다. 대신 플랫폼 자체 cron을 사용하여 실행 엔드포인트를 호출하세요.

코드 정의 Agent.에이전트 디렉터리의 config.ts가 new Agent({...})를 내보내면 그대로 사용되므로 해당 schedules/ 디렉터리는 경고와 함께 무시됩니다. 이 경우 mastra.schedules.create(...)를 사용하세요.

예

고정된 주간 다이제스트와 할 일이 있을 때만 실행되는 야간 청소라는 두 가지 일정을 가진 지원 Agent입니다.

Scheduled support agent

src/mastra/agents/
└── support/
    ├── config.ts
    ├── instructions.md
    └── schedules/
        ├── weekly-digest.md
        └── billing/
            └── sweep.ts

src/mastra/agents/support/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
})

src/mastra/agents/support/schedules/weekly-digest.md

---
cron: '0 9 * * 1'
timezone: 'America/New_York'
---

Summarize the past week's tickets and post the digest to the team channel.

src/mastra/agents/support/schedules/billing/sweep.ts

import { defineSchedule } from '@mastra/core/agent'

export default defineSchedule({
  cron: '0 3 * * *',
  timezone: 'America/New_York',
  handler: async () => {
    const overdue = await findOverdueInvoices()
    if (overdue.length === 0) return null
    return { prompt: `Draft reminders for ${overdue.length} overdue invoices.` }
  },
})