Scheduled Agents

Schedules independently own when an Agent runs. The target owns what runs: ordinary API Agents use model Sessions; Workflow Agents execute an explicitly selected, previously published version. API Schedules never use UI Agent Workspaces, UI Tasks, scheduled_tasks, or schedule_run_log.

Platform → Schedules and /v1/schedules share the same services and validation. Public endpoints authenticate organization API keys: tasks:read for reads and tasks:write for mutations. No OpenAI beta header is required. Platform requires the current organization's admin role.

Ordinary Agent schedules

POST /v1/schedules
Authorization: Bearer <organization-api-key>
Content-Type: application/json

{
  "name": "Daily project follow-up",
  "target": {
    "type": "agent",
    "agent_id": "agent_...",
    "session_mode": "continuous",
    "input": "Review project progress. Compare with previous findings and avoid repeating notifications.",
    "environment": {"type": "none"},
    "vault_ids": []
  },
  "timing": {
    "type": "cron",
    "expression": "0 9 * * 1-5",
    "timezone": "Asia/Shanghai"
  },
  "paused": false,
  "max_runs": 100,
  "timeout_seconds": 600
}

Each trigger creates a separate schedule.run. The session_mode is explicit:

• continuous: this Schedule owns one lazily created Session. Each admitted run submits a new Turn to that Session, retaining its conversation and environment. Different schedules never implicitly share a Session, even with the same Agent.
• isolated: each run gets a fresh Session and optional environment.

Sessions capture the Agent configuration when allocated. Updating an Agent does not change a continuous Session's saved model/instructions/tools. Explicitly POST /v1/schedules/:id/reset-session with {} to have a future run create a new Session from the current Agent configuration. The old Session, conversation and Sandbox remain intact. Reset is refused while a run is active. Schedule deletion also retains execution history and environments; it is not permission to destroy files. Session environment lifecycle and context limits remain the Agents API's existing policies; scheduling does not add unlimited model context.

Environment configuration and selected Vaults are explicit. Omitted environment and Vaults are seeded as none and [] on creation only. Confidential environment setup is encrypted in the schedule and run snapshots, omitted from public reads, and never copied into Temporal arguments/history. Client Function tools are rejected because a scheduled invocation has no online client to answer them. Server tools, MCP, Web Search and environment tools use the existing API runtime.

Workflow schedules

{
  "name": "Calculate daily totals",
  "target": {
    "type": "workflow",
    "workflow_agent_id": "wfa_...",
    "version": 3,
    "input": {"quantity": 4, "price": 7}
  },
  "timing": {"type": "cron", "expression": "0 18 * * *", "timezone": "UTC"}
}

version is required and must already have been published. A new publication does not move the schedule to another version. Input is validated against that exact version's schema. Workflow runs have independent state; there is no implicit conversation context or previous-result injection. The schedule's Run references workflow_run_id, whose existing endpoints provide event replay, output and tools.

The same fixed-code executor runs in a Temporal Activity without an HTTP request lifetime. Automatic Activity replay of program side effects is disabled. Worker loss or ambiguous execution is recorded as failure, not a blind retry of the program. Existing Workflow execution deadlines (300 seconds) still apply even when a schedule permits a longer timeout.

Time and limits

timing is either {type:"cron", expression, timezone} or {type:"once", at:"2026-10-01T09:00:00+08:00"}. One-time timestamps must be in the future when created or changed. Cron uses five numeric fields, including weekday 0–6, with *, lists, ranges and steps. IANA timezones are validated. Temporal owns the actual calendar, timezone/DST behavior and next trigger times. Temporal's calendar semantics apply when both day-of-month and weekday are restricted.

Recurring clock times must be at least 5 minutes apart, including the gap across midnight. */5 * * * * is supported; every-minute expressions and tightly spaced lists/ranges are rejected on both create and update. This conservative validation checks the clock-day independently of date restrictions. Manual “Run now” bypasses the time schedule, but still obeys overlap and lifetime limits.

There is no separate maximum number of calendar days or expiry date. For example, 100 daily runs cover about 100 days; 100 runs every 5 minutes have 8 hours 15 minutes between the first and last trigger. A far-future one-time trigger is allowed.

Creation seeds paused:false, max_runs:100 and timeout_seconds:600 (allowed 10–3600). Limits count admitted executions, including manual and failed executions; skipped triggers do not consume the limit. Exhaustion pauses automatic triggers and blocks further admission. The lifetime limit is at most 100 admitted runs per Schedule; max_runs accepts integers 1–100, and null/unlimited is rejected. A lower limit may be raised up to 100. Editing, pausing/resuming or resetting a Session never resets run_count. After 100 runs, create a new Schedule to continue. A one-time automatic trigger pauses its schedule after admission.

Pause prevents future automatic admission and does not cancel the active run. Manual runs are allowed while paused, but still obey overlap and run limits. The concurrency gate spans the complete model Turn/program, including preparation and cancellation. Overlapping scheduled and manual triggers receive skipped Run records. There is no backlog. Temporal catch-up is limited to one minute.

Endpoints

Target type, identity, version, Session mode, environment and Vault selection are immutable. Create another schedule to change those. PATCH input changes future prompts/program inputs; an already-admitted run keeps its original snapshot. Manual triggers support Idempotency-Key, scoped to organization + Schedule. Repeated keys identify the same trigger, even after configuration edits. The 202 acknowledges durable Temporal acceptance; its Run may briefly return 404 until admission commits. Cancellation stops the specific scheduled Turn, not an unrelated interaction in the same Session. It is asynchronous; poll until terminal. Explicit Session deletion also allows the Schedule to finish cleanup without replacing that Session. Delete is refused during an active run. Run states are preparing, running, completed, failed, cancelled, and skipped.

TypeScript SDK

The SDK exposes client.schedules separately from client.beta.agents and client.workflowAgents. Use a build that includes the Schedules resource.

import Rebyte from '@rebyteai/agent-sdk';

const client = new Rebyte({ apiKey: process.env.REBYTE_API_KEY });
const schedule = await client.schedules.create({
  name: 'Daily project follow-up',
  target: {
    type: 'agent',
    agent_id: 'agent_...',
    session_mode: 'continuous',
    input: 'Review project progress and compare with your previous findings.',
  },
  timing: { type: 'cron', expression: '0 9 * * 1-5', timezone: 'Asia/Shanghai' },
  paused: true,
});
const trigger = await client.schedules.trigger(schedule.id, {
  'Idempotency-Key': 'first-project-review',
});
console.log(trigger.run_id);
// Admission is asynchronous. Poll runs.list or runs.retrieve until terminal.
for await (const run of client.schedules.runs.list(schedule.id)) {
  console.log(run.status, run.result);
}
await client.schedules.resume(schedule.id);

Use schedules.pause, update, resetSession, and delete for lifecycle changes. Use schedules.runs.cancel(scheduleId, runId) to request cancellation of one run. The default client base URL is the Rebyte API; set baseURL for a development server.