에이전트 작업 및 전달

크론 작업은 셸 명령을 실행하거나 프롬프트와 함께 Revka 에이전트를 호출할 수 있습니다. 이 페이지에서는 에이전트 작업 — 즉, 프롬프트 예약 방법, 실행할 세션과 모델 제어, 호출 가능한 도구 제한, 매 실행 후 출력을 채팅 채널로 전달하는 방법 — 을 설명합니다.

고정된 셸 명령 대신 추론이나 도구가 필요한 반복 작업(예: 아침 브리핑, 알림 분류, 팀에 게시되는 예약 요약)에 에이전트 작업을 사용하십시오. 스케줄 형식(cron, every, at)과 표현식 문법은 크론 개요 및 표현식을 참고하십시오. 전체 CLI 참조는 revka cron을, 정적 작업 선언 방법은 선언적 작업 및 스케줄러 설정을 참고하십시오.

참고

작업을 실행하는 스케줄러는 데몬 내부에서 동작합니다. CLI, cron_add 도구, 또는 크론, 세션 및 첨부 API를 통해 작업을 생성할 수 있지만, 데몬이 실행 중이고 cron.enabled = true(기본값)인 경우에만 실행됩니다.

에이전트 작업의 실행 방식

에이전트 작업이 실행될 때 Revka는 다음 단계를 수행합니다.

1. 메모리 스토어에서 관련 컨텍스트를 가져와 프롬프트 앞에 추가합니다.
2. 설정된 세션 대상에서 설정된 모델과 허용 도구 허용 목록으로 에이전트를 실행합니다.
3. 실행 결과(상태, 소요 시간, 잘린 출력)를 실행 기록에 저장합니다.
4. 전달이 설정된 경우, 출력에서 자격 증명 유출을 검사한 후 채널에 알립니다.

에이전트 작업은 셸 작업이 거치는 셸 명령 허용 목록 검증을 건너뛰지만, 읽기 전용 자율 모드이거나 속도 제한에 걸린 경우에는 차단됩니다. 자율 수준 및 승인을 참고하십시오.

에이전트 작업 생성

가장 간단한 에이전트 작업은 스케줄에 따라 실행되는 프롬프트입니다. CLI에서 --agent 플래그를 사용하면 마지막 인수가 셸 명령 대신 프롬프트로 처리됩니다.

revka cron add '0 9 * * 1-5' --agent 'Check server health and summarize'

cron_add 에이전트 도구를 사용할 경우, job_type을 "agent"로 설정하십시오(prompt만 지정하면 자동으로 추론됩니다).

{
  "name": "morning-brief",
  "schedule": { "kind": "cron", "expr": "0 9 * * 1-5", "tz": "America/New_York" },
  "job_type": "agent",
  "prompt": "Summarize overnight alerts"
}

팁

5분보다 자주 실행되도록 예약된 에이전트 작업은 권고 로그 경고를 생성합니다. 이는 소프트 경고로, 실행을 차단하지는 않습니다.

세션 대상

에이전트 작업은 session_target 필드로 설정된 두 가지 세션 대상 중 하나에서 실행됩니다.

값	동작
isolated (기본값)	매 실행마다 새로운 빈 컨텍스트에서 시작합니다.
main	대화형 채팅과 동일한 세션을 공유하며 실행됩니다.

{ "session_target": "isolated" }

최근 대화 컨텍스트를 작업에서 참조해야 할 때는 main을 사용하십시오. 다만, 대화형 사용에 영향을 줄 수 있으니 주의하십시오. 대부분의 자동화 작업에는 isolated를 권장합니다.

모델 재정의

에이전트 작업은 기본적으로 설정된 기본 모델을 사용합니다. model 필드를 설정하면 프로바이더 라우터가 허용하는 프로바이더/모델 문자열로 작업별 모델을 재정의할 수 있습니다.

{ "model": "anthropic/claude-opus-4-5" }

# Declarative form, in config.toml
[[cron.jobs]]
model = "anthropic/claude-opus-4-5"

model을 생략하면 기본 설정 모델이 사용됩니다.

허용 도구 목록

allowed_tools 필드는 실행 중 에이전트가 호출할 수 있는 도구를 제한합니다. 이 필드를 설정하면 목록에 지정된 도구만 사용 가능하며, 생략하거나 비워 두면 모든 도구를 사용할 수 있습니다.

{ "allowed_tools": ["file_read", "web_search"] }

CLI에서는 도구마다 --allowed-tool을 반복하여 지정하십시오.

revka cron add '*/15 * * * *' --agent \
  --allowed-tool file_read --allowed-tool web_search \
  'Check server health'

주의

cron_update에서 "allowed_tools": []를 전달하면 허용 목록이 초기화되어 모든 도구가 사용 가능해집니다. 도구를 0개로 제한하는 것이 아닙니다. 작업을 실제로 제한하려면 항상 비어 있지 않은 목록을 전달하십시오.

전달 / 알림 모드

매 실행 후 Revka는 작업의 출력을 채팅 채널로 전달할 수 있습니다. cron_add 또는 cron_update의 delivery 객체로 설정합니다.

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

필드	타입	기본값	설명
mode	string	none	none(전달 없음) 또는 announce(채널로 출력 전송)
channel	string	—	대상 채널 플랫폼(announce 시 필수)
to	string	—	목적지 식별자(announce 시 필수)
best_effort	bool	true	false로 설정하면, 작업 자체가 성공해도 전달 실패 시 실행이 error로 기록됩니다.

지원 채널: telegram, discord, slack, mattermost, signal, matrix, qq. matrix 채널은 기능 게이팅이 적용됩니다(channel-matrix Cargo 기능 필요). 메시징 채널 연결 및 채널 개요를 참고하십시오.

to 값은 플랫폼 고유 목적지 식별자로, Discord 채널 ID, Telegram 채팅 ID, Slack 채널 이름, Matrix 룸 ID 등이 해당합니다. 채널 자체는 config.toml에 이미 설정되어 있어야 하며, 전달은 채널의 기존 자격 증명을 재사용합니다.

참고

best_effort는 가시성을 제어하는 것이지 재시도를 제어하는 것이 아닙니다. 기본값 true에서는 전달 실패가 로깅되지만 실행은 ok로 기록됩니다. 전달 성공이 작업의 성공 기준에 포함되어야 할 경우 best_effort: false로 설정하십시오.

자격 증명 재작성(Redaction)

출력이 채널로 전송되기 전에 Revka는 자격 증명 유출 여부를 검사합니다. 시크릿이 감지되면 각 일치 항목이 [REDACTED]로 대체되고, 메시지 전송 전에 경고(채널, 대상, 감지된 패턴 포함)가 로깅됩니다. 이 재작성은 모든 외부 전달 경로에 강제 적용되며, 검사를 우회하는 방법은 없습니다. 별도의 설정 없이 항상 활성화되어 있습니다.

cron_add 도구를 통한 전달

cron_add는 에이전트 작업과 채널 전달을 단일 호출로 지원하므로, 에이전트 기반 작업 및 예약된 채널 메시지를 위한 기본 도구로 권장됩니다. 전체 예시 — 매일 오전 9시(동부 시간), 알림 요약 후 Discord에 게시:

{
  "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 channel",
  "session_target": "isolated",
  "model": "anthropic/claude-opus-4-5",
  "allowed_tools": ["file_read", "http_request"],
  "delivery": { "mode": "announce", "channel": "discord", "to": "1234567890", "best_effort": true }
}

에이전트 작업 및 전달과 관련된 cron_add 파라미터:

필드	필수 여부	설명
schedule	예	cron / at / every 객체(JSON 문자열화된 객체도 허용)
job_type	—	"agent" 또는 "shell". prompt만 지정된 경우 "agent"로 추론됨
prompt	에이전트 작업 시 필수	에이전트 프롬프트
name	—	사람이 읽기 쉬운 레이블
session_target	—	"isolated"(기본값) 또는 "main"
model	—	모델 재정의 문자열
allowed_tools	—	도구 이름 배열. 비어 있거나 생략 시 모든 도구 사용 가능
delivery	—	{ mode, channel, to, best_effort }
delete_after_run	—	at 스케줄의 경우 기본값 true

주의

레거시 schedule 도구는 셸 전용 작업만 생성하며 전달을 지원하지 않습니다 — 출력은 로그에만 기록됩니다. 에이전트 작업이나 채널 전달이 필요할 때는 반드시 cron_add를 사용하십시오.

게이트웨이 API를 통한 전달

크론 API는 POST /api/cron 본문에 동일한 필드를 허용하지만, 한 가지 차이점이 있습니다. 여기서 schedule은 객체가 아닌 문자열 크론 표현식이므로, 게이트웨이 엔드포인트는 cron 스케줄만 지원합니다. at 또는 every가 필요하면 cron_add 또는 CLI를 사용하십시오.

POST /api/cron
Authorization: Bearer <pairing-token>
Content-Type: application/json

{
  "schedule": "0 9 * * 1-5",
  "job_type": "agent",
  "prompt": "Summarize overnight alerts and post to channel",
  "session_target": "isolated",
  "model": null,
  "allowed_tools": null,
  "delivery": { "mode": "announce", "channel": "telegram", "to": "123456", "best_effort": true }
}

호출이 성공하면 {"status":"ok","job":{...}}가 반환됩니다.

참고

PATCH /api/cron/:id는 delivery, model, allowed_tools, session_target을 노출하지 않습니다. 생성 후 이 값들을 변경하려면 전체 패치 기능을 지원하는 cron_update 도구를 사용하십시오.

실행 검증 및 검사

스케줄을 기다리지 않고 작업을 즉시 강제 실행하여 테스트한 후, 기록된 출력을 검사할 수 있습니다.

// cron_run
{ "job_id": "<uuid>" }

// cron_runs — recent history for one job
{ "job_id": "<uuid>", "limit": 10 }

cron_runs는 타임스탬프, 상태(ok / error), 소요 시간, 잘린 출력(도구 응답에서 실행당 최대 500자. 저장 레코드는 최대 16KB 보관)을 반환합니다. 동일한 기록을 GET /api/cron/:id/runs?limit=20에서도 확인할 수 있습니다. 저장 한도 및 정리 방식은 선언적 작업 및 스케줄러 설정을 참고하십시오.