Run an agent on a schedule

An agent schedule creates a normal objective on a recurring cadence. Cadenya owns the timer, timezone, overlap policy, and objective inputs, so your application does not need its own cron worker.

What you need

A published agent with at least one variation.
A first user message or a firstUserMessageTemplate on every variation the schedule can select.
Valid system prompt data when the agent defines systemPromptDataSchema.

Create a schedule

Open the agent and select Schedules. Click Add Schedule. Enter a name such as Weekday attendee sample, then configure the objective input:

Field	Example	Behavior
First user message	`Create one attendee record with a name, email, company, city, and country.`	Explicit message for every fired objective
First user message data	Optional JSON	Renders the selected variation’s first user message template when no explicit message is set
System prompt data	JSON that satisfies the agent schema	Appears when the agent defines a system prompt data schema

Under Schedule, choose:

Presets for a common cadence.
Custom to add one or more Calendar rules or Interval rules.

Set the timezone to America/New_York. For a weekday 9:00 AM digest, add a calendar rule with hour 9, minute 0, and day of week 1 through 5.

Create Schedule form for a weekday attendee sample with America New York timezone and the Weekdays at 9 AM preset — The schedule form combines objective input, cadence, variation, and overlap policy

Choose variation and overlap behavior

The lower configuration card contains:

Control	Default	Meaning
Variation	Empty	The agent’s Random or Feedback Driven mode selects one on every fire
Allow concurrent runs	Off	A fire is skipped while the previous objective from this schedule is still running

Pin a variation when every scheduled run must use one exact configuration. Leave it empty when scheduled traffic should participate in the agent’s normal variation sampling. Turn on concurrent runs only when overlapping objectives are safe and intentional.

Create the same schedule with the SDK

const schedule = await client.agents.schedules.create(agentId, {
  workspaceId,
  metadata: {
    name: 'Weekday attendee sample',
    externalId: 'weekday-attendee-sample',
  },
  spec: {
    firstUserMessage:
      'Create one attendee record with a name, email, company, city, and country.',
    schedule: {
      timezone: 'America/New_York',
      calendars: [
        {
          hour: [{ start: 9 }],
          minute: [{ start: 0 }],
          dayOfWeek: [{ start: 1, end: 5 }],
        },
      ],
    },
    overlapPolicy: 'OVERLAP_POLICY_SKIP',
  },
});

console.log(schedule.state, schedule.info?.nextFireAt);

The schedule starts in STATE_ACTIVE.

Use an interval

An interval fires every duration from a stable anchor:

const hourly = await client.agents.schedules.create(agentId, {
  workspaceId,
  metadata: {
    name: 'Hourly sweep',
    externalId: 'hourly-sweep',
  },
  spec: {
    firstUserMessage:
      'Check for stalled tickets and identify their owners.',
    schedule: {
      timezone: 'America/New_York',
      intervals: [{ every: '3600s' }],
    },
    overlapPolicy: 'OVERLAP_POLICY_SKIP',
  },
});

The shortest supported interval is 60s. An optional offset shifts the fire within that interval and must be shorter than every. Calendar and interval rules are ORed. A schedule fires whenever any configured rule matches.

Inspect fires

The Schedules table shows:

Cadence
Status
Next fire
Last fire
Runs

When a schedule fires, open its linked Last fire or the agent’s Objectives tab. The objective snapshot includes configSnapshot.agentSchedule, so it records the schedule and selected variation used at creation. From code:

const current = await client.agents.schedules.retrieve(
  agentId,
  schedule.metadata.id,
  { workspaceId },
);

console.log({
  nextFireAt: current.info?.nextFireAt,
  lastFireAt: current.info?.lastFireAt,
  lastObjectiveId: current.info?.lastObjectiveId,
  lastSkipReason: current.info?.lastSkipReason,
  totalFires: current.info?.totalFires,
});

Filter objective history by schedule:

for await (const objective of client.objectives.list({
  workspaceId,
  agentScheduleId: schedule.metadata.id,
})) {
  console.log(objective.metadata.id, objective.state);
}

Pause, resume, or archive

Open the row menu to Pause, Resume, Archive, or Delete. The same lifecycle is explicit in the SDK:

await client.agents.schedules.pause(
  agentId,
  schedule.metadata.id,
  { workspaceId },
);

await client.agents.schedules.resume(
  agentId,
  schedule.metadata.id,
  { workspaceId },
);

await client.agents.schedules.archive(
  agentId,
  schedule.metadata.id,
  { workspaceId },
);

Paused schedules retain their history and can resume. Archived schedules are terminal and cannot resume.

An unpublished agent cannot run scheduled objectives. Cadenya pauses the underlying timers for its active schedules and reconciles them when the agent is published again.

Configure variations

Decide whether each fire samples a candidate or pins one.

How objectives work

Inspect the snapshot and event timeline created by every fire.

Getting Started

Build with the SDK

Tool Sets

Agents

Objectives

Callbacks

Memory

Secrets

Concepts

Use Cases

Run an agent on a schedule

What you need

Create a schedule

Choose variation and overlap behavior

Create the same schedule with the SDK

Use an interval

Inspect fires

Pause, resume, or archive

Configure variations

How objectives work

​What you need

​Create a schedule

​Choose variation and overlap behavior

​Create the same schedule with the SDK

​Use an interval

​Inspect fires

​Pause, resume, or archive

Configure variations

How objectives work

What you need

Create a schedule

Choose variation and overlap behavior

Create the same schedule with the SDK

Use an interval

Inspect fires

Pause, resume, or archive