AI 영상 에이전트 스케줄 실행: cron, API 트리거, 영수증

Sume 스케줄은 정해진 주기로 실행되는, 저장된 에이전트 자동화입니다. 지시문, 모델, cron 표현식, 지출 상한으로 이뤄집니다. 스케줄이 발동하면 Sume가 새 스레드에서 에이전트로 실행하고 구조화된 실행 영수증을 돌려줍니다. 스케줄은 에이전트 대시보드에서 만듭니다. Developer API로는 스케줄을 나열하고 읽고, 실행을 시작하고 모니터링할 수 있지만, 스케줄을 만들거나 수정할 수는 없습니다.

아래 내용은 모두 Scheduled 문서와 그 하위 페이지인 스케줄 만들기, 실행과 결과, API 트리거에서 가져왔습니다.

주기적인 에이전트 실행은 어떻게 만드나요?

Scheduled를 열고 Create 컨트롤을 쓰거나, 채팅에서 에이전트에게 스케줄을 설정해 달라고 요청하세요. 제품 이름은 Scheduled이지만 API 네임스페이스는 /v1/actions이고, id는 aut_… 형태이며, 객체는 object: "action"으로 돌아옵니다. 대시보드에서는 다음 순서로 만듭니다.

• 지시문을 쓰고 모델을 고르세요. 지시문이 비어 있으면 실행할 수 없습니다.
• 주기를 설정하세요. IANA 타임존 기준의 5필드 cron 표현식을 씁니다. 시간별, 일별, 주별 프리셋을 고르면 표현식이 자동으로 작성됩니다.
• 생성 지출 상한을 설정하세요. 설정하지 않으면 실제 기본값은 실행당 $1.00입니다. 호출자는 generation_spend_cap_usd로 한 번의 실행에 한해 상한을 낮출 수 있지만, 올릴 수는 없습니다.
• 필요하면 출력 스키마를 바인딩하세요. 기본적으로 output은 sume/action-run-output/v1에 투영되며, 형태는 { text, images[], videos[], audio[], files[] }입니다.
• 스케줄을 활성(Active)으로 설정하세요. 비활성(Inactive)인 동안 API 실행은 409 action_inactive로 거부됩니다.

스케줄에는 cron과 API 트리거 중 무엇을 써야 하나요?

트리거 타입은 생성 시점에 정해지며 바꿀 수 없습니다. cron이 기본값이며 주기에 맞춰 실행됩니다. api는 주기가 없는 고급 옵션으로, 직접 운영하는 서비스가 POST /v1/actions/{action_id}/runs를 호출할 때만 스케줄이 실행됩니다. cron 스케줄도 api_trigger_enabled를 켜면 주기와 함께 API 실행을 받을 수 있지만, API 전용 스케줄에는 나중에도 주기가 생기지 않습니다.

내 사용자가 무언가를 했을 때 백엔드에서 Sume를 호출해야 한다면, 문서는 대신 Format API를 권합니다. 실행 엔진과 영수증은 같고, 호출마다 입력을 담아 대상을 지정합니다. Sume Format이란?을 참고하세요.

스케줄 실행은 생성 Job과 어떻게 다른가요?

스케줄 실행은 Job이 아닙니다. /v1/jobs에 나타나지 않으며 Job 라이프사이클도 쓰지 않습니다.

직접 운영하는 서비스에서 실행은 어떻게 시작하나요?

스케줄이 active 상태이고 api_trigger_enabled: true여야 하며, 키에는 actions:read와 actions:write가 있어야 합니다. API 호출 트리거가 나오기 전에 만든 키에는 이 스코프가 없어 403 insufficient_scope로 실패하므로, API 키에서 새 키를 만드세요. 서비스 계정 키로는 Action 실행을 만들 수 없습니다.

접수된 실행은 object가 action.run인 영수증과 함께 202를 반환합니다. input은 지시문이 아니라 데이터로 에이전트에 전달되며, 최대 64개 속성, 2 MiB까지입니다. 1–255자의 Idempotency-Key를 보내세요. 같은 페이로드로 다시 보내면 원래 영수증이 idempotency_hit: true와 함께 200으로 돌아오고, 다른 페이로드로 보내면 409 idempotency_conflict가 반환됩니다. {handle}/{slug} 버니티 경로도 동작하지만, 저장할 때는 절대 바뀌지 않는 불투명 aut_… id를 쓰세요.

curl -sS -X POST "https://api.sume.com/v1/actions/$ACTION_ID/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"input":{"product_name":"Aurora Headphones"}}'

이미 진행 중인 실행이 있으면 어떻게 되나요?

한 스케줄에서 동시에 활성인 실행은 하나뿐이며, 두 번째 요청을 어떻게 처리할지는 on_active_run이 정합니다. 200이 작업이 끝났다는 뜻은 아니므로 영수증의 status로 분기하세요.

• skip(기본값)은 status: "skipped", skip_reason: "previous_run_active"와 함께 200을 반환합니다. 실행 행은 기록됩니다.
• reject는 409 action_run_in_progress를 반환하며, 실행은 기록되지 않습니다.

결과는 어떻게 받나요?

GET /v1/action-runs/{run_id}/status를 폴링하고 next_action으로 분기하세요. 실행이 queued나 processing인 동안은 poll_status, 건너뛴 뒤에는 retry_later, 종료되면 none입니다. GET /v1/action-runs/{run_id}/result는 실행이 종료됐을 때만 전체 영수증을 반환하고, 그 전에는 409 run_not_completed를 반환합니다. 완료된 실행은 output과 artifacts를 채우며, primary_output_url은 primary_output_key에 대응하는 해석된 URL입니다.

usage.billable_amount_usd_micros는 생성 지출만 셉니다. 별도의 Agent 지갑에서 과금되는 에이전트 자체의 LLM 턴은 제외되며, 권위 있는 과금 기록은 여전히 GET /v1/usage입니다. POST /v1/action-runs/{run_id}/cancel에는 actions:write가 필요하며, 멱등입니다. 폴링을 건너뛰려면 communication.webhook_url을 설정해 종료 영수증이 담긴 서명된 POST를 한 번 받으세요. 영상 실행을 위한 서명된 웹훅을 참고하세요.

Scheduled가 아직 지원하지 않는 것은 무엇인가요?

문서에 나온 미지원 항목은 다음과 같습니다.

• 서명 시크릿은 아직 셀프서브가 아닙니다.
• 이벤트 엔드포인트가 없습니다. 실행 영수증의 events_url은 항상 null입니다.
• 스케줄용 MCP 도구도 CLI 명령어도 없습니다.
• 쓰기 엔드포인트가 없습니다. Developer API로는 스케줄을 만들거나 수정하거나 삭제할 수 없습니다.
• 팀 워크스페이스가 소유한 스케줄은 아직 공개 API로 접근할 수 없습니다.