Scheduling

Agents can create time-based triggers to proactively send messages or execute tasks. Schedules persist across restarts and deliver results via any configured gateway.

Overview

Scheduling lets agents handle use cases like:

“Remind me to check deployment status tomorrow at 9am”
“Send me a daily standup prompt on weekdays”
“Follow up on this issue in 2 hours”

Schedule Types

Type	Description	Example
One-shot (`at`)	Fire once at a specific time	`2026-02-01T09:00:00Z`
Interval (`every`)	Repeat every N seconds	`3600` (hourly)
Cron	Standard cron expression	`0 9 * * MON-FRI` (9am weekdays)

Schedule Tool

A single built-in schedule tool handles all scheduling operations via an action parameter:

Action	Description
`create`	Create a new schedule. The agent specifies the timing, destination, and payload.
`list`	List all active schedules for the current agent.
`cancel`	Cancel an active schedule by its ID.

spec:
  tools:
    - type: builtin
      name: schedule

Payload Types

Type	Description
`message`	Send text directly (no LLM call)
`task`	Execute with agent tools, summarize results

Example Scenarios

One-Time Reminder

User: “Remind me to review the PR in 2 hours”
Agent calls schedule with action: "create", at: "2026-01-30T16:00:00Z"
Two hours later, user receives: “Reminder: review the PR”

Recurring Prompt

User: “Send me a daily standup prompt at 9am on weekdays”
Agent calls schedule with action: "create", cron: "0 9 * * MON-FRI"
Every weekday at 9am, user receives the prompt
User replies, and the conversation continues naturally

Scheduled messages inject into the active session for a (chat_id, agent) pair if one exists. If not, a new session is created. This means scheduled messages appear in the same conversation as user messages — enabling natural follow-up.

Storage

Schedules are persisted as YAML files:

.duragent/
├── schedules/
│   ├── sched_01HQXYZ.yaml      # Schedule definition
│   └── runs/
│       └── sched_01HQXYZ.jsonl  # Run history

Schedule File Format

id: reminder-abc123
agent: my-assistant
created_by_session: session_xyz
destination:
  gateway: telegram
  chat_id: "123456789"
schedule:
  at:                                    # one-shot
    at: "2026-01-30T16:00:00Z"
  # or:
  # cron:                                # recurring
  #   expr: "0 9 * * MON-FRI"
payload:
  message:
    message: "Reminder: review the PR"

Process-Linked Schedules

A schedule can be linked to a background process by passing process_handle when creating it. When the linked process exits (completes, fails, times out, or is killed), all schedules with that process_handle are automatically cancelled.

This is useful for the watch pattern, where a recurring schedule monitors a background process. Without process_handle, the watch schedule would keep firing after the process exits until the next poll notices it’s done.

Retry

Schedules support optional retry with exponential backoff and jitter for transient failures (e.g., LLM provider 503).

Duragent Guide