Configuring Agent Durability (Rust)

Durable Agents (Default)

By default, all Golem agents are durable:

• State persists across invocations, failures, and restarts
• Every side effect is recorded in an oplog (operation log)
• On failure, the agent is transparently recovered by replaying the oplog
• No special code needed — durability is automatic

You cannot opt out of oplog writes for a durable agent. The oplog is how durability works — every side effect must be recorded. Do not try to skip persistence. Use durable with periodic snapshots to reduce replay cost (see below); snapshots do not reduce stored oplog volume.

A standard durable agent:

use golem_rust::{agent_definition, agent_implementation};
 
#[agent_definition]
pub trait CounterAgent {
    fn new(name: String) -> Self;
    fn increment(&mut self) -> u32;
    fn get_count(&self) -> u32;
}
 
struct CounterAgentImpl {
    name: String,
    count: u32,
}
 
#[agent_implementation]
impl CounterAgent for CounterAgentImpl {
    fn new(name: String) -> Self {
        Self { name, count: 0 }
    }
 
    fn increment(&mut self) -> u32 {
        self.count += 1;
        self.count
    }
 
    fn get_count(&self) -> u32 {
        self.count
    }
}

Durable with Periodic Snapshots

Same durability guarantees as the default durable mode, but recovery starts from the latest snapshot instead of replaying the full oplog from the beginning. Use this whenever the oplog grows unboundedly — long-running agents, high-frequency state changes, heartbeats, polling loops, recurring tasks.

Snapshots reduce replay work, not stored oplog volume. Automatic snapshots run between successful invocations, not inside an endless handler. Split recurring work into bounded invocations. The implementation must derive serde Serialize and Deserialize for default snapshots, or provide custom save_snapshot / load_snapshot hooks; the annotation alone is not enough.

#[agent_definition(snapshotting = "every(10)")]   // snapshot every 10 successful calls
pub trait CounterAgent { ... }
 
#[agent_definition(snapshotting = "periodic(30s)")]  // or at most once per interval
pub trait HeartbeatAgent { ... }

See golem-custom-snapshot-rust for snapshotting modes and serde-based or custom save_snapshot / load_snapshot implementations.

Ephemeral Agents

Use ephemeral mode for stateless, per-invocation agents where persistence is not needed:

• State is discarded after each invocation completes
• An ephemeral oplog is recorded for inspection. If the executor restarts while preparing an invocation, Golem can replay the recorded initialization so that the method can still start. Once the method starts, a failure is terminal; Golem does not replay the method.
• Useful for pure functions, request handlers, or adapters

#[agent_definition(ephemeral)]
pub trait StatelessHandler {
    fn new() -> Self;
    fn handle(&self, input: String) -> String;
}

When to Choose Which

When in doubt, use the default (durable). Ephemeral mode is an optimization for agents that genuinely don’t need persistence. Add periodic snapshots whenever recovery time matters — see golem-custom-snapshot-rust.