Scheduling a Future Agent Invocation (Rust)

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 the generated <AgentName>Client has a corresponding schedule_ variant that takes a Datetime as the first argument:

use golem_rust::wasip2::clocks::wall_clock::Datetime;
 
let mut counter = CounterAgentClient::get("my-counter".to_string());
 
// Schedule increment to run 60 seconds from now
let now_secs = std::time::SystemTime::now()
    .duration_since(std::time::UNIX_EPOCH)
    .unwrap()
    .as_secs();
 
counter.schedule_increment(Datetime {
    seconds: now_secs + 60,
    nanoseconds: 0,
});
 
// Schedule with arguments
let reporter = ReportAgentClient::get("daily".to_string());
reporter.schedule_generate_report( 
    "summary".to_string(),
    Datetime { seconds: tomorrow_midnight, nanoseconds: 0 }
);

Datetime Type

The Datetime struct represents a point in time as seconds + nanoseconds since the Unix epoch:

use golem_rust::wasip2::clocks::wall_clock::Datetime;
 
Datetime {
    seconds: 1700000000,  // Unix timestamp in seconds
    nanoseconds: 0,       // Sub-second precision
}

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

Scheduling a Future Agent Invocation Triggering a Fire-and-Forget Agent Invocation