일정

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

:::실험적

이 기능은 베타 버전입니다. API가 안정될 때까지 주요 버전 변경 없이 주요 변경 사항이 발생할 수 있습니다.

:::

일정은 cron 주기에 따라 Agent를 실행합니다. 실행될 때마다 Mastra는 스레드에 신호로, 또는 스레드 없는 agent.generate() 실행으로 Agent에 Prompt를 보냅니다. 일일 요약, 주기적 확인 또는 대화에 예약된 알림을 보내는 등 반복적인 Agent 작업에 일정을 사용하세요. 일정은 영속화되므로 재시작과 재배포 후에도 유지됩니다. 런타임에서는 표준 생성, 읽기, 업데이트 및 삭제(CRUD) 인터페이스인 mastra.schedules를 통해 관리하세요. 동일한 인터페이스로 Workflow 일정도 관리할 수 있습니다(Workflow를 예약하려면 agentId 대신 workflowId를 전달하세요).

노트

일정을 사용하려면 schedules 도메인을 구현하는 스토리지 어댑터가 필요합니다. 지원되는 어댑터와 API 동작은 mastra.schedules 레퍼런스를 참조하세요.

빠른 시작

다음 일정은 매시간 pinger Agent를 실행합니다. 스레드가 없으므로 각 실행은 독립적인 agent.generate() 실행입니다.

src/mastra/schedules.ts

import { Mastra } from '@mastra/core'
import { Agent } from '@mastra/core/agent'
import { LibSQLStore } from '@mastra/libsql'

const pinger = new Agent({
  id: 'pinger',
  name: 'Pinger',
  instructions: 'Report the current system status in one sentence.',
  model: 'openai/gpt-5.6-sol',
})

const mastra = new Mastra({
  agents: { pinger },
  storage: new LibSQLStore({ id: 'mastra-storage', url: 'file:./mastra.db' }),
})

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

Mastra는 일정이 처음 생성될 때 스케줄러를 시작한 다음 지정한 cron에서 Agent를 실행합니다.

운율

cron 표현식으로 실행을 예약합니다. cron 필드는 표준 5, 6 또는 7부분 cron 표현식을 허용하며 일정을 생성하거나 업데이트할 때 검증됩니다. croner 별칭도 사용할 수 있습니다. 예를 들면 @hourly, @daily, @weekly, @monthly, @midnight가 있습니다. 요일과 시간 조합은 cron 필드에 직접 작성하세요.

// Every weekday at 9am
await mastra.schedules.create({
  agentId: 'pinger',
  cron: '0 9 * * 1-5',
  prompt: 'Start-of-day check.',
})

실행 시간이 호스트의 로캘에 좌우되지 않도록 timezone을 IANA 시간대(예: America/New_York)로 설정하세요. 생략하면 cron은 호스트의 로컬 시간대를 기준으로 해석됩니다. 더 읽기 쉬운 cron 구성을 위해 cron-time-generator와 같은 사용자 영역 빌더를 사용하고 그 출력을 cron에 전달할 수 있습니다.

스레드리스 및 스레드 일정

Agent 일정은 두 가지 모드 중 하나로 실행되며, 통과 여부에 따라 결정됩니다.threadId.

스레드리스

threadId가 없으면 각 실행은 독립적인 agent.generate() 실행입니다. 대화 스레드에는 아무것도 기록되지 않습니다. 가장 간단한 모드이며 대화 컨텍스트가 필요하지 않은 상태 확인, 보고서 및 기타 작업에 적합합니다.

스레드

threadId를 사용하면 일정이 해당 스레드로 신호를 보내므로 Prompt가 Agent의 대화에 추가됩니다. 스레드 기반 일정에는 threadId와 함께 resourceId가 필요합니다.

src/mastra/schedules.ts

await mastra.schedules.create({
  agentId: 'pinger',
  cron: '0 9 * * *',
  prompt: 'Summarize anything new since yesterday.',
  threadId: 'thread-123',
  resourceId: 'user-456',
})

스레드 기반 일정에서는 신호 유형, XML 태그, 태그 속성, 활성 또는 유휴 상태에서의 전달 동작 등 신호의 작동 방식을 제어하는 추가 필드를 사용할 수 있습니다. 이 옵션은 agent.sendSignal()이 허용하는 옵션을 반영하며, 일정과 함께 영속화될 수 있도록 JSON으로 직렬화할 수 있어야 합니다. 이 필드에는 threadId가 필요합니다. 전체 스레드 기반 입력 구조는 Agent 일정 입력 레퍼런스를 참조하세요.

await mastra.schedules.create({
  agentId: 'pinger',
  cron: '0 9 * * *',
  prompt: 'Summarize anything new since yesterday.',
  threadId: 'thread-123',
  resourceId: 'user-456',
  tagName: 'check-in', // renders as <check-in>…</check-in>
  attributes: { source: 'cron' },
  ifActive: { behavior: 'discard' }, // skip if the thread is mid-stream
  ifIdle: {
    behavior: 'wake', // wake the agent if the thread is idle
    streamOptions: { requestContext: { locale: 'en-US' } },
  },
})

providerOptions모든 실행 시 신호 페이로드에 병합되어 스레드 및 스레드 없는 일정 모두에 적용됩니다.

일정 관리

모든 일정 작업에는 mastra.schedules를 사용하세요. 이 서비스는 일정을 생성, 읽기, 업데이트, 일시 중지, 재개, 수동 실행 및 삭제할 수 있습니다.

const schedule = await mastra.schedules.create({
  agentId: 'pinger',
  cron: '0 * * * *',
  prompt: 'Status check.',
})

await mastra.schedules.pause(schedule.id)
await mastra.schedules.resume(schedule.id)
await mastra.schedules.run(schedule.id) // Fire once now, off-schedule

pause와 resume은 영속적으로 적용됩니다. run은 주기에 영향을 주지 않고 일정을 즉시 한 번 실행합니다. 전체 메서드 목록, 필터 및 패치 필드는 mastra.schedules 레퍼런스를 참조하세요.

Workflow 일정

동일한 서비스로 Agent 대신 Workflow를 실행하는 일정을 만들 수 있습니다. workflowId와 Workflow 형식의 필드를 전달하세요.

await mastra.schedules.create({
  workflowId: 'daily-report',
  cron: '0 9 * * *',
  inputData: { userId: 'system' },
})

이 방식으로 생성한 Workflow 일정은 createWorkflow의 선언적 schedule 필드와 별개입니다. 선언적 형식과 Studio 보기는 예약된 Workflow를 참조하세요.

맞춤 ID

나중에 조회, 업데이트 또는 삭제할 때 사용할 예측 가능한 핸들이 필요하면 id를 전달하세요.

await mastra.schedules.create({
  id: 'nightly-summary',
  agentId: 'pinger',
  cron: '0 9 * * *',
  prompt: 'Summarize anything new since yesterday.',
})

ID 정규화 규칙과 중복 ID 동작은 create(input) 레퍼런스를 참조하세요.

클라이언트에서

동일한 작업은 /api/schedules 경로를 통해 @mastra/client-js에서도 사용할 수 있으므로 별도 프로세스나 UI에서 일정을 관리할 수 있습니다. 클라이언트 메서드 목록은 client-js Agent 일정 레퍼런스를 참조하세요.

수명주기 후크

후크를 사용하면 Agent 일정 수명 주기의 주요 지점에서 코드를 실행할 수 있습니다. 예를 들어 실행 시간 매개변수를 계산하거나 결과에 반응할 수 있습니다. Mastra 생성자의 schedules 아래에 구성하세요. 후크는 모든 Agent 일정에 실행되는 하나의 단일 번들이며, 각 후크 컨텍스트에는 실행 대상 agentId가 포함됩니다. Agent별 동작이 필요하면 이를 기준으로 분기하세요. 후크는 Mastra 수준에 있으므로 코드로 정의한 Agent와 저장된 Agent 모두에 적용됩니다.

src/mastra/index.ts

const mastra = new Mastra({
  agents: { pinger },
  storage: new LibSQLStore({ id: 'mastra-storage', url: 'file:./mastra.db' }),
  schedules: {
    prepare: async ({ agentId, schedule, trigger }) => {
      // Return overrides, null to skip this fire, or undefined for defaults
      return { prompt: `Status as of ${trigger.firedAt.toISOString()}` }
    },
    onFinish: async ({ agentId, outcome, runId }) => {
      // Runs on any non-error, non-abort outcome
    },
    onError: async ({ agentId, phase, error }) => {
      // Runs when prepare, the signal, or the agent run threw
    },
    onAbort: async ({ agentId, runId }) => {
      // Runs when the run was aborted mid-stream
    },
  },
})

후크는 다음과 같습니다.

• prepare: 실행 전에 호출됩니다. prompt 또는 threadId 같은 실행 시간 매개변수를 재정의하는 객체, 실행을 건너뛰는 null, 저장된 기본값을 사용하는 undefined를 반환합니다.
• onFinish: 오류가 없고 중단되지 않은 최종 상태에 도달한 트리거마다 한 번 실행됩니다.
• onError: prepare 또는 신호가 실패한 후 실행됩니다. Agent 실행이 실패할 때도 실행됩니다.
• onAbort: 실행이 도중에 중단되었을 때 실행됩니다. 모든 후크 컨텍스트에는 schedule 및 trigger와 함께 agentId(일정이 실행한 Agent)가 포함됩니다. 후크 예외가 포착되어 기록됩니다. 작업자를 다시 라우팅하거나 다른 후크를 유발하지 않습니다.

관련된

• mastra.schedules: 일정 생성 및 관리를 위한 API 레퍼런스입니다.
• 신호: 스레드 일정 뒤에 있는 전달 메커니즘입니다.
• 예약된 Workflow: Workflow 정의에 대한 크론 일정을 선언합니다.