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

# 일정

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

:::실험적

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

:::

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

> **노트:** 일정을 사용하려면 schedules 도메인을 구현하는 [스토리지](https://mastra.zisheng.pro/ko/docs/storage/overview) 어댑터가 필요합니다. 지원되는 어댑터와 API 동작은 [`mastra.schedules` 레퍼런스](https://mastra.zisheng.pro/ko/reference/schedules/overview)를 참조하세요.

## 빠른 시작

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

```typescript
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 필드에 직접 작성하세요.

```typescript
// 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`](https://www.npmjs.com/package/cron-time-generator)와 같은 사용자 영역 빌더를 사용하고 그 출력을 `cron`에 전달할 수 있습니다.

## 스레드리스 및 스레드 일정

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

### 스레드리스

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

### 스레드

`threadId`를 사용하면 일정이 해당 스레드로 [신호](https://mastra.zisheng.pro/ko/docs/long-running-agents/signals)를 보내므로 Prompt가 Agent의 대화에 추가됩니다. 스레드 기반 일정에는 `threadId`와 함께 `resourceId`가 필요합니다.

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

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

```typescript
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`를 사용하세요. 이 서비스는 일정을 생성, 읽기, 업데이트, 일시 중지, 재개, 수동 실행 및 삭제할 수 있습니다.

```typescript
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` 레퍼런스](https://mastra.zisheng.pro/ko/reference/schedules/overview)를 참조하세요.

### Workflow 일정

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

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

이 방식으로 생성한 Workflow 일정은 `createWorkflow`의 선언적 `schedule` 필드와 별개입니다. 선언적 형식과 Studio 보기는 [예약된 Workflow](https://mastra.zisheng.pro/ko/docs/workflows/scheduled-workflows)를 참조하세요.

### 맞춤 ID

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

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

ID 정규화 규칙과 중복 ID 동작은 [`create(input)` 레퍼런스](https://mastra.zisheng.pro/ko/reference/schedules/overview)를 참조하세요.

### 클라이언트에서

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

## 수명주기 후크

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

```typescript
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`](https://mastra.zisheng.pro/ko/reference/schedules/overview): 일정 생성 및 관리를 위한 API 레퍼런스입니다.
- [신호](https://mastra.zisheng.pro/ko/docs/long-running-agents/signals): 스레드 일정 뒤에 있는 전달 메커니즘입니다.
- [예약된 Workflow](https://mastra.zisheng.pro/ko/docs/workflows/scheduled-workflows): Workflow 정의에 대한 크론 일정을 선언합니다.