스케줄링 및 SOP 도구

이 페이지는 Revka 에이전트가 세션 내에서 작업을 스케줄링하고 표준 운영 절차(SOP)를 수행하는 데 사용하는 에이전트 도구를 설명합니다. 두 가지 도구 패밀리가 있습니다.

• cron_* 도구 — cron_add, cron_list, cron_remove, cron_update, cron_run, cron_runs — 스케줄링된 작업을 생성하고 관리합니다. 하위 호환성을 위해 유지되는 레거시 schedule 도구도 포함됩니다.
• sop_* 도구 — sop_list, sop_execute, sop_advance, sop_approve, sop_status — SOP를 나열하고 실행하며, 승인 게이트를 통해 진행합니다.

각 도구가 허용하는 정확한 파라미터가 필요할 때 이 페이지를 참고하세요. 운영자용 CLI 동등 명령은 revka cron 및 revka skills, workflows & sop를 참고하고, 개념 모델은 Cron 개요 및 표현식과 SOP 레퍼런스: 구문, 트리거 및 실행을 참고하세요. 동일한 작업과 실행 이력은 HTTP를 통해서도 접근할 수 있습니다 — Cron, 세션 및 첨부 파일 API를 참고하세요.

참고

크론 작업을 실제로 실행하는 스케줄러는 데몬 내부에서 동작하며, 대부분의 cron 도구는 읽기 전용 자율 모드와 레이트 리밋 상태에서 차단됩니다. 또한 전체 서브시스템은 cron.enabled = true(기본값)를 필요로 합니다 — false로 설정된 경우 cron 도구와 API는 오류를 반환합니다. 자율성 수준 및 승인을 참고하세요.

Cron 도구

크론 작업은 세 가지 스케줄 형태 중 하나와 에이전트가 생성할 수 있는 두 가지 작업 유형 중 하나를 가집니다.

스케줄(schedule 필드는 oneOf):

형태	JSON	반복 여부	타임존 지원
Cron 표현식	{"kind":"cron","expr":"0 9 * * 1-5","tz":"America/New_York"}	예	예 (tz)
인터벌	{"kind":"every","every_ms":3600000}	예	아니오
1회성	{"kind":"at","at":"2026-12-31T23:59:00Z"}	아니오	아니오 (항상 UTC)

• expr은 5-, 6-, 7-필드 cron 표현식입니다. 표준 5-필드 crontab 구문은 내부적으로 정규화됩니다(초 필드가 앞에 추가되고 요일 열 번호가 재지정됩니다). 익숙한 1 = 월요일 번호 체계로 작성하세요.
• tz는 선택적 IANA 타임존 이름으로, cron 스케줄에서만 적용됩니다. at와 every는 이를 무시합니다. tz를 생략하면 호스트 로컬 시간이 아닌 UTC가 기본값이 됩니다.
• every_ms는 양의 정수여야 합니다. at는 미래의 RFC 3339 UTC 날짜시간이어야 합니다.

작업 유형:

• shell — sh -c를 통해 명령을 실행합니다. 생성 시와 실행 시 보안 정책에 따라 검증되며, 중간 위험 명령은 승인이 필요합니다. command가 필요합니다.
• agent — 관련 메모리 컨텍스트가 주입된 상태로 Revka 에이전트를 통해 프롬프트를 실행합니다. 읽기 전용 모드에서 차단됩니다. prompt가 필요합니다. (세 번째 유형인 workflow는 존재하지만 워크플로우 YAML 트리거에 의해 관리되며, 이 도구들로는 생성할 수 없습니다.)

cron_add

새로운 shell 또는 agent 크론 작업을 생성합니다. 에이전트 기반 작업 스케줄링과 채널에 예약 메시지를 전송하는 데 권장되는 도구입니다.

{
  "name": "morning-brief",
  "schedule": {"kind": "cron", "expr": "0 9 * * 1-5", "tz": "America/New_York"},
  "job_type": "agent",
  "prompt": "Summarize overnight alerts and post to the channel",
  "delivery": {"mode": "announce", "channel": "discord", "to": "1234567890", "best_effort": true}
}

필드	타입	의미
schedule	객체 (필수)	cron / at / every 객체. JSON 문자열로 직렬화된 객체를 전달해도 허용됩니다.
job_type	문자열	"shell" 또는 "agent". prompt만 제공된 경우 "agent"로 추론됩니다.
command	문자열	셸 명령 — shell 작업에 필수.
prompt	문자열	에이전트 프롬프트 — agent 작업에 필수.
name	문자열	선택적 사람이 읽을 수 있는 레이블.
session_target	문자열	"isolated" (기본값) 또는 "main".
model	문자열	agent 작업의 모델 재정의.
allowed_tools	배열	agent 작업에 허용할 도구 이름. 빈 배열은 모든 도구를 허용합니다.
delivery	객체	각 실행 후 작업 출력을 채팅 채널로 전달합니다(전달 / 공지 모드 참고).
delete_after_run	불리언	at 스케줄의 경우 기본값이 true.
approved	불리언	기본값 false. 감독 모드에서 중간 위험 셸 명령을 승인하려면 true로 설정합니다.

최소한의 shell 작업 예시:

{
  "schedule": {"kind": "cron", "expr": "*/5 * * * *"},
  "job_type": "shell",
  "command": "echo ok"
}

cron_list

등록된 모든 작업을 JSON 배열로 나열합니다. 읽기 전용으로 보안 제한이 없습니다. 파라미터를 받지 않습니다.

{}

작업이 없으면 []를 반환합니다. cron.enabled = false이면 오류를 반환합니다.

cron_remove

작업을 ID로 영구 삭제하며, 실행 이력(cron_runs 행)도 함께 삭제됩니다. 취소할 수 없습니다 — 삭제하지 않고 작업을 비활성화하려면 cron_update로 enabled: false를 설정하세요.

{"job_id": "<uuid>"}

필드	타입	의미
job_id	문자열 (필수)	cron_add 또는 cron_list에서 반환된 UUID.

읽기 전용 모드와 레이트 리밋 상태에서 차단됩니다. 작업을 찾을 수 없으면 오류를 반환합니다.

cron_update

기존 작업의 하나 이상의 필드를 수정합니다. patch에 포함된 필드만 변경되며, 생략된 필드는 현재 값을 유지합니다.

{
  "job_id": "<uuid>",
  "patch": {"enabled": false}
}

{
  "job_id": "<uuid>",
  "patch": {
    "schedule": {"kind": "cron", "expr": "0 10 * * *"},
    "prompt": "New prompt text"
  }
}

필드	타입	의미
job_id	문자열 (필수)	대상 작업의 UUID.
patch	객체 (필수)	name, enabled, command, prompt, model, allowed_tools, session_target, delete_after_run, schedule, delivery 중 임의의 부분 집합.
approved	불리언	감독 모드에서 변경된 셸 명령 승인.

주의

패치에서 "allowed_tools": []를 전달하면 허용 목록이 초기화됩니다(모든 도구가 허용됨) — “도구를 0개 허용”을 의미하는 것이 아닙니다. command를 변경하면 새 명령이 보안 정책에 따라 재검증됩니다. 읽기 전용 모드와 레이트 리밋 상태에서 차단됩니다.

cron_run

작업을 정상 스케줄 외에 즉시 강제 실행하고, 결과를 실행 이력에 기록하며, 마지막 실행 메타데이터를 업데이트합니다. 작업을 다시 스케줄링하지는 않습니다 — next_run은 변경되지 않습니다. 필요할 때 작업을 테스트하는 데 유용합니다.

{"job_id": "<uuid>", "approved": true}

필드	타입	의미
job_id	문자열 (필수)	대상 작업의 UUID.
approved	불리언	감독 모드에서 중간 위험 셸 명령 승인.

{job_id, status, duration_ms, output}을 반환합니다. Shell 작업은 실행 시 명령을 재검증합니다(생성 이후 정책이 변경되었을 수 있음). 읽기 전용 모드와 레이트 리밋 상태에서 차단됩니다.

cron_runs

작업의 최근 실행 이력(타임스탬프, 상태, 소요 시간, 잘린 출력)을 반환합니다. 읽기 전용으로 보안 제한이 없습니다.

{"job_id": "<uuid>", "limit": 10}

필드	타입	의미
job_id	문자열 (필수)	UUID 문자열.
limit	정수	반환할 실행 수. 기본값은 10.

도구 응답에서 출력은 실행당 500자로 잘립니다. 저장된 레코드는 최대 16 KB를 보유하며, 작업당 보유되는 레코드 수는 cron.max_run_history에 의해 결정됩니다.

schedule (레거시)

이전의 shell 전용 스케줄링 도구입니다. 더 다양한 액션을 지원하지만 shell 작업만 생성하며, 출력은 로그에만 기록됩니다 — 전달, agent 작업, 타임존 제어가 없습니다. 하위 호환성을 위해 문서화되어 있으며, 새로운 통합에는 cron_add를 사용하세요.

{"action": "create", "expression": "*/5 * * * *", "command": "backup.sh"}
{"action": "once", "delay": "30m", "command": "echo once"}
{"action": "list"}
{"action": "get", "id": "<uuid>"}
{"action": "pause", "id": "<uuid>"}
{"action": "resume", "id": "<uuid>"}
{"action": "cancel", "id": "<uuid>"}
{"action": "remove", "id": "<uuid>"}

필드	타입	의미
action	문자열 (필수)	create | add | once | list | get | cancel | remove | pause | resume.
expression	문자열	Cron 표현식(create / add용).
delay	문자열	"30m", "2h", "1d" 같은 사람이 읽을 수 있는 지연 시간(once용).
run_at	문자열	절대적 1회성 실행을 위한 RFC 3339 타임스탬프.
command	문자열	셸 명령(create / add / once에 필수).
id	문자열	get / cancel / remove / pause / resume용 작업 UUID.
approved	불리언	감독 모드 승인.

팁

출력을 Telegram, Discord, Slack 또는 다른 채널로 전달하거나 셸 명령 대신 agent 프롬프트를 원하는 경우 cron_add를 사용하세요. 두 도구는 공존하며 동일한 작업 저장소를 공유하므로, 어느 도구에서 생성한 작업이든 cron_list에 표시됩니다.

전달 / 공지 모드

cron_add와 cron_update의 delivery 객체는 각 실행 후 작업 출력을 채팅 채널로 전달합니다.

"delivery": {
  "mode": "announce",
  "channel": "discord",
  "to": "1234567890",
  "best_effort": true
}

필드	타입	의미
mode	문자열	"none" (기본값) 또는 "announce".
channel	문자열	"telegram", "discord", "slack", "mattermost", "signal", "matrix", "qq", 또는 "whatsapp".
to	문자열	대상 식별자(Discord 채널 ID, Telegram 채팅 ID, Slack 채널 이름, Matrix 룸 ID 등).
best_effort	불리언	기본값 true. false이면 전달 실패 시 작업 자체가 성공했더라도 실행이 "error"로 표시됩니다.

참고

전달 전에 출력에서 자격증명 유출 여부가 검사되며, 감지된 비밀은 [REDACTED]로 치환됩니다. matrix와 whatsapp 채널은 빌드 시 기능 플래그로 제어됩니다. 해당 Cargo 기능 없이 빌드된 바이너리에서 이를 사용하면 명확한 오류가 반환됩니다. 채널 설정은 채널 개요를 참고하세요.

SOP 도구

표준 운영 절차(SOP)는 디스크의 SOP.toml + SOP.md 파일로 정의되어 Revka의 SOP 엔진에 의해 실행되는 결정적이고 다단계적인 절차입니다. 이 도구들을 통해 에이전트는 SOP를 나열하고, 실행을 시작하고, 단계별로 진행하며, 승인 게이트를 해제할 수 있습니다. SOP 디렉토리(sop.sops_dir)가 구성되어 있어야 합니다. 정의, 트리거, 실행 모드에 대해서는 SOP 레퍼런스: 구문, 트리거 및 실행을 참고하세요.

일반적인 루프는 다음과 같습니다. sop_execute로 실행 시작 → sop_advance를 반복하며(필요 시 sop_approve로 게이트 해제) 실행 완료까지 진행 → 언제든지 sop_status로 상태 확인.

참고

revka sop run CLI 명령은 없습니다. 실행은 sop_execute를 통해 또는 SOP에 구성된 트리거(수동, 웹훅, MQTT, cron, 또는 주변 장치)에 의해 시작됩니다. CLI는 정의 검사용입니다. revka sop list, revka sop show, revka sop validate.

sop_list

로드된 모든 SOP를 트리거, 우선순위, 단계 수, 활성 실행 수와 함께 나열합니다. 선택적 필터를 지원합니다.

{"filter": "incident"}

필드	타입	의미
filter	문자열	SOP 이름에 대한 부분 문자열 필터.
priority	문자열	우선순위 수준 필터(low | normal | high | critical).

sop_execute

이름으로 SOP를 수동 트리거합니다. 실행 ID와 첫 번째 단계의 지시사항을 반환합니다. 실행 ID는 이후의 모든 sop_advance, sop_approve, sop_status 호출에 필요합니다.

{"name": "incident-response"}

필드	타입	의미
name	문자열 (필수)	sop_list에 표시된 SOP 이름.

sop_advance

현재 단계의 결과를 보고하고 다음 단계로 진행합니다.

{"run_id": "run_abc123", "success": true, "output": "Backup completed successfully"}

필드	타입	의미
run_id	문자열 (필수)	sop_execute에서 반환된 실행 ID.
success	불리언 (필수)	단계 성공 여부.
output	문자열 (필수)	해당 단계의 간략한 출력 요약.

sop_approve

운영자 승인을 기다리는 단계를 승인하고 실행할 단계 지시사항을 반환합니다. 승인 게이트는 supervised, step_by_step 같은 모드에서, requires_confirmation으로 표시된 단계에서, 그리고 결정적 체크포인트에서 나타납니다. 게이트에서 일시 정지된 실행은 waiting_approval 또는 paused_checkpoint 상태를 표시합니다.

{"run_id": "run_abc123"}

필드	타입	의미
run_id	문자열 (필수)	일시 정지된 실행의 실행 ID.

sop_status

SOP 실행 상태를 조회합니다. 특정 실행을 조회하려면 run_id를, 특정 SOP의 실행 목록을 보려면 sop_name을 전달하고, 인자 없이 호출하면 모든 활성 실행을 표시합니다.

{}

{"run_id": "run_abc123"}

{"sop_name": "incident-response"}

필드	타입	의미
run_id	문자열	특정 실행.
sop_name	문자열	해당 SOP의 실행 목록.

실행 상태는 pending, running, waiting_approval, paused_checkpoint, completed, failed, cancelled 중 하나입니다.

관련 페이지

• 도구 개요 — 도구 등록 및 게이팅 방식.
• revka cron — 작업 생성 및 관리를 위한 CLI 동등 명령.
• revka skills, workflows & sop — revka sop CLI.
• Cron 개요 및 표현식 및 Agent 작업 및 전달 — cron 모델 심층 설명.
• SOP 레퍼런스: 구문, 트리거 및 실행 — SOP 정의 및 실행 모드.
• Cron, 세션 및 첨부 파일 API — HTTP를 통한 작업 관리.