Creating Ephemeral (Stateless) Agents (MoonBit)
Overview
An ephemeral agent is a Golem agent that gets a fresh instance for every invocation. Unlike the default durable agents, ephemeral agents:
- No shared state: Each invocation starts from a clean
new() — field values set in one call are gone by the next
- No method recovery replay: An oplog is still recorded lazily (useful for debugging via
golem agent oplog). 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.
- No persistence: The agent's memory is discarded after each invocation completes
- Logical target versus concrete identity: Constructor parameters select the logical target; each call uses a fresh, one-shot concrete agent identity
This makes ephemeral agents ideal for pure request handlers, stateless transformers, adapters, and serverless-style functions where each call is independent.
How to Create an Ephemeral Agent
Use #derive.agent("ephemeral") instead of #derive.agent:
#derive.agent("ephemeral")
struct RequestHandler {
}
fn RequestHandler::new() -> RequestHandler {
{ }
}
pub fn RequestHandler::handle(self: Self, input: String) -> String {
"processed: " + input
}
What "Fresh Instance Per Invocation" Means
Consider a durable agent vs an ephemeral one:
// DURABLE (default) — state accumulates across calls
#derive.agent
struct DurableCounter {
mut count: UInt
}
fn DurableCounter::new() -> DurableCounter {
{ count: 0 }
}
pub fn DurableCounter::increment(self: Self) -> UInt {
self.count = self.count + 1
self.count
}
// Call increment() three times → returns 1, 2, 3
// EPHEMERAL — state resets every call
#derive.agent("ephemeral")
struct EphemeralCounter {
mut count: UInt
}
fn EphemeralCounter::new() -> EphemeralCounter {
{ count: 0 }
}
pub fn EphemeralCounter::increment(self: Self) -> UInt {
self.count = self.count + 1
self.count
}
// Call increment() three times → returns 1, 1, 1
Each invocation of an ephemeral agent:
- Calls
new() to create a fresh instance
- Executes the method
- Discards the instance entirely
When to Use Ephemeral Agents
| 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 |
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 define the logical target, not a reusable concrete instance across calls
- Ephemeral agents can call other agents via RPC and make HTTP requests, but do not support durable suspension or unlimited waits
- The oplog is still recorded lazily, so you can inspect what an ephemeral agent did via
golem agent oplog. 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.
- Never edit generated files —
golem_reexports.mbt, golem_agents.mbt, and golem_derive.mbt are auto-generated by golem build
1---2name: golem-stateless-agent-moonbit3description: "Creating ephemeral (stateless) agents in a MoonBit 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."4metadata:5 source: https://skillmd.com/skills/golemcloud/golem-stateless-agent-moonbit6---78# Creating Ephemeral (Stateless) Agents (MoonBit)910## Overview1112An **ephemeral agent** is a Golem agent that gets a **fresh instance for every invocation**. Unlike the default durable agents, ephemeral agents:1314- **No shared state**: Each invocation starts from a clean `new()` — field values set in one call are gone by the next15- **No method recovery replay**: An oplog is still recorded lazily (useful for debugging via `golem agent oplog`). 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.16- **No persistence**: The agent's memory is discarded after each invocation completes17- **Logical target versus concrete identity**: Constructor parameters select the logical target; each call uses a fresh, one-shot concrete agent identity1819This makes ephemeral agents ideal for **pure request handlers**, **stateless transformers**, **adapters**, and **serverless-style functions** where each call is independent.2021## How to Create an Ephemeral Agent2223Use `#derive.agent("ephemeral")` instead of `#derive.agent`:2425```moonbit26#derive.agent("ephemeral")27struct RequestHandler {28}2930fn RequestHandler::new() -> RequestHandler {31 { }32}3334pub fn RequestHandler::handle(self: Self, input: String) -> String {35 "processed: " + input36}37```3839## What "Fresh Instance Per Invocation" Means4041Consider a durable agent vs an ephemeral one:4243```moonbit44// DURABLE (default) — state accumulates across calls45#derive.agent46struct DurableCounter {47 mut count: UInt48}4950fn DurableCounter::new() -> DurableCounter {51 { count: 0 }52}5354pub fn DurableCounter::increment(self: Self) -> UInt {55 self.count = self.count + 156 self.count57}5859// Call increment() three times → returns 1, 2, 36061// EPHEMERAL — state resets every call62#derive.agent("ephemeral")63struct EphemeralCounter {64 mut count: UInt65}6667fn EphemeralCounter::new() -> EphemeralCounter {68 { count: 0 }69}7071pub fn EphemeralCounter::increment(self: Self) -> UInt {72 self.count = self.count + 173 self.count74}7576// Call increment() three times → returns 1, 1, 177```7879Each invocation of an ephemeral agent:801. Calls `new()` to create a fresh instance812. Executes the method823. Discards the instance entirely8384## When to Use Ephemeral Agents8586| Use Case | Why Ephemeral? |87|----------|---------------|88| Stateless HTTP API (REST adapter, proxy) | No state to persist between requests |89| Data transformation / format conversion | Pure function — input in, output out |90| Validation service | Each validation is independent |91| Webhook receiver that forwards events | No need to remember previous webhooks |92| Stateless computation (math, encoding) | No side effects worth persisting |9394## When NOT to Use Ephemeral Agents9596- **Counters, accumulators, shopping carts** — need state across calls → use durable (default)97- **Workflow orchestrators, sagas** — need oplog for recovery → use durable (default)98- **Agents calling external APIs** where at-least-once semantics matter → use durable (default)99- **Any agent where one call's result depends on a previous call** → use durable (default)100101## Key Points102103- Ephemeral mode is set at the **agent type level** — all instances of the type are ephemeral104- Constructor parameters define the logical target, not a reusable concrete instance across calls105- Ephemeral agents can call other agents via RPC and make HTTP requests, but do not support durable suspension or unlimited waits106- The oplog is still recorded lazily, so you can inspect what an ephemeral agent did via `golem agent oplog`. 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.107- **Never edit generated files** — `golem_reexports.mbt`, `golem_agents.mbt`, and `golem_derive.mbt` are auto-generated by `golem build`