create_schedule

Create a recurring agent launch inside a workflow.

Schedulewritesnot idempotentMCP tool

Nothing runs at create time; the agent is spawned when the cron expression next matches, and again on every match after that. The workflow supplies the directory, flags, and shared context each launch uses, so only the prompt and the timing are set here. Create it with enabled false to write it down without arming it, or with hideAgents true to keep its runs out of the panel's sidebar while they still run.

Calling it#

curl -X POST http://127.0.0.1:8787/schedule.v1.ScheduleService/CreateSchedule \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "<name>",
  "cron": "<cron>",
  "prompt": "<prompt>",
  "workflowId": "<workflowId>"
}'

komrad rpc create-schedule \
  --name <string> \
  --cron <string> \
  --prompt <string> \
  --workflow-id <string>

{
  "name": "create_schedule",
  "arguments": {
    "name": "<name>",
    "cron": "<cron>",
    "prompt": "<prompt>",
    "workflowId": "<workflowId>"
  }
}

Offered by the komrad MCP server to orchestrator agents.

Request#

CreateScheduleRequest#

Field	Type	Description
`name`	string	What to list it as, which also becomes the title of each agent it launches. required, at most 200 characters
`cron`	string	When to fire, as five whitespace-separated fields. required
`timezone`	string	Which clock to read that against, blank for the machine's own. at most 100 characters
`enabled`	bool	False to write the schedule down without arming it.
`hideAgents`	bool	True to keep its launches out of the panel's sidebar.
`prompt`	string	The opening prompt each launch is given. required, at most 50000 characters
`workflowId`	string	Which workflow to launch into, whose cwd and flags each agent inherits. required

Response#

CreateScheduleResponse#

Field	Type	Description
`schedule`	Schedule	The schedule as recorded, which has fired nothing yet.

Types#

Schedule#

Field	Type	Description
`id`	string	The handle every other call names this schedule by.
`name`	string	What the panel lists it as.
`cron`	string	Five fields saying when it fires, in the timezone below.
`timezone`	string	Which clock the expression is read against, blank for the machine's own.
`enabled`	bool	Whether it is armed, since a paused schedule keeps its record and stops firing.
`hideAgents`	bool	Whether its launches stay out of the panel's sidebar while still running.
`prompt`	string	The opening prompt every agent it launches is given.
`workflowId`	string	Which workflow its agents are filed under, deciding their directory and flags.
`nextRunAt`	timestamp	When the expression next matches, unset while the schedule is paused.
`promptTruncated`	bool	Whether prompt holds only its opening, which a summary listing returns.
`latestRun`	ScheduleRun	The newest firing still on record, unset when it has never fired or the record has aged out.
`recentRuns`	list of ScheduleRun	The newest firings on record, newest first, which only the watch fills.

ScheduleRun#

ScheduleRun is one firing of a schedule, as the job that carried it out stands.

Field	Type	Description
`id`	int64	The job's own id, which orders firings newest first.
`scheduledFor`	timestamp	Which occurrence of the cron expression this firing stands for.
`state`	ScheduleRunState	Where the firing stands.
`attempt`	int32	Which try this is, starting at one once it has been worked.
`maxAttempts`	int32	How many tries it is given before it is discarded.
`finalizedAt`	timestamp	When it finished, unset while it is still waiting or working.
`message`	string	Why it was skipped or what its last failed attempt said, blank once it has launched.

ScheduleRunState#

ScheduleRunState is where River holds a firing's job.

Value	Description
`SCHEDULE_RUN_STATE_AVAILABLE`	Waiting for a worker to pick it up.
`SCHEDULE_RUN_STATE_PENDING`	Held back from running until something releases it.
`SCHEDULE_RUN_STATE_SCHEDULED`	Queued to become available at a later time.
`SCHEDULE_RUN_STATE_RUNNING`	Being worked right now.
`SCHEDULE_RUN_STATE_RETRYABLE`	Failed an attempt and waiting to try again.
`SCHEDULE_RUN_STATE_COMPLETED`	Launched its agent.
`SCHEDULE_RUN_STATE_CANCELLED`	Skipped on purpose, with the reason in its message.
`SCHEDULE_RUN_STATE_DISCARDED`	Ran out of attempts, with the last error in its message.