Chuyển tới nội dung chính

Scheduled Tasks

Chay cac AI Agent theo lich dinh ky (cronjob). Ket qua duoc gui den nhieu kenh (DB, Discord, Slack...) thong qua webhook.

Luong Hoat Dong​

1. Admin tao task (chon agent, viet prompt, dat lich, cau hinh webhook)
        |
2. APScheduler trigger theo cron schedule
        |
3. Redis distributed lock (chi 1 node chay khi multi-node)
        |
4. Agent duoc invoke voi input_message
        |
5. Thu thap ket qua (text output tu agent)
        |
6. Fan-out webhook (gui dong thoi den tat ca kenh da cau hinh)
   |           |            |
   DB       Discord      Slack      ...
        |
7. Luu run history (status, duration, notification results)
        |
8. Tao chat session (user co the xem tren frontend)

Khi Update/Delete Task​

Admin update task tren Node A
  -> Sync APScheduler local
  -> Redis PUBLISH "scheduled_task:sync"
  -> Tat ca nodes nhan message -> reload task tu DB -> re-register cron

Huong Dan Cai Dat​

1. Tao Task qua Admin UI​

Truy cap /admin/scheduled-tasks -> click Create Task.

General

  • Task ID: optional, tu dong sinh neu de trong (e.g. morning-report-vn)
  • Name: ten hien thi
  • Active: bat/tat

Agent

  • Agent: chon agent se chay task
  • Target User ID: user_id se nhan ket qua (hien tren frontend cua user do)
  • Input Message: prompt gui cho agent moi lan chay
  • System Prompt Override: (optional) bo sung chi dan rieng cho task

Schedule

  • Type: Daily / Weekly / Monthly / Cron
  • Time: gio chay (e.g. 07:00)
  • Day of Week: cho weekly (0=Sun, 1=Mon...)
  • Day of Month: cho monthly
  • Cron Expression: cho cron type (e.g. */5 * * * * = moi 5 phut, 0 7 * * 1-5 = 7h sang thu 2-6)
  • Timezone: mac dinh Asia/Ho_Chi_Minh

Notifications (Webhooks)

Moi webhook can:

  • Name: ten dinh danh (e.g. signal_output, discord)
  • URL: endpoint nhan du lieu
  • Format: cach build body (Raw / Discord / Slack / Telegram / Template)
  • Headers: (optional) e.g. X-Api-Key cho internal endpoint

2. Tao Task qua API​

curl -X POST /v2/admin/scheduled-tasks/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "morning-report-vn",
    "name": "Morning Market Report",
    "agent_id": "simplize",
    "input_message": "Hay tom tat 3 diem noi bat nhat cua TTCK VN hom nay.",
    "schedule_type": "daily",
    "schedule_time": "07:00",
    "timezone": "Asia/Ho_Chi_Minh",
    "target_user_id": "45",
    "webhooks": [
      {
        "name": "signal_output",
        "url": "http://localhost:8080/v2/signal-outputs/ingest",
        "format": "raw",
        "headers": {"X-Api-Key": "your-internal-key"}
      },
      {
        "name": "discord",
        "url": "https://discord.com/api/webhooks/xxx/yyy",
        "format": "discord"
      }
    ]
  }'

3. Chay Thu (Run Now)​

UI: click nut Run tren row task.

API:

curl -X POST /v2/admin/scheduled-tasks/morning-report-vn/run \
  -H "Authorization: Bearer $TOKEN"

4. Xem Lich Su​

UI: click nut History -> click tung row de xem detail (output markdown, notification results, error).

API:

curl /v2/admin/scheduled-tasks/morning-report-vn/runs?limit=10 \
  -H "Authorization: Bearer $TOKEN"

5. Clone Task​

Click nut Clone tren row task -> form tao moi voi du lieu copy tu task goc.

Webhook Formats​

raw (default)​

Gui nguyen payload JSON. Dung cho internal endpoint (signal_output ingest).

discord​

Gui dang embed message voi title, description, footer. Chi can paste Discord webhook URL.

slack​

Gui dang blocks (header + section + context). Dung voi Slack Incoming Webhook.

telegram​

Gui dang text voi Markdown parse. Can them chat_id trong webhook config.

template​

Custom body voi placeholders:

{
  "format": "template",
  "body_template": {
    "text": "{{task_name}}: {{content}}",
    "channel": "#reports"
  }
}

Variables: task_id, task_name, run_id, user_id, output_type, content, va cac key trong metadata.

Them Format Moi​

Tao function trong notification/formatter.py:

@register("my_format")
def format_my(payload: NotificationPayload, config: Dict) -> Dict[str, Any]:
    return {"message": extract_text(payload.content)}

Cau Hinh Moi Truong​

# .env
INTERNAL_API_KEY=your-secret-key    # Bao ve webhook ingest endpoint
  • Endpoint /v2/signal-outputs/ingest yeu cau header X-Api-Key
  • NotificationDispatcher tu dong inject key vao tat ca webhook requests
  • Khong set key = bypass auth (dev mode)

Multi-Node​

  • Distributed Lock: Redis SET NX dam bao moi task chi chay 1 lan du nhieu nodes cung trigger
  • Cross-Node Sync: Redis pub/sub broadcast khi create/update/delete task -> tat ca nodes tu dong cap nhat APScheduler

Signal Outputs​

Xem ket qua output tai /admin/signal-outputs:

  • Filter: theo ticker, event type, date, source, status
  • Detail: click row de xem full data (layer1/2/3 results, signal factors...)
  • Status flow: new -> processing -> completed / failed (update boi cac job xu ly sau)