# create\_schedule

Create a schedule that, each time its cron expression matches, creates a task in `workflow_id` or mails the prompt to `orchestrator_agent_id`.

writes · not idempotent · MCP tool · [Schedule](https://komrad.dev/latest/api/schedule.md)

## Calling it

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

```bash
komrad rpc create-schedule \
  --name '<string>' \
  --cron '<string>' \
  --prompt '<string>' \
  --workflow-id '<uuid>'
```

```json
{
  "name": "create_schedule",
  "arguments": {
    "name": "<name>",
    "cron": "<cron>",
    "prompt": "<prompt>",
    "workflow_id": "<workflow_id>"
  }
}
```

Offered by the komrad MCP server to orchestrator agents.

## Request

### CreateScheduleRequest

| Field | Type | Description |
| --- | --- | --- |
| [`name`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-CreateScheduleRequest-name) | string\* at most 200 characters must not contain control characters | The schedule's name, which is also the title of each task the schedule creates. |
| [`cron`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-CreateScheduleRequest-cron) | string\* must be five whitespace-separated fields, such as '0 9 \* \* 1-5' | The schedule's cron expression, in five fields separated by spaces. |
| [`timezone`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-CreateScheduleRequest-timezone) | string at most 100 characters | The timezone to read the cron expression in. Empty uses the machine's timezone. |
| [`enabled`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-CreateScheduleRequest-enabled) | bool | Whether the schedule starts enabled. |
| [`prompt`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-CreateScheduleRequest-prompt) | string\* at most 50000 characters | The prompt each launched writer starts with, or the mail sent to the orchestrator. |
| [one of](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-CreateScheduleRequest-target)\* |  | What each run does. |
| [`workflow_id`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-CreateScheduleRequest-workflow_id) | uuid | The workflow to create a task in, by id. The writer takes the workflow's directory and flags. |
| [`orchestrator_agent_id`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-CreateScheduleRequest-orchestrator_agent_id) | uuid | The orchestrator to mail the prompt to, by id. |

## Response

### CreateScheduleResponse

| Field | Type | Description |
| --- | --- | --- |
| [`schedule`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-CreateScheduleResponse-schedule) | [Schedule](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-Schedule) | The schedule as created. |

## Types

### Schedule

Schedule is a cron expression that creates a task or mails an orchestrator each time it matches.

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-Schedule-id) | uuid\* | The schedule's id. |
| [`name`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-Schedule-name) | string | The schedule's name. |
| [`cron`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-Schedule-cron) | string | The schedule's cron expression, in five fields. |
| [`timezone`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-Schedule-timezone) | string | The timezone the cron expression is read in. Empty uses the machine's timezone. |
| [`enabled`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-Schedule-enabled) | bool | Whether the schedule is enabled. A disabled schedule keeps its record and never runs. |
| [`prompt`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-Schedule-prompt) | string | The prompt each launched writer starts with, or the mail sent to the orchestrator. |
| [`workflow_id`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-Schedule-workflow_id) | uuid\* | The id of the workflow the schedule belongs to. For an orchestrator schedule, the orchestrator's workflow. |
| [`kind`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-Schedule-kind) | [ScheduleKind](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleKind) | Whether the schedule creates a task or mails an orchestrator. |
| [`orchestrator_agent_id`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-Schedule-orchestrator_agent_id) | uuid | The id of the orchestrator the schedule mails. Set only on an orchestrator schedule. |
| [`next_run_at`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-Schedule-next_run_at) | timestamp | When the cron expression next matches. Unset while the schedule is disabled. |
| [`latest_run`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-Schedule-latest_run) | [ScheduleRun](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleRun) | The schedule's newest run. Unset when the schedule has never run or the run's record has expired. |
| [`recent_runs`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-Schedule-recent_runs) | [ScheduleRun\[\]](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleRun) | The schedule's newest runs, newest first. Set only in `Watch` events. |
| [`archived_at`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-Schedule-archived_at) | timestamp | When the schedule was archived. Unset while the schedule is live. |

### ScheduleRun

ScheduleRun is one time a schedule's cron expression matched, with its state.

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleRun-id) | int64 | The run's id. A higher id is a newer run. |
| [`scheduled_for`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleRun-scheduled_for) | timestamp | The time the cron expression matched for this run. |
| [`state`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleRun-state) | [ScheduleRunState](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleRunState) | The run's state. |
| [`attempt`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleRun-attempt) | int32 | The run's current attempt, counting from one once the run has started. |
| [`max_attempts`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleRun-max_attempts) | int32 | How many attempts the run has before it is discarded. |
| [`finalized_at`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleRun-finalized_at) | timestamp | When the run finished. Unset while the run is waiting or running. |
| [`message`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleRun-message) | string | Why the run was skipped, or the error from its last failed attempt. Empty when the run completed. |

### ScheduleKind

ScheduleKind is what a schedule does each time its cron expression matches.

| Value | Description |
| --- | --- |
| [`orchestrator`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleKind-orchestrator) | Mails the prompt to a running orchestrator. |
| [`task`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleKind-task) | Creates a task in the workflow and launches its writer with the prompt. |

### ScheduleRunState

ScheduleRunState is the state of one schedule run.

| Value | Description |
| --- | --- |
| [`available`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleRunState-available) | Waiting to start. |
| [`pending`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleRunState-pending) | Held back until something releases the run. |
| [`scheduled`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleRunState-scheduled) | Waiting for a later time to start. |
| [`running`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleRunState-running) | Running now. |
| [`retryable`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleRunState-retryable) | Failed an attempt and waiting to try again. |
| [`completed`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleRunState-completed) | Launched the run's agent or sent the run's mail. |
| [`cancelled`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleRunState-cancelled) | Skipped, with the reason in the run's message. |
| [`discarded`](https://komrad.dev/latest/api/schedule/create-schedule.md#komrad-schedule-v1-ScheduleRunState-discarded) | Out of attempts, with the last error in the run's message. |
