Daily Tasks¶
Daily Tasks are the product-layer shape for recurring or scheduled agent work. They reuse the SDK cron backend, but add the missing product semantics: user intent, permission profile, run limits, retries, and structured run history.
Layering¶
User intent
|
v
DailyTaskSpec(name, prompt, schedule, workspace, permission_mode, work_dir, timeout_seconds, max_retries, retry_delay_ms)
|
v
CronJob storage and scheduler tick
|
v
AgentRunner.run(prompt, context)
|
v
TaskRun(run_id, task_id, status, timing, error_type)
DailyTaskSpec is the stable input shape for CLI/Gateway/product surfaces. CronJob remains the file-backed execution record. TaskRun is the append-only history item written after every execution attempt. A daily task does not set target; create_job defaults to "new_once" — the first run creates one named conversation and later runs reuse it.
SDK Usage¶
from agentica.cron import CronSchedule, DailyTaskSpec, create_daily_task
spec = DailyTaskSpec(
name="Morning Brief",
prompt="Summarize overnight incidents and list follow-up actions.",
schedule=CronSchedule.at_time(8, 30),
user_id="alice",
workspace="/srv/agentica/workspaces/alice",
permission_mode="read-only", # every run: reads and reports; writes and mutating commands are denied
work_dir="/srv/agentica/projects/alice",
timeout_seconds=60,
max_retries=2,
)
job = create_daily_task(spec)
Failure Visibility¶
Every scheduler attempt writes a TaskRun record with:
status:ok,failed, ortimeouterror_type: named failure class such asTimeoutErrorstarted_at_ms,ended_at_ms, andduration_msattempt: retry attempt numberresultorerror
from agentica.cron import list_task_runs
runs = list_task_runs(job_id=job.id)
latest = runs[0]
print(latest.status, latest.error_type, latest.duration_ms)
Product Rules¶
- Prompts must be self-contained because scheduled runs do not inherit the current chat.
permission_mode/work_dirare the job's mandate: every run uses them, regardless of the tier the host process is in when the job fires. A job created through thecronjobtool records the calling session's tier and directory; the tool only lets the model pick a stricter tier, never a broader one.- If
work_dirno longer exists when the job is due, the scheduler pauses the job instead of running it and setspaused_reason. A job's own run can do the same withcronjob(action="pause", job_id=..., reason=...)when it cannot go on unattended. A paused job is not retried;resume_jobclears the reason. - Use
timeout_secondsfor all unattended tasks. A stuck run should become a visibletimeout, not a silent hang. - Use
max_retriesfor transient failures. Retries are immediate scheduled attempts withretry_delay_ms; after retries are exhausted, recurring jobs wait for their next normal schedule.