Schedule an agent

A schedule is a persisted cloud trigger attached to one deployed agent by its slug. Each occurrence starts an independent production run with the input object stored on the schedule. Creating, reading, previewing, and cancelling schedules all use the authenticated Agents API.

Before scheduling, deploy the agent and confirm it has a ready build. The API can retain a trigger independently of a build, but a fire cannot start a runnable agent without one.

Preview recurring times

Preview validates the cron expression and IANA timezone and projects upcoming occurrences. It creates no trigger, but it still requires authentication because it is served by the tenant Agents API.

Claude Code with MCP
TypeScript SDK

Ask Claude to call sapiom_dev_agents_cron_preview:

{
  "cron": "0 9 * * 1-5",
  "timezone": "America/Los_Angeles",
  "count": 3
}

The response echoes the cron and timezone and returns occurrences as ISO 8601 instants in UTC. Preview does not apply a schedule’s optional start/end bounds or jitter.

Use the authenticated @sapiom/tools client outside an agent run:

import { createClient } from "@sapiom/tools";

const sapiom = createClient({ apiKey: process.env.SAPIOM_API_KEY! });

const preview = await sapiom.schedules.preview({
  cron: "0 9 * * 1-5",
  timezone: "America/Los_Angeles",
  count: 3,
});

When using the namespace functions directly, you can also rely on the package’s default authenticated transport instead of passing one explicitly.

Call sapiom_dev_agents_schedule with the deployed definition slug:

{
  "definition": "daily-research-brief",
  "kind": "schedule_cron",
  "cron": "0 9 * * 1-5",
  "timezone": "America/Los_Angeles",
  "input": { "topic": "agent reliability" },
  "policy": { "catchupPolicy": "skip", "overlapPolicy": "allow" }
}

import { createClient } from "@sapiom/tools";

const sapiom = createClient({ apiKey: process.env.SAPIOM_API_KEY! });

const schedule = await sapiom.schedules.create({
  definition: "daily-research-brief",
  kind: "schedule_cron",
  cron: "0 9 * * 1-5",
  timezone: "America/Los_Angeles",
  input: { topic: "agent reliability" },
  policy: { catchupPolicy: "skip", overlapPolicy: "allow" },
});

The five-field cron is evaluated in timezone; omitted timezone defaults to UTC. Optional startAt and endAt ISO timestamps bound the recurring window. catchupPolicy: "skip" drops missed slots after downtime; "all" replays them one per sweep until caught up. Overlapping runs are currently allowed. An overlap-suppression mode is not implemented, so the only accepted overlapPolicy is "allow".

Schedule timing is best effort. A due occurrence starts at or shortly after its recorded time; do not use it as a hard real-time clock.

Create a one-off schedule

A one-off stores one future fire and completes after it starts that run:

{
  "definition": "daily-research-brief",
  "kind": "schedule_once",
  "at": "2026-08-10T16:00:00.000Z",
  "input": { "topic": "launch readiness" }
}

Pass that object to sapiom_dev_agents_schedule, or call schedules.create(...) with the same fields. at must be an ISO 8601 timestamp; the schedule input must be a JSON object accepted by the agent’s entry schema when the run starts.

Inspect schedule state and fires

List an agent’s schedules
Section titled “List an agent’s schedules”

Call sapiom_dev_agents_schedule_inspect with the definition slug:
```
{ "definition": "daily-research-brief" }
```
Each summary includes id, kind, status, cron, timezone, and nextFireAt.
Inspect one schedule
Section titled “Inspect one schedule”
```
{ "scheduleId": "<schedule-id>" }
```
Detail adds the stored input, bounds, policy, and recentFires. Each fire record has its scheduled time, state, firedAt terminalization time, and the production executionId it started (or an error when it could not start one). A cancelled pending occurrence becomes skipped, so it has a firedAt timestamp but no execution ID.
Follow a fired run
Section titled “Follow a fired run”

Copy a non-null recentFires[].executionId into sapiom_dev_agents_inspect, or open that execution under the agent’s Runs page. The Agents dashboard observes scheduled executions like other production runs; it does not provide a schedule editor or schedule list.

The SDK equivalents are sapiom.schedules.list(definition), sapiom.schedules.get(scheduleId), and the normal run-inspection flow.

Cancel future occurrences

Call sapiom_dev_agents_schedule_cancel:

{ "scheduleId": "<schedule-id>" }

or await sapiom.schedules.cancel(scheduleId). Cancellation returns status disabled, marks a pending future occurrence skipped, and prevents a recurring schedule from re-arming. It does not cancel a run that already started. Cancellation is final; create a new schedule to reschedule.

Do not confuse schedules with delayed child dispatch

Operation	Ownership	What happens later	Parent behavior
`schedules.create(...)` or the local schedule MCP tool	Standalone control-plane trigger	Starts an independent run of the definition	No parent is linked or resumed
`ctx.sapiom.agents.launch({ at })` inside an agent step	Runtime parent/child dispatch	Starts one linked child run at `at`	Returns a pause-only handle; the child’s terminal result automatically resumes the parent

Delayed child dispatch stores parent lineage and an internal trigger-<id> correlation. Use its returned handle with pauseUntilSignal; do not recreate that correlation with a standalone schedule.

Use signals Declare a durable pause and deliver a human or webhook payload to the matching waiter.

Inspect a run Read the production execution started by a schedule fire.