Create Schedule

Example scheduler server

Install the runtime (including scheduler dependencies) and SQLite support:

uv pip install -U "agno[os]" sqlalchemy
export OS_SECURITY_KEY="your-agentos-key"

Save as schedule_api.py and run python schedule_api.py. This function-only workflow needs no model key:

from agno.db.sqlite import SqliteDb
from agno.os import AgentOS
from agno.workflow import Step, StepInput, StepOutput, Workflow


def echo(step_input: StepInput) -> StepOutput:
    return StepOutput(content=str(step_input.input))


db = SqliteDb(db_file="tmp/schedule-api.db")
workflow = Workflow(id="scheduled-echo", db=db, steps=[Step(name="Echo", executor=echo)])
agent_os = AgentOS(
    db=db,
    workflows=[workflow],
    scheduler=True,
    scheduler_base_url="http://127.0.0.1:7777",
)
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="schedule_api:app", host="127.0.0.1", port=7777)

Creating this schedule enables it and schedules execution every day at 09:00 UTC:

curl --fail-with-body http://127.0.0.1:7777/schedules \
  -H "Authorization: Bearer $OS_SECURITY_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Daily echo","cron_expr":"0 9 * * *","timezone":"UTC","endpoint":"/workflows/scheduled-echo/runs","payload":{"message":"Scheduled hello"}}'

Keep its returned id for the schedule APIs. endpoint must be a local path, with no full URL, whitespace or control characters. Target a served code component or an available published database component; draft-only and archived database targets return 409.

Scheduler prerequisites

Configure an AgentOS-level database with schedule methods. The example scheduler server uses SQLite. Database-backed schedule CRUD is available without starting the scheduler; execution requires scheduler=True, a running application lifespan and a scheduler_base_url matching the server's address.

Owners come from authenticated identity. Configured authorization uses schedules:read, schedules:write and schedules:delete. Creating, repointing, enabling or triggering a run schedule also requires permission to run its target. Non-run targets require admin permission when that authorization is enforced. An inaccessible record can return 404; insufficient permission returns 403.

For run endpoints, the executor sets stream=false and background=true, forwards the schedule owner and discards payload user overrides and version pins. See Scheduler.

curl --request POST 'https://example.com/schedules' \  --header 'Content-Type: application/json' \  --data-raw '{"name":"string","cron_expr":"string","endpoint":"string"}'

{  "id": "string",  "user_id": "string",  "name": "string",  "description": "string",  "method": "string",  "endpoint": "string",  "payload": {},  "cron_expr": "string",  "timezone": "string",  "timeout_seconds": 0,  "max_retries": 0,  "retry_delay_seconds": 0,  "enabled": true,  "next_run_at": 0,  "managed_by": "string",  "target_type": "string",  "target_id": "string",  "disabled_reason": "string",  "created_at": 0,  "updated_at": 0}

{  "detail": [    {      "loc": [        "string"      ],      "msg": "string",      "type": "string",      "input": null,      "ctx": {}    }  ]}