# How to Manage Scheduling in Agent Zero: A Complete Guide to Task Automation

> Master Agent Zero scheduling with this guide. Learn to manage recurring, one-off, and timestamp tasks via Python API, CLI, or HTTP endpoints for efficient automation.

- Repository: [Agent Zero/agent-zero](https://github.com/agent0ai/agent-zero)
- Tags: how-to-guide
- Published: 2026-02-23

---

**Agent Zero includes a built-in task scheduler that supports cron-style recurring tasks, ad-hoc one-off executions, and planned timestamp-based tasks, all manageable via Python API, CLI tools, or HTTP endpoints.**

Agent Zero is an open-source AI agent framework that ships with a lightweight, file-backed task scheduler for automating background operations. Whether you need to run maintenance scripts on a schedule, trigger one-off agent workflows, or plan tasks for specific future timestamps, the scheduling system in Agent Zero provides thread-safe persistence and multiple interfaces for management.

## Understanding the TaskScheduler Architecture

The scheduling system centers around the **`TaskScheduler`** class, implemented as a singleton in [`python/helpers/task_scheduler.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/task_scheduler.py). This design ensures that only one scheduler instance manages the task queue across the entire application lifecycle.

To access the global instance, use the factory method:

```python
from python.helpers.task_scheduler import TaskScheduler

scheduler = TaskScheduler.get()

```

The singleton holds two critical components:
- A **`SchedulerTaskList`** that manages persistence of tasks to [`usr/scheduler/tasks.json`](https://github.com/agent0ai/agent-zero/blob/main/usr/scheduler/tasks.json)
- A registry of currently running **`DeferredTask`** objects tracking active executions

### Persistence and Thread Safety

All tasks are stored as JSON in [`usr/scheduler/tasks.json`](https://github.com/agent0ai/agent-zero/blob/main/usr/scheduler/tasks.json). The **`SchedulerTaskList.get()`** method (lines 70-80 of [`task_scheduler.py`](https://github.com/agent0ai/agent-zero/blob/main/task_scheduler.py)) handles lazy initialization, creating the file if it does not exist.

Thread-safe updates are guaranteed through **`SchedulerTaskList.update_task_by_uuid()`** (lines 41-71), which acquires an internal lock before writing to disk. This prevents race conditions when multiple agents or API calls modify the schedule simultaneously.

## Task Types and Models

Agent Zero supports three distinct task types, all inheriting from `BaseTask` in [`python/helpers/task_scheduler.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/task_scheduler.py). Each type supports lifecycle hooks (`on_run`, `on_success`, `on_error`, `on_finish`) and common fields including `uuid`, `name`, `state`, `system_prompt`, and `prompt`.

### ScheduledTask (Cron-Style Recurring)

**`ScheduledTask`** implements cron-style scheduling through a `TaskSchedule` object containing minute, hour, day, month, and weekday fields. When the scheduler tick matches the pattern, the task executes.

Source: `ScheduledTask` class definition, lines 88-104 of [`task_scheduler.py`](https://github.com/agent0ai/agent-zero/blob/main/task_scheduler.py).

### AdHocTask (One-Off Execution)

**`AdHocTask`** represents single-shot tasks triggered manually or by external events. It extends `BaseTask` with a unique `token` field for idempotency checks.

Source: `AdHocTask` class, lines 40-48 of [`task_scheduler.py`](https://github.com/agent0ai/agent-zero/blob/main/task_scheduler.py).

### PlannedTask (Timestamp-Based)

**`PlannedTask`** executes at specific UTC timestamps defined in a `TaskPlan` structure. It tracks state transitions through `todo`, `in_progress`, and `done` phases, making it ideal for deadline-driven workflows.

Source: `PlannedTask` class, lines 70-78 of [`task_scheduler.py`](https://github.com/agent0ai/agent-zero/blob/main/task_scheduler.py).

## The Scheduler Tick Loop

Task execution is driven by the **`TaskScheduler.tick()`** method, invoked periodically by the background job loop in [`python/helpers/job_loop.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/job_loop.py) (default interval: every minute).

The tick process follows this sequence:

1. **Fetch due tasks** via `SchedulerTaskList.get_due_tasks()` (lines 84-90), which filters for tasks where `check_schedule()` returns `True` and state is `IDLE`.

2. **Execute via `_run_task()`** (lines 11-57), which:
   - Atomically marks the task `RUNNING` using `update_task_checked`
   - Creates or reuses an `AgentContext` for the task
   - Streams the user-provided prompt to a fresh agent instance
   - Persists results and transitions state back to `IDLE` (or `ERROR` on exception)

The background loop ensures that scheduled tasks run even when no user is actively interacting with the agent, making the system suitable for production automation.

## Managing Tasks with SchedulerTool

For programmatic control, Agent Zero provides **`SchedulerTool`** in [`python/tools/scheduler.py`](https://github.com/agent0ai/agent-zero/blob/main/python/tools/scheduler.py), which exposes high-level methods that map to the core scheduler API.

### Creating a Scheduled Task

```python
from python.tools.scheduler import SchedulerTool
from agent import Agent

# Assume `agent` is a live Agent instance

scheduler = SchedulerTool(agent=Agent())
await scheduler.create_scheduled_task(
    name="nightly-backup",
    system_prompt="You are a backup script executor",
    prompt="Run `tar -czf /backups/daily.tar.gz /mydata` and report success.",
    schedule={"minute": "0", "hour": "2", "day": "*", "month": "*", "weekday": "*"},
    dedicated_context=True,
)

```

This creates a cron-style task running daily at 02:00 UTC. The `dedicated_context=True` flag forces a fresh chat context for isolation.

### Running Tasks Immediately

```python
await scheduler.run_task(uuid="123e4567-e89b-12d3-a456-426614174000")

```

The tool verifies the task isn't already running, then invokes `TaskScheduler.run_task_by_uuid()` and returns a `Response` when the agent completes.

### Waiting for Completion

```python
await scheduler.wait_for_task(uuid="123e4567-e89b-12d3-a456-426614174000")

```

Blocks for up to 5 minutes (configurable) until the task state transitions from `RUNNING`, returning a formatted summary of results.

## HTTP API Endpoints for Remote Scheduling

Agent Zero exposes the scheduler functionality via HTTP-style endpoints in `python/api/`, enabling remote management without direct Python imports.

| Endpoint | Method | Purpose | Implementation |
|----------|--------|---------|----------------|
| `/scheduler/tasks` | GET | List all tasks | [`scheduler_tasks_list.py`](https://github.com/agent0ai/agent-zero/blob/main/scheduler_tasks_list.py) (lines 12-23) |
| `/scheduler/task/create` | POST | Create scheduled/ad-hoc/planned task | [`scheduler_task_create.py`](https://github.com/agent0ai/agent-zero/blob/main/scheduler_task_create.py) (lines 15-46) |
| `/scheduler/task/run` | POST | Execute task by UUID/name | [`scheduler_task_run.py`](https://github.com/agent0ai/agent-zero/blob/main/scheduler_task_run.py) (lines 13-35) |
| `/scheduler/task/update` | PATCH | Modify fields (cron, state, plan) | [`scheduler_task_update.py`](https://github.com/agent0ai/agent-zero/blob/main/scheduler_task_update.py) (lines 12-30) |
| `/scheduler/task/delete` | DELETE | Remove task | [`scheduler_task_delete.py`](https://github.com/agent0ai/agent-zero/blob/main/scheduler_task_delete.py) (lines 11-28) |
| `/scheduler/tick` | POST | Manually trigger scheduler tick | [`scheduler_tick.py`](https://github.com/agent0ai/agent-zero/blob/main/scheduler_tick.py) (lines 5-14) |

These endpoints forward to the same `TaskScheduler` methods used by the Python tool, ensuring consistent behavior across interfaces.

### Example API Usage

```bash

# List all tasks

curl -X GET https://your-agent-host/api/scheduler/tasks

# Create a new scheduled task

curl -X POST https://your-agent-host/api/scheduler/task/create \
     -H "Content-Type: application/json" \
     -d '{
           "name":"hourly-report",
           "system_prompt":"You are a reporting bot",
           "prompt":"Generate the sales report for the last hour.",
           "schedule":{"minute":"*/60","hour":"*","day":"*","month":"*","weekday":"*"},
           "dedicated_context":false
         }'

# Trigger the scheduler tick (normally run automatically)

curl -X POST https://your-agent-host/api/scheduler/tick

```

## Background Job Loop and Persistence

The scheduler relies on [`python/helpers/job_loop.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/job_loop.py) to drive the tick loop. This background thread wakes every minute (configurable) and invokes `TaskScheduler.tick()`, ensuring that cron-style tasks trigger even when the main agent is idle.

State changes are persisted through [`python/helpers/state_monitor_integration.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/state_monitor_integration.py), which marks the UI dirty when tasks change, triggering front-end refreshes. Chat contexts for scheduled tasks are temporarily saved via [`python/helpers/persist_chat.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/persist_chat.py), allowing tasks to resume with full conversation history if interrupted.

## Summary

- **Agent Zero** provides a built-in task scheduler supporting **cron-style**, **ad-hoc**, and **planned** task types.
- The **`TaskScheduler`** singleton in [`python/helpers/task_scheduler.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/task_scheduler.py) manages persistence to [`usr/scheduler/tasks.json`](https://github.com/agent0ai/agent-zero/blob/main/usr/scheduler/tasks.json) with thread-safe updates.
- Three task models—**`ScheduledTask`**, **`AdHocTask`**, and **`PlannedTask`**—inherit from `BaseTask` and support lifecycle hooks.
- The **tick loop** (driven by [`python/helpers/job_loop.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/job_loop.py)) checks for due tasks every minute and executes them via `_run_task()`.
- Manage tasks programmatically via **`SchedulerTool`** ([`python/tools/scheduler.py`](https://github.com/agent0ai/agent-zero/blob/main/python/tools/scheduler.py)) or remotely through **HTTP API endpoints** in `python/api/`.

## Frequently Asked Questions

### What file format does Agent Zero use to store scheduled tasks?

Agent Zero persists all scheduled tasks as JSON in [`usr/scheduler/tasks.json`](https://github.com/agent0ai/agent-zero/blob/main/usr/scheduler/tasks.json). The `SchedulerTaskList` class handles atomic writes with internal locking to prevent corruption during concurrent updates.

### How does Agent Zero prevent scheduled tasks from running simultaneously?

The `TaskScheduler` maintains a registry of running `DeferredTask` objects. Before executing a task, the `_run_task()` method atomically checks and updates the task state from `IDLE` to `RUNNING`. If a task is already running, subsequent calls will skip execution until the state returns to `IDLE`.

### Can I trigger the scheduler manually instead of waiting for the background loop?

Yes. While [`python/helpers/job_loop.py`](https://github.com/agent0ai/agent-zero/blob/main/python/helpers/job_loop.py) automatically invokes `TaskScheduler.tick()` every minute, you can manually trigger a tick via the `SchedulerTool` or by calling the HTTP endpoint `POST /scheduler/tick` (implemented in [`python/api/scheduler_tick.py`](https://github.com/agent0ai/agent-zero/blob/main/python/api/scheduler_tick.py)).

### What is the difference between dedicated_context and shared context in scheduled tasks?

When creating a task via `SchedulerTool.create_scheduled_task()`, setting `dedicated_context=True` forces the scheduler to create a fresh `AgentContext` for each execution, ensuring isolation from other conversations. When `False`, the task may reuse existing contexts depending on the agent configuration, allowing for continuity across related operations.