Scheduler 도구

Scheduler 도구 (Scheduler Tool)

에이전트가 고른 시각이나 반복 주기로 세션 중에 무언가를 실행하게 하는 방법을 설명해요. 모니터링과 예약 작업에 유용해요.

출처: 문서

본문

scheduler 도구셋은 에이전트가 세션 중 선택된 시각이나 반복 주기에 무언가가 일어나게 해 줘요. 지침과 일정을 주면, 일정이 되었을 때 지침이 에이전트로 다시 전달되고, 에이전트는 평소 도구(shell, api, fetch 등)로 그 동작을 수행해요.

scheduler는 스스로 셸이나 API 호출을 실행하지 않아요. 일정이 발동하면 런타임의 리콜 메커니즘 — background_jobs가 완료된 작업을 보고하는 것과 같은 원시 기능 — 으로 지침을 에이전트 루프에 주입하고, 에이전트가 어떻게 행동할지 결정해요. 이렇게 하면 모든 동작이 에이전트의 평소 도구와 권한 아래에 있어서, 두 번째 무인(無人) 명령 실행기가 추가되지 않아요.

참고 일정은 세션이 실행 중일 때만 발동하고(대화형 TUI 또는 서버 모드) 재시작 시 유지되지 않아요. 스케줄링은 리콜을 지원하는 호스트가 필요하며, 지원하지 않으면 create_schedule이 오류를 반환해요.

구성

toolsets:
  - type: scheduler

구성 옵션은 없어요.

도구

도구 설명
create_schedule 시각 또는 간격에 실행할 지침 등록
list_schedules id, 스펙, 다음 발동 시각과 함께 활성 일정 나열
cancel_schedule id로 일정 제거

create_schedule

파라미터 필수 설명
prompt 네 일정이 발동할 때 에이전트에 전달할 지침
when 네 언제 발동할지(아래 Schedule specs 참고)
name 아니오 선택적 사람이 읽을 수 있는 라벨

새 일정의 id와 다음 발동 시각을 반환해요.

cancel_schedule

파라미터 필수 설명
id 네 취소할 일정의 id(create_schedule 또는 list_schedules에서)

일정 스펙

when 인수는 다음을 받아요:

형태 의미 예시
in: 일회성, 지연 후 in:10m
at: 일회성, 절대 미래 시각에 at:2026-07-14T09:00:00Z
every: 반복, 고정 간격 every:1h
minutely / hourly / daily / weekly 반복 사전 설정 간격 hourly

기간은 Go 기간 문법(30s, 15m, 2h)을 사용해요. 사전 설정과 every: 간격은 일정 생성 시각부터 측정돼요(예: hourly는 생성 후 매시간 발동), 벽시계 슬롯에 맞춰지지 않아요.

중요 반복 일정은 1분 최소 시간이 있어요. 매 발동은 에이전트 루프에 메시지를 주입하고 보통 LLM 턴 비용이 들어요. 그래서 every: 값이 1m 미만이면 거부돼요 — every:1h 대신 every:1s 같은 오타가 그렇지 않으면 통제 불능의 토큰 소모가 되거든요. 일회성 일정(in:/at:)은 한 번만 발동하므로 제한되지 않아요.

예시

agents:
  root:
    model: openai/gpt-5-mini
    description: A monitoring assistant
    instruction: |
      Every 15 minutes, run `git fetch` and tell me if origin/main moved.
    toolsets:
      - type: scheduler
      - type: shell

에이전트가 호출해요:

create_schedule(prompt="Run git fetch and report if origin/main moved", when="every:15m")

매 15분마다 상기되고, shell 도구로 명령을 실행하고, 보고해요.

팁 언제 쓸까 장기 실행 세션 중 반복 모니터링, 예약된 일회성 작업, 무인 하우스키핑 루프에 scheduler를 사용하세요. 즉시 실행되어 대기해야 하는 작업은 background_jobs를 대신 사용하세요.

더 알아보기 (Learn more)