Configuring Agent Durability (Scala)

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. Do not skip persistence to reduce replay cost. Use durable with periodic snapshots instead (see below); snapshots do not reduce stored oplog volume.

A standard durable agent:

import golem.runtime.annotations.{agentDefinition, agentImplementation}
import golem.BaseAgent
 
import scala.concurrent.Future
 
@agentDefinition(mount = "/counters/{name}")
trait CounterAgent extends BaseAgent {
  class Id(val name: String)
  def increment(): Future[Int]
  def getCount(): Future[Int]
}
 
@agentImplementation()
final class CounterAgentImpl(private val name: String) extends CounterAgent {
  private var count: Int = 0
 
  override def increment(): Future[Int] = Future.successful {
    count += 1
    count
  }
 
  override def getCount(): Future[Int] = Future.successful(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. Snapshots reduce replay work, not stored oplog volume. Periodic snapshots run at invocation boundaries; they do not interrupt an endless handler. Split heartbeats and polling into bounded, self-scheduled invocations.

@agentDefinition(snapshotting = "every(10)")     // snapshot every 10 successful calls
trait CounterAgent extends BaseAgent { ... }
 
@agentDefinition(snapshotting = "periodic(30s)") // or at most once per interval
trait HeartbeatAgent extends BaseAgent { ... }

See golem-custom-snapshot-scala for snapshotting modes and Snapshotted[S] / custom binary save/load hooks.

Ephemeral Agents

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

• State is discarded after each invocation completes
• An oplog is written 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

import golem.runtime.annotations.{agentDefinition, DurabilityMode}
 
@agentDefinition(mode = DurabilityMode.Ephemeral)
trait StatelessHandler extends BaseAgent {
  class Id()
  def handle(input: String): Future[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-scala.