---
title: Scheduled
description: 저장해 둔 Agents 자동화를 정해진 주기로 실행하는 방법과, 그 실행이 일회성 생성 Job과 어떻게 다른지 살펴보세요.
---

스케줄은 주기적으로 실행되는, 저장해 둔 Agents 자동화입니다. 지시문, 모델, cron
표현식, 지출 상한으로 이뤄집니다. 발동하면 Sume가 새 스레드에서 Agent로
실행하고 구조화된 실행 영수증을 돌려줍니다.

**핵심은 주기입니다.** *내* 사용자가 무언가를 했을 때 내 백엔드에서 Sume를
호출하고 싶다면 [Format API](/formats)가 맞습니다. 같은 실행 엔진, 같은
영수증이지만 호출마다 주소를 지정하고 입력을 넘길 수 있습니다. 시계 말고는 이
작업을 촉발하는 것이 없을 때 스케줄을 선택하세요.

스케줄은 Agents 대시보드에서 만들거나, 채팅에서 Agent에게 설정해 달라고 하면
됩니다. Developer API는 스케줄을 나열하고, 읽고, 실행을 시작하고, 실행을 관찰할
수 있지만 만들거나 수정할 수는 없습니다.

Scheduled의 나머지 내용은 여기서 연결되는 세 페이지에 있습니다.
[스케줄 만들기](/agents/actions/create),
[실행과 결과](/agents/actions/runs),
[고급: API로 스케줄 실행하기](/agents/actions/api-trigger).

> **Scheduled와 Actions API.** 제품 이름은 Scheduled입니다. HTTP API
> 네임스페이스는 여전히 `/v1/actions`이고, id는 `aut_…`이며, 객체는
> `object: "action"`으로 돌아옵니다. 이 이름들은 안정적이며 바뀌지 않습니다. 이
> 페이지의 "Action"은 스케줄의 통신 규약상 표기라고 읽으세요.

## 스케줄 vs 생성 Job

스케줄 실행은 Job이 아닙니다. `/v1/jobs`에 나타나지 않고,
[Job과 결과](/workflows/jobs-and-results)가 설명하는 Job 라이프사이클을 쓰지도
않습니다.

| | 스케줄 실행 | 생성 Job |
|---|---|---|
| 시작 방법 | cron 스케줄 또는 `POST /v1/actions/{action_id}/runs` | `POST /v1/{family}-1.0/...` |
| 작업 단위 | Agent가 새 스레드에서 실행하는 저장된 지시문 | 모델 호출 한 번 |
| 읽는 곳 | `/v1/action-runs/{run_id}` | `/v1/jobs/{id}` |
| 상태 | `queued`, `processing`, `completed`, `failed`, `canceled`, `skipped` | [Job과 결과](/workflows/jobs-and-results) 참고 |
| 결과 형태 | 출력 스키마에 투영된 `output`과 `artifacts` | Job `result` |
| 중복 정책 | `on_active_run`(`skip` 또는 `reject`) | 없음 |

모델 호출 한 번이 필요하면 생성 Job을 쓰세요. Agent가 주기적으로 수행하는,
때로는 여러 생성에 걸치는 저장된 지시문이 필요하면 스케줄을 쓰세요.

호출할 때마다 작업 자체가 달라지고 저장해 둘 만한 것이 없다면
[Agent Completions](/agents/completions)가 맞습니다. 같은 에이전트이지만 저장
객체가 없고 지시문을 요청마다 제공합니다.

## 스케줄의 구조

`GET /v1/actions`와 `GET /v1/actions/{action_id}`는 다음 형태를 반환합니다.

```json
{
  "id": "aut_...",
  "object": "action",
  "title": "Weekly product teaser",
  "status": "active",
  "trigger_type": "api",
  "api_trigger_enabled": true,
  "cron": null,
  "model": "...",
  "output_schema": null,
  "primary_output_key": null,
  "generation_spend_cap_usd_micros": 1000000,
  "last_run_at": "2026-07-30T09:00:00.000Z",
  "created_at": "2026-07-20T12:00:00.000Z",
  "updated_at": "2026-07-30T09:00:00.000Z",
  "invoke_url": "https://api.sume.com/v1/actions/aut_.../runs"
}
```

| 필드 | 설명 |
|---|---|
| `status` | `active` 또는 `inactive`입니다. `inactive` 스케줄은 API 실행을 거부합니다. |
| `trigger_type` | `cron` 또는 `api`입니다. 생성 시점에 고정됩니다. |
| `api_trigger_enabled` | `true`면 `POST /v1/actions/{action_id}/runs`가 허용됩니다. `cron` 스케줄도 이를 켤 수 있습니다. |
| `cron` | `{ "expr", "timezone", "next_run_at" }`이거나, API 전용인 경우 `null`입니다. |
| `output_schema` | 기본 구조화 출력 바인딩(`{ "name", "strict" }`)이거나, 기본 내장 값을 쓰면 `null`입니다. 대시보드에서 바인딩하세요. [구조화 출력](/formats/structured-output)에서 살펴보세요. |
| `generation_spend_cap_usd_micros` | 실행당 생성 상한이며 USD 마이크로 단위입니다. `null`이면 기본값 $1.00이 적용됩니다. |
| `invoke_url` | 이 스케줄의 실행 엔드포인트입니다. |

`instructions` 텍스트는 공개 형태에서 의도적으로 제외했습니다. 지시문은
대시보드에서 읽고 수정하세요.

## 트리거

트리거 타입은 생성 시점에 정해지며 그 뒤에는 바꿀 수 없습니다.

- **Scheduled**(`cron`) — 기본값입니다. IANA 타임존의 5필드 cron 표현식으로
  실행됩니다.
- **API call**(`api`) — 고급 옵션입니다. 주기가 없고, 서비스가
  `POST /v1/actions/{action_id}/runs`를 호출할 때만 실행됩니다.
  [고급: API로 스케줄 실행하기](/agents/actions/api-trigger)에서 살펴보세요.

cron 스케줄은 주기와 별개로 `api_trigger_enabled`를 켜서 API 실행도 받을 수
있습니다. API 전용 스케줄에는 주기가 없습니다.

## 스케줄이 있는 곳

`https://www.sume.com/agents/scheduled`에서 만들고 관찰하세요. 대시보드 플로는
[스케줄 만들기](/agents/actions/create)에 있습니다.

## 제한

| 제한 | 값 |
|---|---|
| `input` 속성 수 | 64 |
| `input` 크기 | UTF-8 기준 2097152바이트(2 MiB) |
| 기본 생성 지출 상한 | 설정하지 않으면 $1.00(`1000000` USD 마이크로) |
| 실행당 지출 상한 재정의 | `min(request, schedule cap)`으로 제한됩니다. 낮출 수는 있어도 올릴 수는 없습니다 |
| `Idempotency-Key` 길이 | 1~255자 |
| 목록 엔드포인트의 `limit` | 1~100, 기본 50 |

## 스케줄이 아직 지원하지 않는 것

설계하기 전에 다음 공백을 알아 두세요.

- **서명 시크릿은 아직 셀프서브가 아닙니다.** `communication.webhook_url`은
  `api.dev.sume.com`과 `api.sume.com`에서 받아서 검증·저장·전달됩니다. 계약은
  [Run 웹훅](/agents/run-webhooks)에 문서화돼 있습니다.
- **이벤트 엔드포인트가 없습니다.** 실행 영수증의 `events_url`은 항상
  `null`입니다. 실행 라이프사이클 이벤트는 API로 노출되지 않습니다.
  `status_url`과 `result_url`을 사용하세요.
- **페이지네이션이 없습니다.** 목록 응답은 항상 `has_more: false`와
  `next_cursor: null`을 반환합니다.
- **MCP 도구도 CLI 명령어도 없습니다.** 스케줄은 [MCP](/mcp)나 [CLI](/cli)로
  노출되지 않습니다.
- **쓰기 엔드포인트가 없습니다.** Developer API로는 스케줄을 만들거나 수정하거나
  삭제할 수 없습니다.

## 다음

- [스케줄 만들기](/agents/actions/create)
- [실행과 결과](/agents/actions/runs)
- [안전한 자동화](/agents/safe-automation)
- [고급: API로 스케줄 실행하기](/agents/actions/api-trigger)
- [Run 웹훅](/agents/run-webhooks)