Scheduled

이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.

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

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

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

Scheduled의 나머지 내용은 여기서 연결되는 세 페이지에 있습니다. 스케줄 만들기, 실행과 결과, 고급: API로 스케줄 실행하기.

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

스케줄 vs 생성 Job

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

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

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

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

스케줄의 구조

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

필드설명
statusactive 또는 inactive입니다. inactive 스케줄은 API 실행을 거부합니다.
trigger_typecron 또는 api입니다. 생성 시점에 고정됩니다.
api_trigger_enabledtrue면 POST /v1/actions/{action_id}/runs가 허용됩니다. cron 스케줄도 이를 켤 수 있습니다.
cron{ "expr", "timezone", "next_run_at" }이거나, API 전용인 경우 null입니다.
output_schema기본 구조화 출력 바인딩({ "name", "strict" })이거나, 기본 내장 값을 쓰면 null입니다. 대시보드에서 바인딩하세요. 구조화 출력에서 살펴보세요.
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로 스케줄 실행하기에서 살펴보세요.

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

스케줄이 있는 곳

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

제한

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

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

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

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

다음