9.7. 작업 스케줄링¶

작업 스케줄링을 사용하면 cron 표현식, 고정 인터벌, 또는 단일 일회성 실행으로 컨테이너 에이전트를 자동으로 실행할 수 있습니다. 예약된 작업은 Squad UI와 독립적으로 실행되며, 앱이 시스템 트레이로 최소화된 상태에서도 백그라운드에서 실행됩니다.

스케줄 유형¶

유형	실행 시점	예시 사용 사례
Cron	cron 표현식으로 정의된 특정 시간	평일 오전 9시에 일일 보고서
인터벌	N 밀리초마다 반복	5분마다 모니터링 확인
일회성	특정 ISO 타임스탬프에 한 번	예약된 유지 관리 시간에 마이그레이션 실행

예약 작업 생성¶

설정 UI를 통해¶

설정 > 컨테이너 > 스케줄로 이동합니다.
새 스케줄을 클릭합니다.

스케줄 설정을 입력합니다:

필드	설명
이름	사람이 읽기 쉬운 레이블
그룹	실행할 컨테이너 그룹 네임스페이스
프롬프트	에이전트에 대한 작업 설명/지침
스케줄 유형	Cron, 인터벌, 또는 일회성
스케줄 값	Cron 표현식, ms 단위 인터벌, 또는 ISO 타임스탬프
이미지	컨테이너 이미지 (기본값: `aigo-agent-runner:latest`)
타임아웃	최대 실행 시간 (초, 0 = 제한 없음, 기본값: 300)
컨텍스트 모드	`group` (세션 재사용) 또는 `isolated` (매번 새 세션)
활성화	스케줄 일시 중지/재개 토글

생성을 클릭합니다.

Management API를 통해¶

curl -X POST http://localhost:55765/api/v1/container/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "일일 요약",
    "group": "reporting",
    "prompt": "오늘의 주요 이벤트를 요약하고 /workspace/reports/daily.md에 보고서를 작성하세요",
    "schedule": {
      "type": "cron",
      "value": "0 9 * * 1-5"
    },
    "containerConfig": {
      "timeoutSecs": 600
    },
    "contextMode": "isolated",
    "enabled": true
  }'

Cron 표현식¶

Backend.AI GO는 표준 5필드 cron 표현식을 사용합니다:

┌───────── 분 (0-59)
│ ┌───────── 시 (0-23)
│ │ ┌───────── 일 (1-31)
│ │ │ ┌───────── 월 (1-12)
│ │ │ │ ┌───────── 요일 (0-7, 일요일 = 0 또는 7)
│ │ │ │ │
* * * * *

일반적인 예시¶

표현식	스케줄
`0 9 * * 1-5`	평일 오전 9:00
`0 /4 * *`	4시간마다
`30 8 * * 0`	일요일 오전 8:30
`0 0 1 * *`	매월 1일 자정
`/15 * * *`	15분마다

인터벌 스케줄¶

인터벌 스케줄은 N 밀리초마다 실행됩니다. 최소 인터벌은 10,000ms(10초)입니다.

# 5분마다 실행 (300,000 ms)
curl -X POST http://localhost:55765/api/v1/container/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "상태 모니터",
    "group": "monitoring",
    "prompt": "시스템 상태를 확인하고 /workspace/health.log에 상태 줄을 추가하세요",
    "schedule": {
      "type": "interval",
      "value": 300000
    },
    "enabled": true
  }'

드리프트 방지

스케줄러는 실제 실행 시간이 아닌 예약된 시간에서 next_run을 계산합니다. 이를 통해 스케줄 드리프트를 방지합니다 — 작업이 30초가 걸리더라도 다음 실행은 예상 시간에 이루어집니다.

일회성 스케줄¶

일회성 스케줄은 특정 UTC 타임스탬프에 한 번 실행되며 자동으로 완료로 표시됩니다:

curl -X POST http://localhost:55765/api/v1/container/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "데이터베이스 마이그레이션",
    "group": "maintenance",
    "prompt": "/workspace/scripts/migrate.sh의 데이터베이스 마이그레이션 스크립트를 실행하세요",
    "schedule": {
      "type": "once",
      "value": "2026-04-01T02:00:00Z"
    },
    "containerConfig": {
      "timeoutSecs": 3600
    },
    "enabled": true
  }'

컨텍스트 모드¶

컨텍스트 모드는 실행 간에 컨테이너 세션이 어떻게 관리되는지 결정합니다:

모드	동작	최적 사용 사례
`isolated`	모든 실행에 대해 새 세션 (기본값)	독립 작업, 보고서
`group`	실행 간에 그룹 세션 재사용	상태 기반 워크플로우, 모니터링

실행 로그 확인¶

Management API를 통해¶

curl "http://localhost:55765/api/v1/container/schedules/{id}/logs?limit=20"

응답:

[
  {
    "id": "run-abc123",
    "scheduleId": "sched-xyz789",
    "startedAt": "2026-03-15T09:00:00Z",
    "finishedAt": "2026-03-15T09:02:15Z",
    "status": "completed",
    "exitCode": 0,
    "output": "보고서가 /workspace/reports/daily.md에 작성되었습니다"
  }
]

실행 상태 값¶

상태	설명
`pending`	예약됨, 시작 대기 중
`running`	현재 실행 중
`completed`	성공적으로 완료됨 (종료 코드 0)
`failed`	오류와 함께 완료됨
`timeout`	설정된 타임아웃 초과

문제 해결¶

예약된 작업이 실행되지 않음¶

스케줄의 enabled가 true인지 확인
컨테이너 런타임이 사용 가능한지 확인

스케줄의 실행 로그에서 오류 확인:

curl http://localhost:55765/api/v1/container/schedules/{id}/logs

Cron 작업이 잘못된 시간에 실행됨¶

시스템 시간대가 올바르게 설정되어 있는지 확인
crontab.guru와 같은 cron 표현식 검사기를 사용하여 표현식 확인
cron은 UTC가 아닌 로컬 시스템 시간을 사용함을 기억하세요