Deep Agent Builder 스케줄링
에이전트 실행을 정해진 시각에 반복하려면 스케줄을 등록합니다. 이 페이지는 스케줄을 만들거나 바꾼 뒤 다음 실행 시각과 최근 실행 상태를 확인하고, 권한이나 검증 오류가 났을 때 다음 판단을 내리는 방법을 설명합니다. 화면의 실제 메뉴와 버튼은 제품 환경에서 확인해야 하며, 아래 내용은 현재 스케줄 API와 데이터 계약을 기준으로 합니다.
시작하기 전에 확인할 것
스케줄을 만들려면 대상 에이전트가 있고, 스케줄 생성과 에이전트 수정에 필요한 권한이 있어야 합니다. 목록을 읽으려면 스케줄 조회 권한이 필요하고, 삭제에는 스케줄 삭제 권한이 필요합니다. 실제 발화 권한이나 실행 가능 여부는 별도의 runner와 에이전트 설정에서 확인해야 하며, 이 페이지의 스케줄 관리 권한만으로 단정하지 않습니다.
실행 메시지는 스케줄이 발화할 때 전달할 내용입니다. 실제 고객 자료, 인증값, 호스트 주소를 넣지 말고 비식별 테스트 메시지로 먼저 확인합니다. 반복 실행이 업무에 영향을 주는 경우에는 활성화 전에 다음 실행 시각과 대상 에이전트를 다시 검토합니다.
스케줄이 저장하는 정보
스케줄은 Service DB의 agent_run_schedules에 저장되고, 스케줄이 발화해 만든 run은 Thread DB에 저장됩니다. 따라서 스케줄이 목록에 보인다는 사실과 실제 run이 생성됐다는 사실은 별도로 확인해야 합니다.
| 항목 | 의미 |
|---|---|
| cron_expression | 반복 실행 시각을 나타내는 5필드 cron 표현식 |
| timezone | cron을 해석하는 IANA 시간대. 기본값은 UTC |
| execution_message | 발화할 때 전달할 메시지. trim 후 1자에서 10,000자 사이 |
| is_enabled | 스케줄 활성화 여부. 기본값은 true |
| next_run_at | 다음 실행 예정 시각. 비활성 스케줄에서는 null |
| last_run_at, last_run_id, last_status | 최근 발화 시각, 연결된 run, 최근 상태 |
| run_count | 발화 횟수 |
목록 응답에는 생성·수정 시각도 포함됩니다. 에이전트별 목록은 항목과 전체 개수, 활성 개수를 반환하고, 사용자 전체 목록은 각 항목에 공개 에이전트 식별자와 에이전트 이름을 함께 반환합니다. 두 목록 API에는 페이지네이션이 없습니다.
스케줄 만들기
- 수행 위치를 대상 에이전트의 스케줄 관리 화면으로 정합니다. 실제 메뉴와 버튼 이름은 촬영 전 확인합니다.
- 5필드 cron 표현식, 시간대, 실행 메시지를 준비합니다. 처음에는 현재 환경에서 확인한 시간대와 짧은 비식별 메시지를 사용합니다.
- 스케줄을 저장하고 생성 결과를 확인합니다. API 생성 요청은 스케줄 조회용 에이전트 공개 식별자와 함께 cron 표현식, 시간대, 실행 메시지, 활성화 여부를 받으며 성공 상태는 201입니다.
- 같은 목록을 다시 조회해 대상 에이전트, 활성화 여부, next_run_at을 확인합니다.
- next_run_at이 의도한 시간대와 맞는지 확인한 뒤, 발화 후 last_run_id와 last_status를 다시 조회합니다.
cron 표현식은 정확히 5개 필드여야 하고 parser가 해석할 수 있어야 합니다. 생성하거나 실제 cron 값을 바꿀 때 minute 필드는 단일 ASCII 정수여야 합니다. 별표, step, range, list 형태를 minute 필드에 사용하면 sub-hourly schedule not allowed 검증 오류가 발생합니다. 이미 저장된 레거시 sub-hourly 값을 같은 값으로 다시 보내는 변경 없는 요청은 예외적으로 허용될 수 있습니다.
기존 스케줄 바꾸기
PATCH는 cron 표현식, 시간대, 실행 메시지, 활성화 여부를 선택적으로 받습니다. is_enabled만 바꾸는 요청은 방향에 따라 별도 권한을 검사합니다. is_enabled를 true로 바꾸면 활성화 권한, false로 바꾸면 비활성화 권한이 필요합니다. 다른 필드만 바꾸면 일반 수정 권한을 확인하고, toggle과 다른 필드를 함께 바꾸면 일반 수정 권한과 해당 활성화 권한을 함께 확인합니다.
cron 표현식, 시간대, 활성화 여부가 실제로 바뀌면 next_run_at을 다시 계산합니다. 실행 메시지만 바꾸거나 이전과 같은 값을 다시 보내면 이미 정해진 due tick을 밀지 않도록 기존 next_run_at을 유지합니다. 변경 후에는 저장 성공만 확인하지 말고 다음 실행 시각과 다음 발화 결과를 다시 조회합니다.
시간대는 IANA 식별자여야 합니다. 절대경로 형태, ..가 포함된 값, 비정규 키는 검증 오류가 됩니다. 기존 저장값이 잘못돼도 전체 목록 조회가 실패하는 대신 해당 항목의 next_run_at이 null로 표시될 수 있습니다.
비활성화와 삭제
일시적으로 실행을 멈추려면 스케줄을 비활성화하고 is_enabled와 next_run_at을 확인합니다. 삭제는 비활성화와 다른 파괴적 작업으로 취급하고, 필요한 설정과 마지막 실행 정보를 먼저 기록합니다. 삭제 후 복원 동작은 이 계약에서 정의하지 않으므로 복원할 수 있다고 가정하지 않습니다. 삭제 성공 상태는 204입니다.
보관된 에이전트의 스케줄은 목록 조회, 수정, 삭제가 정상적으로 해소될 수 있습니다. 다만 보관된 에이전트의 스케줄을 다시 활성화할 수는 없습니다. 보관된 에이전트에 대한 새 스케줄 생성은 찾을 수 없음으로 처리됩니다.
에이전트를 삭제하면 연결된 활성 스케줄은 같은 Service DB 트랜잭션에서 비활성화되고 next_run_at은 null이 되며 last_status는 agent_not_found로 바뀝니다. 이 상태는 스케줄 정의가 더 이상 실행되지 않도록 정리된 것을 뜻하지만, 과거에 생성된 run의 존재나 보존까지 없앴다고 해석하지 마세요.
발화 후 결과 확인
스케줄을 저장한 뒤에는 다음 실행 시각만 보지 말고 실제 run을 확인합니다.
- 스케줄 목록에서 next_run_at을 확인합니다.
- 예정 시각이 지난 뒤 last_run_at, last_run_id, last_status, run_count를 다시 조회합니다.
- 연결된 run에서 현재 상태와 결과 또는 오류를 확인합니다. 상태 이름과 종료 이유는 실제 run 응답이 제공하는 값으로 판정하고, 스케줄 표에 없는 상태를 성공이나 완료로 해석하지 않습니다.
- 스케줄이 계속 활성 상태인지, 다음 next_run_at이 새로 계산됐는지 확인합니다.
스케줄 API는 등록과 관리 경계를 담당합니다. 실제 발화와 run 생성은 별도의 runner 계약에 속하므로, 스케줄 생성 응답만으로 에이전트가 실행됐다고 판단하지 않습니다.
대표 실패와 다음 판단
| 증상 | 먼저 확인할 것 | 다음 판단 |
|---|---|---|
| 스케줄 생성이 거부됨 | 생성 권한, 에이전트 수정 권한, cron 5필드, minute 필드 | 권한 오류인지 sub-hourly 검증 오류인지 나눠 확인합니다. |
| next_run_at이 null임 | is_enabled, 시간대 형식, 기존 cron 값의 유효성 | 비활성 상태인지 저장값이 잘못됐는지 확인하고, 임의로 시간을 계산하지 않습니다. |
| 실행 메시지만 바꿨는데 시각이 달라짐 | PATCH에 cron, 시간대, 활성화 여부가 함께 들어갔는지 | 실제 변경 필드를 확인하고 due tick 재계산 여부를 대조합니다. |
| 예정 시각이 지났지만 run이 보이지 않음 | runner 상태, next_run_at, last_status, 실행 권한 | 스케줄 저장과 발화를 분리해 확인하고 중복 스케줄을 만들지 않습니다. |
| 보관된 에이전트 스케줄을 다시 켤 수 없음 | 에이전트 archived 상태, is_enabled 변경 방향 | 먼저 에이전트 상태를 확인하고 활성화 요청을 반복하지 않습니다. |
| 에이전트 삭제 뒤 스케줄이 남아 보임 | is_enabled, next_run_at, last_status | agent_not_found 정리 상태인지 확인하고 과거 run과 현재 스케줄을 구분합니다. |
완료 기준과 다음 문서
스케줄 작업은 다음 조건을 모두 확인했을 때 완료로 기록합니다.
- 대상 에이전트와 필요한 권한을 확인했습니다.
- 5필드 cron, IANA 시간대, 실행 메시지를 검증했습니다.
- 목록에서 is_enabled와 next_run_at을 확인했습니다.
- 예정 시각 이후 last_run_id, last_status와 연결된 run 상태를 대조했습니다.
- 오류가 났다면 권한, 입력 검증, runner 발화 문제를 구분했습니다.
다음 문서에서 실행 상태와 Thread의 관계를 이어서 확인할 수 있습니다.