Scheduled Triggers

Scheduled triggers let you run agents automatically on a recurring schedule (cron) or at a specific future time (one-time). Scheduled triggers are driven by time and can be used for daily reports, hourly health checks, periodic data syncs, or deferred tasks.

Schedule Types

Cron Expressions (Recurring)

Cron triggers use standard 5-field cron syntax to define recurring schedules:

┌───────────── minute (0–59)
│ ┌───────────── hour (0–23)
│ │ ┌───────────── day of month (1–31)
│ │ │ ┌───────────── month (1–12)
│ │ │ │ ┌───────────── day of week (0–7 or MON–SUN)
│ │ │ │ │
* * * * *

Common examples:

Expression	Description
`0 9 * * *`	Every day at 9:00 AM
`0 9 * * MON-FRI`	Weekdays at 9:00 AM
`/15 * * *`	Every 15 minutes
`0 /2 * *`	Every 2 hours
`0 0 1 * *`	First day of every month at midnight

Trigger Configuration

Option	Type	Required	Default	Description
`name`	`string`	Yes	—	Human-readable name
`description`	`string`	No	—	Description of the trigger's purpose
`enabled`	`boolean`	No	`true`	Whether the trigger is active
`cronExpression`	`string`	One of `cronExpression` or `runAt`	—	5-field cron expression for recurring execution
`cronTimezone`	`string`	No	`UTC`	IANA timezone for cron evaluation
`runAt`	`string`	One of `cronExpression` or `runAt`	—	ISO 8601 timestamp for one-time execution
`messageTemplate`	`string`	No	—	Template with `{{placeholder}}` syntax
`payload`	`object`	No	—	Static JSON payload passed to the agent
`maxRetries`	`number`	No	`1`	Max retry attempts on failure (0–10)
`retryDelaySeconds`	`number`	No	`60`	Seconds between retries (10–3600)
`timeoutSeconds`	`number`	No	`780`	Execution timeout in seconds (30–780)
`runAsUserId`	`string`	No	—	User ID whose identity and credentials are used during execution
`createdBy`	`string`	—	—	Read-only. User ID of the trigger creator, set automatically on creation.

Note

You must specify either cronExpression or runAt, but not both. The system validates this at creation time.

Message Templates

Message templates use {{placeholder}} syntax to interpolate values from the payload:

const weeklyDigest = scheduledTrigger({
  name: 'Weekly Digest',
  cronExpression: '0 8 * * MON',
  payload: {
    reportType: 'weekly',
    includeMetrics: true,
  },
  messageTemplate: 'Generate a {{reportType}} digest. Include metrics: {{includeMetrics}}',
});

When the trigger fires, the agent receives:

A text part with the interpolated message: "Generate a weekly digest. Include metrics: true"
A data part with the full payload object

If messageTemplate is omitted, the agent receives only the JSON-serialized payload.

Retry Configuration

Failed executions are automatically retried based on your configuration:

const resilientTask = scheduledTrigger({
  name: 'Critical Data Sync',
  cronExpression: '0 */4 * * *',
  messageTemplate: 'Sync data from external source',
  maxRetries: 5,           // Retry up to 5 times
  retryDelaySeconds: 120,  // Wait 2 minutes between retries
  timeoutSeconds: 600,     // Each attempt times out after 10 minutes
});

Each retry creates a new conversation with the agent. All conversation IDs are tracked on the invocation record so you can review each attempt.

User-Scoped Execution

By default, scheduled triggers execute without a user identity — tools with user-scoped credentials are skipped. Setting runAsUserId makes the trigger execute as a specific user, enabling access to their connected credentials (e.g., per-user OAuth tokens for GitHub, Slack, or Jira).

Self-Scheduling

Any user with edit permission on a project can create a scheduled trigger that runs as themselves:

POST /manage/tenants/{tenantId}/projects/{projectId}/agents/{agentId}/scheduled-triggers

{
  "name": "My Daily Report",
  "cronExpression": "0 9 * * MON-FRI",
  "messageTemplate": "Generate my daily status report",
  "runAsUserId": "user_abc123"
}

The target user must have use permission on the project. The system validates this at creation time and returns 400 if the user lacks access.

Admin Delegation

Organization admins and owners can create triggers that run on behalf of other users in their org:

POST /manage/tenants/{tenantId}/projects/{projectId}/agents/{agentId}/scheduled-triggers

{
  "name": "Team Member Daily Sync",
  "cronExpression": "0 8 * * MON-FRI",
  "messageTemplate": "Sync {{source}} data for today",
  "payload": { "source": "Jira" },
  "runAsUserId": "user_target456"
}

Only org admins/owners can set runAsUserId to a different user. Regular users with edit permission can only set it to themselves.

Runtime Permission Checks

The system verifies the target user's project access before every execution. If the user has lost access since the trigger was created, the invocation fails with a clear error rather than executing without proper authorization.

Legacy Behavior

Triggers without runAsUserId (including all existing triggers) continue to work exactly as before — executing without a user identity. No migration or backfill is needed.

Invocation Tracking

Every scheduled execution creates an invocation record with full observability:

Field	Description
Status	`pending` → `running` → `completed`, `failed`, or `cancelled`
Scheduled For	The time the invocation was scheduled to run
Started At	When execution actually began
Completed At	When execution finished
Attempt Number	Current attempt (1-based, increments on retry)
Conversation IDs	All conversations created across attempts
Idempotency Key	Ensures exactly-once execution

Invocation Statuses

Manual Operations

Run Now

Trigger an immediate execution of any scheduled trigger, regardless of its schedule:

POST /manage/tenants/{tenantId}/projects/{projectId}/agents/{agentId}/scheduled-triggers/{id}/run

This creates a new invocation scheduled for the current time and executes it immediately with the trigger's configured payload, message template, and retry settings. If the trigger has a runAsUserId, the execution uses that user's identity and credentials. For admin-delegated triggers (where runAsUserId differs from the caller), only org admins/owners can invoke "Run Now".

Rerun a Past Invocation

Rerun any completed, failed, or cancelled invocation:

POST /manage/tenants/{tenantId}/projects/{projectId}/agents/{agentId}/scheduled-triggers/{id}/invocations/{invocationId}/rerun

This creates a new invocation using the same trigger configuration and executes it immediately. The same delegation permission rules apply as for "Run Now".

Cancel an Invocation

Cancel a pending or running invocation:

POST /manage/tenants/{tenantId}/projects/{projectId}/agents/{agentId}/scheduled-triggers/{id}/invocations/{invocationId}/cancel

Note

Completed and failed invocations cannot be cancelled.

View Upcoming Runs

See all pending and running invocations across all scheduled triggers for an agent:

GET /manage/tenants/{tenantId}/projects/{projectId}/agents/{agentId}/scheduled-triggers/upcoming-runs

Next Steps

Define in Code

Create scheduled triggers using the TypeScript SDK.

Webhook Triggers

For event-driven execution from external services, use webhook triggers.

Chat API

For synchronous conversations, use the Chat API.

Define in Code

Webhook Triggers

Chat API

On this page