# 자동화 및 예약

## 크론 작업

정확한 타이밍으로 에이전트 깨우기를 예약합니다. 크론 작업은 게이트웨이 재시작 후에도 지속되며 유연한 예약 패턴을 지원합니다.

### 예약 유형

| 유형 | 설명 | 예시 |
|------|-------------|---------|
| **크론 표현식** | 시간대가 있는 표준 크론 구문 | `0 7 * * *` (매일 오전 7시) |
| **인터벌** | 고정 간격으로 반복 | `30m`, `2h`, `1d` |
| **일회성** | 특정 시간에 한 번 실행 | `2026-03-15T16:00:00Z` |

### 세션 대상

- **메인 세션**, 에이전트의 메인 대화에서 시스템 이벤트로 큐에 추가합니다
- **격리된 세션**, 메인 대화를 오염시키지 않기 위해 전용 세션(`cron:<jobId>`)에서 실행합니다

### 배달 모드

| 모드 | 설명 |
|------|-------------|
| **없음** | 자동 실행 (출력이 게시되지 않음) |
| **공지** | 특정 채널에 결과를 다시 게시합니다 |
| **웹훅** | 외부 URL에 결과를 HTTP POST합니다 |

### 일회성 알림

특정 시간에 알림을 설정합니다. 에이전트가 깨어나 알림을 처리하고, 선택적으로 실행 후 작업을 삭제합니다.

### 반복 작업

크론 표현식과 시간대 지원을 통해 반복 작업을 예약합니다. 작업은 실행 기록(성공, 실패, 타이밍)을 추적합니다.

---

## 웹훅

외부 서비스에서 이벤트를 수신하여 에이전트로 라우팅합니다.

### Gmail Pub/Sub

이메일 도착 시 에이전트 작업을 트리거하기 위해 Gmail의 푸시 알림 시스템과 통합합니다:

1. GCP Pub/Sub 주제 및 구독 설정
2. Gmail 레이블 필터링 구성
3. 웹훅 URL에 푸시 배달 포인트
4. Neotask가 메시지를 받고 에이전트 이벤트를 큐에 추가합니다

### 커스텀 웹훅

호출될 때 에이전트 차례를 트리거하는 HTTP 엔드포인트를 등록합니다. CI/CD 파이프라인, 모니터링 시스템, 또는 HTTP 요청을 보낼 수 있는 모든 서비스와 통합하는 데 유용합니다.

---

## 시스템 이벤트

시스템 이벤트는 처리를 위해 에이전트를 깨우는 신호입니다:

- **즉시**, 다음 하트비트에서 처리합니다
- **다음 하트비트**, 다음 예약된 체크인을 위해 큐에 추가합니다

반응형 워크플로에 시스템 이벤트를 사용하세요, 에이전트가 고정된 일정보다는 무언가가 발생할 때 깨어납니다.

---

## 하트비트

하트비트는 에이전트가 대기 중인 작업을 처리할 기회를 주는 주기적 신호입니다 (기본값 ~15초):

- 새 시스템 이벤트 확인
- 큐에 있는 메시지 처리
- 대기 중인 자동화 실행

하트비트는 에이전트별로 활성화, 비활성화 또는 구성할 수 있습니다.

---

## 훅

게이트웨이 이벤트에 응답하여 셸 명령이나 스크립트를 트리거하는 이벤트 기반 자동화:

- **메시지 수신 시**, 메시지가 수신될 때 실행합니다
- **에이전트 차례 시**, 에이전트가 메시지를 처리하기 전이나 후에 실행합니다
- **채널 이벤트 시**, 채널별 이벤트(참가, 떠나기, 반응)에서 실행합니다

훅은 게이트웨이 호스트에서 실행되며 이벤트 컨텍스트 데이터에 접근할 수 있습니다.

---

## 사용 사례

| 시나리오 | 해결책 |
|----------|----------|
| 매일 아침 브리핑 | 오전 7시 크론 작업 → 에이전트가 밤새 업데이트를 요약합니다 |
| 주간 보고서 생성 | 매주 월요일 크론 작업 → 에이전트가 보고서를 생성하고 이메일로 전송합니다 |
| 이메일 모니터링 | Gmail 웹훅 → 에이전트가 수신 이메일을 처리합니다 |
| 빌드 알림 | CI/CD 웹훅 → 에이전트가 Discord에서 빌드 결과를 발표합니다 |
| 시간별 데이터 확인 | 인터벌 기반 크론 → 에이전트가 대시보드를 확인하고 이상 시 알림을 보냅니다 |
| 예약된 소셜 게시 | 크론 작업 → 에이전트가 최적의 시간에 콘텐츠를 작성하고 게시합니다 |