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. Schedules operate independently of UI Agent tasks.

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 is not exposed to API callers.

Tool execution and application workers

Ordinary Agents accept the same tools whether started directly or by a Schedule:

“Client function” means a function executed by the API application. It does not require an online browser or phone. Your application may internally call its own Composio account, MCP server, or business service. Rebyte sees the Function contract, not that internal implementation. If you instead give Rebyte the MCP endpoint, Rebyte calls it through the MCP path. MCP and Function tools can be mixed.

No special Schedule tool mode or consumer registration is required. An application worker can use the existing public endpoints. Alternatively, subscribe to Webhooks for Schedule Run lifecycle events and Session or Workflow action_required notifications, then retrieve current state and submit results through the same endpoints below:

1. Poll GET /v1/schedules/:id/runs to discover runs, including automatic triggers. A prepared Run exposes its session_id and turn_id.
2. Read GET /v1/agents/sessions/:sessionId. When it has required_actions, execute the actions belonging to that Run's Turn under the correct application user's authorization. The Session is requires_action; its Turn is waiting; the Schedule Run remains running.
3. Submit results to the same Session. Do not resubmit the scheduled prompt:

POST /v1/agents/sessions/:sessionId/events
Authorization: Bearer <organization-api-key>
OpenAI-Beta: agents=v1
Idempotency-Key: <stable-result-batch-id>
Content-Type: application/json

{
  "events": [{
    "type": "agent.session.input.tool_result",
    "turn_id": "turn_...",
    "call_id": "call_...",
    "success": true,
    "output": "Application function result"
  }]
}

4. Continue until the Run reaches completed, failed, or cancelled. Multiple tool batches can occur in one Turn. A failed tool result uses success: false and error instead of output; it is recorded as a tool failure and the Agent may continue to handle it.

Keep execution receipts in durable application storage, keyed by Session, Turn and Call. If a result acknowledgment is lost, resend the identical batch with its original Idempotency-Key. Reusing the key with different events is rejected. Rebyte deduplicates accepted results; your application remains responsible for idempotency of external effects. A restarted worker can rediscover the same Run and pending calls. No browser connection or SSE stream owns the waiting lifecycle.

A direct Function batch can wait up to 24 hours; partial results do not extend that batch's deadline. The Schedule's total timeout_seconds includes preparation, model execution and waiting, so whichever deadline expires first limits the run. An absent consumer eventually causes failure and releases the Schedule's overlap slot. Cancellation stops the owned Turn; new results after cancellation or expiry are rejected. Replaying an already accepted result receipt remains an idempotent acknowledgment and does not resume a finished Turn. External side effects already performed by your application are not rolled back.

Continuous runs retain the same Session and tool snapshot. Only explicit reset selects a fresh Session. Functions inside Dynamic Workflow use the same Session endpoint; submit each nested result in its own one-event request. A Workflow Agent uses its separate run and result endpoint, as described below.

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.

Workflow targets can use application functions as well as server tools. Poll GET /v1/workflow-agents/runs/:workflow_run_id. If its status is requires_action, execute the pending function and POST its result to /v1/workflow-agents/runs/:workflow_run_id/tool-results. Do not post that result to a Session events endpoint. Follow the Workflow Agent protocol for result bodies, duplicate submissions and event replay.

While the program waits, the Schedule Run remains running and retains its concurrency slot. Waiting survives service restarts and does not depend on an open HTTP connection. The Schedule's total timeout_seconds includes this wait and can expire before the function's 24-hour deadline. Cancellation or Schedule timeout stops the owned program; the overlap slot remains occupied until it finishes cancellation. Completed external effects are not undone.

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. Triggers follow the configured timezone, including daylight-saving changes. When both day-of-month and weekday are restricted, both conditions must match.

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. Missed automatic triggers are eligible for catch-up for 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 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 optional @rebyteai/agent-extensions package exposes Schedules and Workflows using an existing official OpenAI client. Install the verified versions:

pnpm add openai@7.15.0 @rebyteai/agent-extensions@0.3.0

The HTTP examples above work without any Rebyte package.

import OpenAI from 'openai';
import { RebyteExtensions } from '@rebyteai/agent-extensions';

const client = new OpenAI({
  apiKey: process.env.REBYTE_API_KEY,
  baseURL: 'https://api.rebyte.ai/v1',
  maxRetries: 0,
});
const rebyte = new RebyteExtensions(client);
const schedule = await rebyte.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 rebyte.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 rebyte.schedules.runs.list(schedule.id)) {
  console.log(run.status, run.result);
}
await rebyte.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.