# ระบบอัตโนมัติและการจัดกำหนดการ

## Cron Job

กำหนดเวลาการปลุกเอเจนต์ด้วยเวลาที่แม่นยำ Cron job คงอยู่ข้ามการรีสตาร์ท Gateway และรองรับรูปแบบการจัดกำหนดการที่ยืดหยุ่น

### ประเภทกำหนดการ

| ประเภท | คำอธิบาย | ตัวอย่าง |
|------|-------------|---------|
| **Cron expression** | ไวยากรณ์ cron มาตรฐานพร้อม timezone | `0 7 * * *` (ทุกวันเวลา 7 โมงเช้า) |
| **Interval** | ทำซ้ำในช่วงเวลาคงที่ | `30m`, `2h`, `1d` |
| **One-shot** | รันครั้งเดียวในเวลาที่กำหนด | `2026-03-15T16:00:00Z` |

### เป้าหมาย Session

- **Main session**, จัดคิวเป็น system event ในการสนทนาหลักของเอเจนต์
- **Isolated session**, รันในเซสชันเฉพาะ (`cron:<jobId>`) เพื่อหลีกเลี่ยงการปนเปื้อนการสนทนาหลัก

### โหมดการส่งมอบ

| โหมด | คำอธิบาย |
|------|-------------|
| **None** | การรันเงียบ (ไม่มีเอาต์พุตที่โพสต์) |
| **Announce** | โพสต์ผลลัพธ์กลับไปยังช่องทางเฉพาะ |
| **Webhook** | HTTP POST ผลลัพธ์ไปยัง URL ภายนอก |

### การเตือนความจำ One-Shot

ตั้งการเตือนความจำสำหรับเวลาเฉพาะ เอเจนต์จะตื่น ประมวลผลการเตือนความจำ และอาจลบงานหลังจากรัน

### งานที่เกิดซ้ำ

กำหนดเวลางานที่ทำซ้ำด้วย cron expression และการรองรับ timezone งานติดตามประวัติการรัน (ความสำเร็จ ความล้มเหลว เวลา)

---

## Webhook

รับ event จากบริการภายนอกและกำหนดเส้นทางไปยังเอเจนต์

### Gmail Pub/Sub

ผสานรวมกับระบบแจ้งเตือน push ของ Gmail เพื่อทริกเกอร์การกระทำเอเจนต์เมื่ออีเมลมาถึง:

1. ตั้งค่า GCP Pub/Sub topic และ subscription
2. กำหนดค่าการกรอง Gmail label
3. ชี้การส่งมอบ push ไปยัง webhook URL ของคุณ
4. Neotask รับข้อความและจัดคิว event เอเจนต์

### Custom Webhook

ลงทะเบียน HTTP endpoint ที่ทริกเกอร์รอบเอเจนต์เมื่อถูกเรียก มีประโยชน์สำหรับการผสานรวมกับ CI/CD pipeline ระบบตรวจสอบ หรือบริการใด ๆ ที่สามารถส่งคำขอ HTTP

---

## System Event

System event คือสัญญาณที่ปลุกเอเจนต์สำหรับการประมวลผล:

- **Immediate**, ประมวลผลใน heartbeat ถัดไป
- **Next heartbeat**, จัดคิวสำหรับการเช็คอินตามกำหนดการถัดไป

ใช้ system event สำหรับเวิร์กโฟลว์แบบตอบสนอง, เอเจนต์ตื่นขึ้นเมื่อมีสิ่งเกิดขึ้นแทนที่จะเป็นในกำหนดการคงที่

---

## Heartbeat

Heartbeat คือสัญญาณเป็นระยะ (ค่าเริ่มต้น ~15 วินาที) ที่ให้เอเจนต์มีโอกาสประมวลผลงานที่รอดำเนินการ:

- ตรวจสอบ system event ใหม่
- ประมวลผลข้อความที่จัดคิว
- รันระบบอัตโนมัติที่รอดำเนินการ

Heartbeat สามารถเปิดใช้งาน ปิดใช้งาน หรือกำหนดค่าต่อเอเจนต์ได้

---

## Hook

ระบบอัตโนมัติที่ขับเคลื่อนด้วย event ที่ทริกเกอร์คำสั่งเชลล์หรือสคริปต์เพื่อตอบสนองต่อ Gateway event:

- **On message**, รันเมื่อได้รับข้อความ
- **On agent turn**, รันก่อนหรือหลังเอเจนต์ประมวลผลข้อความ
- **On channel event**, รันบน event เฉพาะช่องทาง (เข้าร่วม ออก ปฏิกิริยา)

Hook รันบน Gateway host และมีสิทธิ์เข้าถึงข้อมูล context ของ event

---

## กรณีการใช้งาน

| สถานการณ์ | โซลูชัน |
|----------|----------|
| สรุปข่าวสารตอนเช้า | Cron job เวลา 7 โมงเช้า → เอเจนต์สรุปการอัปเดตข้ามคืน |
| การสร้างรายงานรายสัปดาห์ | Cron job ทุกวันจันทร์ → เอเจนต์สร้างและส่งอีเมลรายงาน |
| การตรวจสอบอีเมล | Gmail webhook → เอเจนต์ประมวลผลอีเมลขาเข้า |
| การแจ้งเตือน build | CI/CD webhook → เอเจนต์ประกาศผล build บน Discord |
| การตรวจสอบข้อมูลรายชั่วโมง | Cron แบบ interval → เอเจนต์ตรวจสอบแดชบอร์ดและแจ้งเตือนความผิดปกติ |
| โพสต์โซเชียลมีเดียตามกำหนด | Cron job → เอเจนต์ร่างและโพสต์เนื้อหาในเวลาที่เหมาะสม |