11.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": "Daily Summary",
    "group": "reporting",
    "prompt": "Summarize the key events from today and write a report to /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분마다

시간대

Cron 스케줄은 시스템에 설정된 시간대를 사용합니다. TZ 환경 변수는 컨테이너에 자동으로 전달됩니다.

인터벌 스케줄¶

인터벌 스케줄은 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": "Health Monitor",
    "group": "monitoring",
    "prompt": "Check system health and append a status line to /workspace/health.log",
    "schedule": {
      "type": "interval",
      "value": 300000
    },
    "enabled": true
  }'

드리프트 방지

스케줄러는 실제 실행 시각이 아니라 예약된 시각을 기준으로 next_run을 계산하므로 스케줄 드리프트가 생기지 않습니다. 작업이 30초 걸리더라도 다음 실행은 30초 밀리지 않고 예상 시각에 시작됩니다.

일회성 스케줄¶

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

curl -X POST http://localhost:55765/api/v1/container/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Database Migration",
    "group": "maintenance",
    "prompt": "Run the database migration script in /workspace/scripts/migrate.sh",
    "schedule": {
      "type": "once",
      "value": "2026-04-01T02:00:00Z"
    },
    "containerConfig": {
      "timeoutSecs": 3600
    },
    "enabled": true
  }'

컨텍스트 모드¶

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

모드	동작	적합한 용도
`isolated`	매 실행마다 새 세션 (기본값)	독립적인 작업, 보고서 생성
`group`	실행 간에 그룹 세션 재사용	상태 유지 워크플로우, 모니터링

isolated 모드에서는 매 실행이 깨끗한 .claude/ 세션 디렉터리로 시작합니다. group 모드에서는 세션이 실행 사이에도 유지되므로 에이전트가 대화 기록과 메모리를 그대로 갖고 갑니다.

스케줄 관리¶

스케줄 목록 조회¶

curl http://localhost:55765/api/v1/container/schedules

스케줄 조회¶

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

스케줄 수정¶

curl -X PUT http://localhost:55765/api/v1/container/schedules/{id} \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

스케줄 삭제¶

curl -X DELETE http://localhost:55765/api/v1/container/schedules/{id}

스케줄 일시 중지¶

스케줄을 삭제하지 않고 일시 중지하려면 enabled: false로 설정합니다:

curl -X PUT http://localhost:55765/api/v1/container/schedules/{id} \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

실행 로그 확인¶

스케줄이 실행될 때마다 실행 로그 항목이 생성됩니다.

설정 UI를 통해¶

설정 > 컨테이너 > 스케줄로 이동합니다.
스케줄 이름을 클릭합니다.
실행 로그를 클릭해 실행 기록을 확인합니다.

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": "Report written to /workspace/reports/daily.md"
  }
]

실행 상태 값¶

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

스케줄의 컨테이너 설정¶

스케줄마다 컨테이너 관련 설정을 지정할 수 있습니다:

{
  "containerConfig": {
    "image": "aigo-agent-runner:latest",
    "timeoutSecs": 300,
    "env": ["MY_CUSTOM_VAR=value"]
  }
}

필드	기본값	설명
`image`	`aigo-agent-runner:latest`	사용할 컨테이너 이미지
`timeoutSecs`	`300`	최대 실행 시간 (초, 0 = 무제한)
`env`	`[]`	추가 환경 변수

환경 변수 보안

env에는 민감하지 않은 환경 변수만 전달해야 합니다. API 키와 자격증명은 항상 자격증명 프록시를 통해 전달하세요.

문제 해결¶

스케줄이 실행되지 않음¶

스케줄의 enabled가 true인지 확인
스케줄러 틱 간격 확인 (스케줄러는 15초마다 검사합니다)
컨테이너 런타임이 사용 가능한지 확인

스케줄이 실행되지만 즉시 실패함¶

실행 로그에서 종료 코드와 출력 확인
컨테이너 이미지가 존재하는지 확인: 설정 > 컨테이너 > 이미지 상태
감사 로그에서 마운트 또는 권한 오류 검토

Cron 스케줄이 잘못된 시간에 실행됨¶

시스템 시간대가 올바르게 설정되어 있는지 확인
온라인 cron 표현식 검사기로 표현식 검증
cron은 로컬 시스템 시간을 사용하고 TZ 환경 변수가 그대로 전달된다는 점에 유의

인터벌 스케줄에 드리프트가 발생함¶

스케줄러는 드리프트 방지 로직을 사용합니다 (다음 실행 = 실제 실행 시각이 아닌 예약된 시각)
그래도 드리프트가 보이면 시스템 시계 변경이나 과도한 시스템 부하가 있는지 확인