Golem Stateless Agent Rust

How to Create an Ephemeral Agent

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}")
    }
}

What "Fresh Instance Per Invocation" Means

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:

1. Calls new() to create a fresh instance
2. Executes the method
3. Discards the instance entirely

Combining with HTTP Endpoints

Ephemeral 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()
    }
}

When to Use Ephemeral Agents

When NOT to Use Ephemeral Agents

• Counters, accumulators, shopping carts — need state across calls → use durable (default)
• Workflow orchestrators, sagas — need oplog for recovery → use durable (default)
• Agents calling external APIs where at-least-once semantics matter → use durable (default)
• Any agent where one call's result depends on a previous call → use durable (default)

Key Points

• Ephemeral mode is set at the agent type level — all instances of the type are ephemeral
• Constructor parameters still define identity — you can have multiple ephemeral agents with different parameters
• Ephemeral agents can still call other agents via RPC, make HTTP requests, and use all Golem APIs
• The oplog is still recorded lazily, so you can inspect what an ephemeral agent did via golem agent oplog — but it is never replayed