Scheduling a Future Agent Invocation (TypeScript)

Overview

A scheduled invocation enqueues a method call on the target agent to be executed at a specific future time. The call returns immediately; the target agent processes it when the scheduled time arrives.

Usage

Every method on a definition RPC client has a .schedule() variant that takes a Datetime as the first argument, followed by the method’s input record (omit the input for methods declared with input: {}). It returns a CancellationToken; ignore the token when cancellation is not needed.

import { Datetime } from '@golemcloud/golem-ts-sdk';
import { Counter } from './counter-agent.js';
 
const counter = Counter.client.get({ name: 'my-counter' });
 
// Schedule increment to run 60 seconds from now.
const inOneMinute = Datetime.fromDate(new Date(Date.now() + 60_000));
counter.increment.schedule(inOneMinute);
 
// Schedule with arguments.
const reporter = ReportAgent.client.get({ name: 'daily' });
reporter.generateReport.schedule(
    Datetime.parse('2026-01-02T00:00:00Z'),
    { kind: 'summary' },
);

Datetime Type

The Datetime argument is the SDK Datetime type: a plain { seconds: bigint, nanoseconds: number } object with seconds since the Unix epoch in UTC. Import it from the SDK and build values with its helpers:

import { Datetime } from '@golemcloud/golem-ts-sdk';
 
const fromDate = Datetime.fromDate(new Date(Date.now() + 5 * 60_000));
const fromText = Datetime.parse('2026-01-02T09:30:00+02:00'); // any RFC 3339 offset, stored as UTC
const inline: Datetime = { seconds: 1700000000n, nanoseconds: 0 };
 
Datetime.toISOString(fromText); // '2026-01-02T07:30:00Z'
Datetime.toDate(inline);        // a JavaScript Date (millisecond precision)

Cancellation

Keep the CancellationToken returned by .schedule(at, input) and call .cancel() any time before the scheduled time to cancel the invocation:

const token = counter.increment.schedule(Datetime.fromDate(new Date(Date.now() + 60_000)));
// …later, if the run is no longer wanted:
token.cancel();

(To cancel an in-flight — not scheduled — RPC call, pass { signal } as the trailing option to the normal awaited call and abort the AbortSignal, for example method(input, { signal }). You can also gate a method on agent state, or cancel from the CLI with a known idempotency key via golem agent cancel-invocation — see golem-cancel-queued-invocation.)

Use Cases

• Periodic tasks: Schedule the next run at the end of each invocation
• Delayed processing: Process an order after a cooling-off period
• Reminders and notifications: Send a reminder at a specific time
• Retry with backoff: Schedule a retry after a delay on failure