Creating ephemeral (stateless) agents in a Rust Golem project. Use when the user wants a stateless agent, a fresh instance per invocation, no shared state between calls, or a request-handler style agent.
An ephemeral agent is a Golem agent that gets a fresh instance for every invocation. Unlike the default durable agents, ephemeral agents:
new() — field values set in one call are gone by the nextgolem agent oplog), but it is never used for replay — no automatic recovery on failureThis makes ephemeral agents ideal for pure request handlers, stateless transformers, adapters, and serverless-style functions where each call is independent.
Add ephemeral to the #[agent_definition] attribute:
use golem_rust::{agent_definition, agent_implementation};
#[agent_definition(ephemeral)]
pub trait RequestHandler {
fn new() -> Self;
fn handle(&self, input: String) -> String;
}
struct RequestHandlerImpl;
#[agent_implementation]
impl RequestHandler for RequestHandlerImpl {
fn new() -> Self {
Self
}
fn handle(&self, input: String) -> String {
format!("processed: {input}")
}
}
Consider a durable agent vs an ephemeral one:
// DURABLE (default) — state accumulates across calls
#[agent_definition]
pub trait DurableCounter {
fn new() -> Self;
fn increment(&mut self) -> u32;
}
// Call increment() three times → returns 1, 2, 3
// EPHEMERAL — state resets every call
#[agent_definition(ephemeral)]
pub trait EphemeralCounter {
fn new() -> Self;
fn increment(&mut self) -> u32;
}
// Call increment() three times → returns 1, 1, 1
Each invocation of an ephemeral agent:
new() to create a fresh instanceEphemeral agents are a natural fit for HTTP request handlers:
use golem_rust::{agent_definition, agent_implementation};
#[agent_definition(ephemeral, mount = "/api/convert/{name}")]
pub trait ConverterAgent {
fn new(name: String) -> Self;
#[post("/to-upper")]
fn to_upper(&self, #[body] input: String) -> String;
#[post("/to-lower")]
fn to_lower(&self, #[body] input: String) -> String;
}
struct ConverterAgentImpl {
name: String,
}
#[agent_implementation]
impl ConverterAgent for ConverterAgentImpl {
fn new(name: String) -> Self {
Self { name }
}
fn to_upper(&self, input: String) -> String {
input.to_uppercase()
}
fn to_lower(&self, input: String) -> String {
input.to_lowercase()
}
}
| Use Case | Why Ephemeral? |
|---|---|
| Stateless HTTP API (REST adapter, proxy) | No state to persist between requests |
| Data transformation / format conversion | Pure function — input in, output out |
| Validation service | Each validation is independent |
| Webhook receiver that forwards events | No need to remember previous webhooks |
| Stateless computation (math, encoding) | No side effects worth persisting |
golem agent oplog — but it is never replayed