Scheduled agent tasks

Server SDK 2.5.0 lets a short Function submit work to an independent app Agent run. It returns { runId } after durable admission. Work runs when app and provider capacity are available, even with the main chat closed. Other app work waits in the existing queue; the main model is not woken to delegate.

Declare agentTasks in the manifest, targeting a declared result Function:

runtime:
  sdk:
    version: 2.5.0
agentTasks:
  - name: inspect-competitors
    title: Check competitor campaigns
    instructions: Inspect each supplied screenshot and submit campaign observations.
    capture: website_screenshot
    inputSchema:
      type: object
      properties:
        url: { type: string }
        competitorId: { type: string }
      required: [url, competitorId]
      additionalProperties: false
    resultFunction: record-observation
    maxAssignments: 10
    timeoutSeconds: 900
    maxAttempts: 2
    tokenLimit: 100000
cron:
  - name: daily-competitors
    schedule: "0 9 * * *"
    timezone: Europe/Prague
    function: select-competitors
    enabled: true

Declare both Functions as usual. The cron Function selects inputs and returns:

return agentTasks.start("inspect-competitors", {
  assignments: competitors.map(item => ({
    id: item.id,
    input: { competitorId: item.id, url: item.url },
  })),
}, { idempotencyKey: "daily-competitors" });

Cron supplies its trusted occurrence identity, overriding this key. Owner Function calls use their explicit stable key. Repeating a key with different work conflicts. Inputs support bounded strings, numbers and booleans, up to 50 assignments and 32 input fields. Empty batches should return without submission. agentTasks.get(runId) reads status.

The app needs an existing Agent conversation with a configured provider and the app-owner Codex harness (opencloud-codex-ai-sdk-harness-v3). Admission is production-only and owner-authorized. Dev Functions, anonymous users and other app members cannot spend Agent resources through this API. Workers cannot submit more tasks. They have the existing exact-app owner authority: resultFunction is an intended result path, not a Function allowlist.

Capture uses public HTTPS on port 443, a fresh browser profile, fixed 1440×1000 PNGs, a 30-second page limit, and private-network restrictions. The runtime supplies capture metadata and stable assignment submission keys. The worker uploads screenshots with opencloud file upload and submits JSON with opencloud function invoke --input-file. No custom submission tool is needed.

A successful result Function returns a receipt:

{
  "schemaVersion": 1,
  "submissionKey": "the-assignment-submission-key",
  "observationId": "app-observation-id",
  "outcome": "changed",
  "calendarCommitted": true,
  "notification": "queued",
  "screenshotFileId": "33333333-3333-4333-8333-333333333333"
}

outcome is changed, unchanged, or no_campaign; notification is queued or not_needed. Commit observation and calendar writes before returning. Queue notifications separately with durable, idempotent intent. Queued is not proof of delivery. Failed captures preserve the previous campaign.

The platform reconciles exact-app, exact-run Function operations and checks screenshot Files against runtime capture hashes. Agent prose never proves a save. The card separates execution from result reconciliation and opens the existing details panel. Stop preserves already accepted operations and saved observations. Recovery retains receipts and verifies screenshot bytes before reuse; unavailable retained evidence needs attention.

Keep result Function inputs backward-compatible during redeployment: invocation uses the current active Function. Task declarations are snapshotted; Function execution is not revision-pinned. Asynchronous result-handler receipts are not part of this first version. Execution timeout applies per bounded attempt.

Use CLI 3.10.0 or later for local validation, bundling and development of these declarations. Select SDK 2.5.0 explicitly: the CLI retains SDK 2.3.0 as its default for compatibility with older installations. Server-side drafts remain available on an updated platform. Workers use the existing upload/invoke commands.