Scheduled Tasks

Enterprise

Run AI agent prompts on a cron schedule. Each scheduled task fires a natural-language agent run with full network tool access, timezone support, and execution history.

Overview

A scheduled task runs an AI agent prompt on a recurring cron schedule. Instead of choosing from a fixed set of operation types, you write a natural-language instruction — the same kind of prompt you would type into the AI chat — and the scheduler fires it automatically at the times you define, in the timezone you choose.

When a schedule fires, NetStacks spawns an agent task that runs the prompt through the agent loop with full access to its network tools: it can SSH into devices, query the device inventory, plan and execute MOPs, save reports as documents, send email, and delegate to specialist sub-agents. The result is recorded in execution history so you can review exactly what the agent did on each run.

Scheduled tasks run AI agent prompts

There is one kind of scheduled task: a saved prompt on a cron schedule. There are no separate “backup”, “health check”, or “deployment” task types — you express those operations as prompts (for example, “back up the running-config of every core router and save it as a snapshot”) and the agent carries them out using its tools.

Tasks vs MOPs

Scheduled tasks are best for recurring, open-ended agent work (audits, summaries, periodic checks, routine collection). For a fixed, multi-step change procedure with explicit per-step validation, approval gates, and rollback commands, author a Method of Procedure (MOP) instead. A scheduled task can also be told to run an existing MOP as part of its prompt.

How It Works

Each schedule stores a cron expression and an IANA timezone. The scheduler computes the next fire time (next_run_at) from those two values. When that time arrives, it creates an agent task from the saved prompt and hands it to the agent executor.

Execution lifecycle

The spawned agent task moves through these states:

pending — the task has been created and is waiting for an execution slot
running — the executor acquired a slot and the agent loop is working through the prompt with its tools
completed — the agent finished and produced a result, recorded in the task’s history
failed — the run hit an unrecoverable error (the error message is stored)
cancelled — the run was stopped before it finished (also cancels any sub-agents it had delegated to)

Concurrency is bounded by a semaphore in the executor, so if many schedules fire at once the extra runs wait pending until a slot frees up rather than overwhelming the host or the LLM API.

Tools the agent can use

A scheduled run has the same tool registry as an interactive agent run, including:

SSH command — run commands on managed devices
Device query — look up devices in the inventory
MOP plan / execute / analyze — work with Methods of Procedure
Save document — persist a report, config, or note as an app document
Send email — deliver a summary or alert
List specialists / delegate — hand a sub-job to a specialist or ephemeral child agent

File-editing tools (write / edit / patch) are only registered when AI terminal mode is enabled in settings, and any external MCP tools you have enabled are added on top.

Approvals still apply

Mutating tool calls pause for explicit user approval, the same as an interactive run. If you want a fully unattended schedule, keep the prompt read-only (collect, summarize, report) or pre-approve the relevant actions through your agent configuration.

Task Fields

A scheduled task is defined entirely by these fields:

Field	Required	Description
`name`	Yes	Human-readable label shown in the task list
`prompt`	Yes	The natural-language instruction the agent runs each time
`cron_expression`	Yes	Standard 5-field cron expression (minute hour day-of-month month day-of-week)
`timezone`	No	IANA timezone the cron expression is evaluated in. Defaults to `UTC`
`description`	No	Optional longer note about what the task is for
`enabled`	No	Whether the schedule is active. Defaults to `true`; set to `false` to pause without deleting

Read-only fields returned by the API include id, last_run_at, next_run_at, and created_at.

Enterprise feature

Scheduled tasks are part of the Controller and require an account with the appropriate permission to manage them. The feature is not available in a standalone single-user install.

Creating a Schedule

Open the Scheduled Tasks panel and click New Schedule (or right-click the empty list and choose New Schedule). The dialog has four inputs:

Name — a short label, e.g. Daily network audit.
Prompt — the instruction the agent runs each time, e.g. Check all core routers for interface errors and report anomalies.
Cron Expression — defaults to 0 9 * * * (daily at 09:00). The dialog shows a plain-English description of the expression as you type. See the Cron Expressions reference for syntax.
Timezone — defaults to UTC; pick the zone the cron expression should be read in (e.g. America/New_York).

New schedules are created enabled. Click Create to save; the task appears in the list with its next run time.

Managing existing schedules

Each task row (and its right-click context menu) offers:

Pause / Resume — toggles enabled. A paused task keeps its full configuration and history but will not fire until you resume it.
Edit — change the name, prompt, cron expression, or timezone.
View History — open the execution history for that task.
Delete — cancel all future runs. Past run history is preserved.

Deleting keeps history

Deleting a schedule only stops future runs — the record of past executions remains so you can audit what already happened.

API Reference

Scheduled tasks are managed under /tasks/agent-schedules. All requests are authenticated and scoped to the calling user.

List schedules

GET /tasks/agent-schedules?limit=50&offset=0

Returns either an array of tasks or an object of the form { tasks: [...], total, limit, offset }.

Create a schedule

POST /tasks/agent-schedules
Content-Type: application/json

{
  "name": "Daily network audit",
  "prompt": "Check all core routers for interface errors and report anomalies.",
  "cron_expression": "0 9 * * *",
  "timezone": "America/New_York",
  "enabled": true
}

Get, update, delete

GET    /tasks/agent-schedules/{id}
PUT    /tasks/agent-schedules/{id}
DELETE /tasks/agent-schedules/{id}

Update accepts any subset of the editable fields. Pause and resume are expressed as updates to enabled:

# Pause a schedule
PUT /tasks/agent-schedules/{id}
Content-Type: application/json

{ "enabled": false }

# Resume it
PUT /tasks/agent-schedules/{id}
Content-Type: application/json

{ "enabled": true }

Example task object

{
  "id": "a1b2c3d4-5678-9abc-def0-123456789abc",
  "name": "Daily network audit",
  "description": null,
  "prompt": "Check all core routers for interface errors and report anomalies.",
  "cron_expression": "0 9 * * *",
  "timezone": "America/New_York",
  "enabled": true,
  "last_run_at": "2026-06-15T13:00:00Z",
  "next_run_at": "2026-06-16T13:00:00Z",
  "created_at": "2026-06-01T08:30:00Z"
}

Read-only timing fields

last_run_at and next_run_at are computed by the scheduler from the cron expression and timezone. You do not set them directly — change the schedule by editing cron_expression or timezone.

Prompt Examples

Because the task body is a prompt, you describe the outcome you want and let the agent use its tools to achieve it. Below are common recurring jobs expressed as scheduled-task payloads.

Nightly interface-error audit

audit-schedule.jsonjson

{
  "name": "Nightly interface error audit",
  "prompt": "SSH into every device tagged 'core' and check for interface input/output errors, CRCs, and drops. Summarize any interface above threshold in a table and email the summary to the NOC. If everything is clean, say so in one line.",
  "cron_expression": "0 2 * * *",
  "timezone": "America/New_York",
  "enabled": true
}

Weekly config collection

config-collection-schedule.jsonjson

{
  "name": "Weekly running-config collection",
  "prompt": "For every core and distribution router, capture the running configuration and save it as a config snapshot. Report any device you could not reach and why.",
  "cron_expression": "0 1 * * 0",
  "timezone": "UTC",
  "enabled": true
}

Weekday morning health summary

health-summary-schedule.jsonjson

{
  "name": "Morning network health summary",
  "prompt": "Summarize the current health of all BGP peers, flag any interfaces with errors above threshold, and note any device that looks unreachable. Save the result as a document titled 'Morning Health Summary'.",
  "cron_expression": "0 7 * * 1-5",
  "timezone": "America/Chicago",
  "enabled": true
}

Scheduled MOP run

mop-schedule.jsonjson

{
  "name": "Monthly compliance MOP",
  "prompt": "Run the 'Security baseline compliance check' MOP against all firewalls. If any step reports a deviation, save the full report as a document and email it to security@example.com.",
  "cron_expression": "0 3 1 * *",
  "timezone": "UTC",
  "enabled": true
}

Write prompts like work orders

Be explicit about scope (which devices), the check to perform, and the output you want (a table, an email, a saved document). Clear, bounded prompts produce more reliable unattended runs than vague ones.

Questions & Answers

Q: What does a scheduled task actually run?: A: It runs a saved AI agent prompt. When the schedule fires, the scheduler creates an agent task from the prompt and executes it with the agent’s network tools (SSH, device queries, MOP execution, email, document saving, sub-agent delegation, and any enabled MCP tools). There is only this one task kind — you express backups, audits, deployments, and reports as prompts.
Q: How do I set when a task runs?: A: With a 5-field cron expression plus an IANA timezone. For example 0 2 * * * with America/New_York runs daily at 2:00 AM Eastern. The create/edit dialog shows a plain-English description as you type. See the Cron Expressions guide.
Q: What are the defaults?: A: New schedules default to the cron expression 0 9 * * * (daily at 09:00), timezone UTC, and enabled: true. Name and prompt are required and have no default.
Q: How do I pause a task without losing it?: A: Use Pause in the row actions or context menu, which sets enabled: false. Via the API, send PUT /tasks/agent-schedules/{id} with { "enabled": false }. The task keeps its configuration and history and stops firing until you resume it.
Q: What happens if a run fails?: A: The spawned agent task is marked failed and the error message is stored in its history. The schedule itself stays enabled and will fire again at its next scheduled time. Review the run’s history to see what the agent did before it failed.
Q: Can a scheduled task change device configuration?: A: Yes, but mutating tool calls pause for explicit approval just like an interactive run. For unattended schedules, keep prompts read-only (collect/summarize/report) or pre-approve the actions through your agent configuration.
Q: Can a scheduled task run a MOP?: A: Yes. The agent has MOP plan, execute, and analyze tools, so a prompt can instruct it to run a named MOP and report the result.
Q: Is there a “run now” button?: A: Scheduled tasks fire on their cron schedule. To run the same prompt immediately and interactively, paste it into the AI chat and start an agent run on demand.

Troubleshooting

Task ran at the wrong time

Check the timezone. A task with cron 0 2 * * * in America/New_York runs at 2:00 AM Eastern, which shifts relative to UTC across daylight saving time. Confirm next_run_at on the task matches what you expect, and verify the cron expression with the Cron Expressions reference.

Task never fires

Make sure the task is enabled (a paused task shows “Paused” instead of a next-run time). Confirm the cron expression is a valid 5-field expression — an invalid expression cannot produce a next_run_at.

Runs fail against devices

Open the task’s history and read the agent transcript for the failed run. Common causes are unreachable devices, invalid or expired credentials, or a prompt the agent could not complete with its tools. Tighten the prompt so the agent has an unambiguous, bounded job.

Run stalls waiting for input

If a prompt triggers a mutating action, the agent pauses for approval. For an unattended schedule that should never block, rewrite the prompt to be read-only, or pre-approve the actions in your agent configuration so the run can proceed without a human in the loop.

Long runs and concurrency

Agent runs are bounded by an executor concurrency limit. If a run takes a long time and the schedule fires again, the new run waits in the pending state until a slot frees up rather than running on top of the previous one. Give long-running jobs a wider interval so they do not pile up.

Explore related automation and AI capabilities:

Cron Expressions — syntax reference and common patterns for scheduling tasks
Methods of Procedure (MOPs) — multi-step procedures with validation, approvals, and rollback that a scheduled prompt can run
Task Monitoring — execution status, history, and logs for agent runs
AI Agents — the agent definitions and tools that execute scheduled prompts
AI Chat — run the same prompts interactively and on demand
MCP Servers — add external tools that scheduled agent runs can call