Scheduling Automated Agent Runs

How to create, manage, and monitor scheduled agent runs using cron expressions, view run history per schedule, and manually trigger executions.

Agent Manager supports scheduling recurring or one-time agent runs without any external job orchestration. Scheduled runs execute as background jobs and produce the same RunResponse as manually triggered runs, so they work with all the same monitoring and audit tooling.

Common use cases

• Daily report generation (summarize overnight activity, generate executive briefings)
• Periodic data analysis (run analytics agents on a nightly or weekly cadence)
• Automated monitoring alerts (poll data sources and notify on anomalies)
• Batch knowledge base updates (re-ingest and refresh vector content on a schedule)

Creating a schedule

1. Define the schedule payload

   Build a ScheduleDTO with the agent to run, the message to send it, and the recurrence expression:

   {
     "name": "Daily Sales Summary",
     "agentId": "finance_agent",
     "message": "Generate a summary of today's sales data",
     "cronExpression": "0 8 * * *",
     "enabled": true
   }
   
2. Submit the schedule

   curl -X POST http://your-host/api/v1/schedules \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Daily Sales Summary",
       "agentId": "finance_agent",
       "message": "Generate a summary of today'\''s sales data",
       "cronExpression": "0 8 * * *",
       "enabled": true
     }'
   

   The API returns 201 Created with the new schedule including its assigned ID.

Cron expression reference

Schedules use standard five-field cron syntax:

┌───── minute (0-59)
│ ┌───── hour (0-23)
│ │ ┌───── day of month (1-31)
│ │ │ ┌───── month (1-12)
│ │ │ │ ┌───── day of week (0-7, Sunday = 0 or 7)
│ │ │ │ │
* * * * *

Expression	Meaning
0 8 * * *	Every day at 8:00 AM
0 * * * *	Every hour on the hour
30 9 * * 1	Every Monday at 9:30 AM
0 0 1 * *	First day of every month at midnight
*/15 * * * *	Every 15 minutes

Managing schedules

List all schedules (paginated):

GET /api/v1/schedules

Get a specific schedule:

GET /api/v1/schedules/{id}

Update a schedule (change message, recurrence, or enabled state):

curl -X PUT http://your-host/api/v1/schedules/{id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Sales Summary",
    "agentId": "finance_agent",
    "message": "Generate a summary of today'\''s sales data",
    "cronExpression": "0 9 * * *",
    "enabled": true
  }'

Delete a schedule:

DELETE /api/v1/schedules/{id}

Returns 204 No Content on success.

Triggering a schedule manually

To execute a schedule immediately without waiting for its next cron time:

curl -X POST http://your-host/api/v1/schedules/{id}/trigger \
  -H "Authorization: Bearer {token}"

{
  "message": "Schedule execution triggered."
}

Manual triggers enqueue the same background job as an automatic execution.

Viewing run history

To see the execution history for a specific schedule:

GET /api/v1/schedules/{id}/runs

Each entry in the list corresponds to one execution and includes its status, start time, and outcome. You can also monitor background jobs produced by scheduled runs via the Jobs dashboard.

Scheduled runs execute as background jobs. If a scheduled run fails, the job status will show FAILED and the failure reason will be captured in the run record. The schedule itself continues to execute on its defined cadence regardless of individual run outcomes.

Batch jobs

Agent Manager also supports spot batch jobs for one-off bulk operations. View all batch jobs:

GET /api/v1/schedules/batches

Each batch job entry includes its status, progress percentage, estimated cost, and the compute configuration it ran on.

For time-sensitive schedules, use the manual trigger endpoint during testing to verify the agent produces the expected output before relying on the cron schedule in production.