Agentuity Documentation

Create platform-managed cron jobs that fire on a schedule and deliver HTTP requests to configured destinations. The schedule service is available via ctx.schedule in agents and c.var.schedule in routes.

Not inside an agent or route?

Use the @agentuity/schedule standalone package to access this service from any Node.js or Bun app without the runtime.

For concepts, cron routes vs platform schedules, and when-to-use guidance, see Schedules.

create(params)

Create a new schedule with optional destinations. The schedule and its destinations are created atomically: if any validation fails, the entire operation is rolled back.

Param	Type	Required	Description
`params`	`CreateScheduleParams`	yes	Schedule creation parameters (see below)

CreateScheduleParams fields:

Field	Type	Required	Description
`name`	`string`	yes	Human-readable name
`expression`	`string`	yes	Cron expression (e.g., `'0 9 * * 1-5'` for weekdays at 9 AM)
`description`	`string`	no	Description of the schedule's purpose
`destinations`	`CreateScheduleDestinationParams[]`	no	Destinations to create alongside the schedule

CreateScheduleDestinationParams fields:

Field	Type	Required	Description
`type`	`'url' \| 'sandbox'`	yes	Destination type
`config`	`Record<string, unknown>`	yes	Type-specific configuration

For 'url' destinations, the config shape is:

{
  url: string;
  headers?: Record<string, string>;
  method?: string;
}

Returns: Promise<ScheduleCreateResult>

interface ScheduleCreateResult {
  schedule: Schedule;
  destinations: ScheduleDestination[];
}
 
interface Schedule {
  id: string;              // Prefixed with sch_
  name: string;
  description: string | null;
  expression: string;      // Cron expression
  due_date: string;        // ISO 8601, next scheduled execution
  created_at: string;
  updated_at: string;
  created_by: string;
}

Example

import { createAgent } from '@agentuity/runtime';
 
const agent = createAgent('ScheduleManager', {
  handler: async (ctx, input) => {
    const result = await ctx.schedule.create({
      name: 'Daily Report',
      description: 'Generate and send daily reports at 9 AM',
      expression: '0 9 * * *',
      destinations: [
        {
          type: 'url',
          config: {
            url: 'https://example.com/reports/generate',
            headers: { 'Authorization': 'Bearer token' },
          },
        },
      ],
    });
 
    ctx.logger.info('Schedule %s created, next run: %s',
      result.schedule.id, result.schedule.due_date);
 
    return { scheduleId: result.schedule.id };
  },
});

list(params?)

List all schedules with optional pagination.

Param	Type	Required	Description
`params`	`object`	no	Pagination options
`params.limit`	`number`	no	Max results (max 500)
`params.offset`	`number`	no	Results to skip

Returns: Promise<ScheduleListResult>

interface ScheduleListResult {
  schedules: Schedule[];
  total: number;
}

Example

const { schedules, total } = await ctx.schedule.list({ limit: 20 });
ctx.logger.info('Showing %d of %d schedules', schedules.length, total);
 
for (const s of schedules) {
  ctx.logger.info('%s: %s (next: %s)', s.name, s.expression, s.due_date);
}

get(scheduleId)

Get a schedule by its ID, including all configured destinations.

Param	Type	Required	Description
`scheduleId`	`string`	yes	Schedule ID (prefixed with `sch_`)

Returns: Promise<ScheduleGetResult>

interface ScheduleGetResult {
  schedule: Schedule;
  destinations: ScheduleDestination[];
}
 
interface ScheduleDestination {
  id: string;           // Prefixed with sdst_
  schedule_id: string;
  type: 'url' | 'sandbox';
  config: Record<string, unknown>;
  created_at: string;
  updated_at: string;
  created_by: string;
}

Example

const { schedule, destinations } = await ctx.schedule.get('sch_abc123');
ctx.logger.info('Schedule: %s, destinations: %d', schedule.name, destinations.length);

update(scheduleId, params)

Update an existing schedule. Only provided fields are modified. If the expression changes, the due_date is automatically recomputed.

Param	Type	Required	Description
`scheduleId`	`string`	yes	Schedule ID
`params`	`UpdateScheduleParams`	yes	Fields to update (all optional)

UpdateScheduleParams fields (all optional):

Field	Type	Description
`name`	`string`	Updated name
`description`	`string`	Updated description
`expression`	`string`	Updated cron expression

Returns: Promise<{ schedule: Schedule }>

Example

const { schedule } = await ctx.schedule.update('sch_abc123', {
  name: 'Nightly Sync',
  expression: '0 0 * * *',
});
 
ctx.logger.info('Updated. Next run: %s', schedule.due_date);

delete(scheduleId)

Delete a schedule and all of its destinations and delivery history.

Param	Type	Required	Description
`scheduleId`	`string`	yes	Schedule ID

Returns: Promise<void>

Destinations

createDestination(scheduleId, params)

Add a new destination to an existing schedule.

Param	Type	Required	Description
`scheduleId`	`string`	yes	Schedule ID
`params`	`CreateScheduleDestinationParams`	yes	Destination type and config

Returns: Promise<{ destination: ScheduleDestination }>

Example

const { destination } = await ctx.schedule.createDestination('sch_abc123', {
  type: 'url',
  config: {
    url: 'https://example.com/webhook',
    headers: { 'X-Source': 'agentuity' },
  },
});
 
ctx.logger.info('Destination added: %s', destination.id);

deleteDestination(destinationId)

Remove a destination from a schedule.

Param	Type	Required	Description
`destinationId`	`string`	yes	Destination ID (prefixed with `sdst_`)

Returns: Promise<void>

getDestination(scheduleId, destinationId)

Get a specific destination by schedule and destination ID.

Returns: Promise<ScheduleDestination>

Delivery History

listDeliveries(scheduleId, params?)

List delivery attempts for a schedule. Each time a schedule fires, one delivery record is created per destination.

Param	Type	Required	Description
`scheduleId`	`string`	yes	Schedule ID
`params`	`object`	no	`{ limit?: number; offset?: number }`

Returns: Promise<ScheduleDeliveryListResult>

interface ScheduleDelivery {
  id: string;
  date: string;                   // ISO 8601 timestamp
  schedule_id: string;
  schedule_destination_id: string;
  status: 'pending' | 'success' | 'failed';
  retries: number;
  error: string | null;
  response: Record<string, unknown> | null;
}

Example

const { deliveries } = await ctx.schedule.listDeliveries('sch_abc123');
for (const d of deliveries) {
  ctx.logger.info('%s: %s (retries: %d)', d.date, d.status, d.retries);
  if (d.error) {
    ctx.logger.error('  Error: %s', d.error);
  }
}

getDelivery(scheduleId, deliveryId, params?)

Get a specific delivery record by its ID. Accepts optional pagination parameters to control the search window.

Returns: Promise<ScheduleDelivery>