Configuring Agent Durability (MoonBit)

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

A standard durable agent:

#derive.agent
struct CounterAgent {
  name: String
  mut count: UInt
}
 
fn CounterAgent::new(name: String) -> CounterAgent {
  { name, count: 0 }
}
 
pub fn CounterAgent::increment(self: Self) -> UInt {
  self.count = self.count + 1
  self.count
}
 
pub fn CounterAgent::get_count(self: Self) -> UInt {
  self.count
}

Ephemeral Agents

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

• State is discarded after each invocation completes
• No oplog replay — lower overhead (an oplog is still recorded lazily for debugging via golem agent oplog, but never replayed)
• Each invocation calls new() to create a fresh instance, executes the method, then discards the instance
• Useful for pure functions, request handlers, or adapters

#derive.agent("ephemeral")
struct StatelessHandler {
}
 
fn StatelessHandler::new() -> StatelessHandler {
  {  }
}
 
pub fn StatelessHandler::handle(self: Self, input: String) -> String {
  "processed: " + input
}

When to Choose Which

When in doubt, use the default (durable). Ephemeral mode is an optimization for agents that genuinely don’t need persistence.

Switching Between Modes

To make a durable agent ephemeral, change:

#derive.agent
struct MyAgent {

to:

#derive.agent("ephemeral")
struct MyAgent {

To make an ephemeral agent durable, change #derive.agent("ephemeral") back to #derive.agent.

After changing the annotation, rebuild with golem build to regenerate derived files. Never edit generated files — golem_reexports.mbt, golem_agents.mbt, and golem_derive.mbt are auto-generated.