Read-only agent methods

Golem lets agent authors mark individual agent methods as read-only. A read-only method is one you promise performs only a pure read of the agent’s state, and Golem caches its result, so read-heavy methods can be served without waiting behind slow writes — and without even loading the agent when a cached value is available.

This page explains what the runtime actually enforces (and, just as importantly, what it does not), how the cache policies work, and how to use the marker from each SDK.

What “read-only” means

A read-only method must be a pure function of the agent’s already-loaded state and the method inputs: it must not change anything, and its result must depend only on its inputs and the current state. That is the contract you are promising.

Golem enforces only part of this contract:

Allowed	Not allowed — runtime-enforced	Not allowed — author’s responsibility
Reading the agent’s state fields	Writing through durable host APIs (key-value and blob storage, external databases, promises, agent management, …)	Mutating in-memory state (assigning to a field)
Computation over the method inputs	Outgoing HTTP requests	Reading the clock / current time
Returning derived/aggregated values	RPC calls to other agents	Randomness
		Reading environment variables
		Remote / blob reads
		Creating, writing, or deleting the agent’s own files

Operations in the middle column trap before the call runs or any change is persisted. The invocation fails with a typed ReadOnlyViolation that identifies the agent method and offending host function. Golem does not detect the operations in the right column: in-memory writes are not host calls, and filesystem permissions do not enforce the read-only contract. These operations can make cached results incorrect, so you must avoid them yourself. If you need them, use a regular (non-read-only) method.

In exchange for honoring this contract, Golem provides:

Guarantee	What it means
Cached result	The result is cached per `(method, normalized input, optional principal)` on the worker.
Queue & loading bypass	A cache hit returns immediately — it never acquires the agent’s invocation queue and never loads an evicted agent.

A cache hit writes nothing to the oplog and does not load the agent. A cache miss (or a no-cache method) still runs through the queue and writes the usual AgentInvocationStarted / AgentInvocationFinished markers — needed for oplog visibility, fuel accounting, and idempotency-key result lookup.

Cache policies

The cache policy is part of the read-only marker — non-read-only methods cannot carry one.

Policy	Behavior
`until-write` (default)	The cached result is valid until the next non-read-only invocation on the same agent invalidates it.
`ttl(d)`	The cached result expires after duration `d`, even if no write happened in the meantime.
`no-cache`	The method runs every time without caching; the read-only contract still applies.

After a successful non-read-only invocation commits its completion marker, Golem invalidates cached read-only results for that agent. While a mutation is queued or running, readers can still receive the previous cached value. Updating or reverting the agent also invalidates its cache; evicting and reloading only the WebAssembly instance does not. ttl(d) entries additionally expire by time. no-cache never inserts into the cache.

Per-principal caching

By default a read-only result is shared across all callers — the cache key is (method, input) and HTTP responses are marked Cache-Control: public (CDN-friendly).

When the result depends on who is calling (for example, an authorization-scoped view), add a Principal parameter to the method and enable per-principal caching:

TypeScript

Add a direct s.principal() input to the method. The TypeScript SDK automatically enables per-principal caching.

Effect TypeScript

Add a PrincipalSchema input to the method. The Effect SDK automatically enables per-principal caching.

Rust

Add a Principal parameter to the method. The Rust SDK automatically enables per-principal caching.

Scala

Add a Principal parameter to the method. The Scala SDK automatically enables per-principal caching.

MoonBit

Add a Principal parameter to the method. The MoonBit SDK automatically enables per-principal caching.

Go

Add a Principal parameter to the method. The Go SDK automatically enables per-principal caching.

With per-principal caching enabled, the calling principal becomes part of the cache key, so each principal gets its own cached entry, and HTTP responses switch to Cache-Control: private. The response’s Vary header names the configured authentication header and any request headers bound as method inputs.

The Principal parameter is marked as auto-injected in the method’s input schema. The runtime supplies it; callers do not pass it.

Read-only and ephemeral are mutually exclusive

Read-only methods read the agent’s shared, already-loaded state. Ephemeral agents get a fresh instance per invocation and have no shared state to read from, so a read-only method on an ephemeral agent has no meaning. The host rejects this combination when the agent registers its types; individual SDKs may also reject it earlier.

Marking a method read-only

TypeScript

Mark a method read-only by setting readOnly: true on its method(...) spec:


import { z } from "zod"
import { defineAgent, method } from "@golemcloud/golem-ts-sdk"
 
export const CounterAgent = defineAgent({
  name: "CounterAgent",
  id: { name: z.string() },
  methods: {
    // Non-read-only: writes shared state
    increment: method({ input: {}, returns: z.number() }),
    // Read-only: pure read over already-loaded state
    getCount: method({ input: {}, returns: z.number(), readOnly: true }),
  },
})
 
export const CounterAgentImpl = CounterAgent.implement({
  init: () => ({ count: 0 }),
  methods: {
    increment() {
      this.count += 1
      return this.count
    },
    getCount() {
      return this.count
    },
  },
})

readOnly: true uses the default until-write cache policy. For finer control, pass an object instead of the boolean. A direct s.principal() input automatically enables per-principal caching:


methods: {
  // TTL cache: the result expires 30s after it is computed
  recentSummary: method({
    input: {},
    returns: Summary,
    readOnly: { cache: { ttlNanos: 30_000_000_000n } },
  }),
  // Never cached, but still side-effect-free
  pureCompute: method({
    input: { x: z.number(), y: z.number() },
    returns: z.number(),
    readOnly: { cache: "no-cache" },
  }),
  // Principal-aware: cached per caller principal
  myVisibleItems: method({
    input: { caller: s.principal() },
    returns: z.array(Item),
    readOnly: true,
  }),
}

Effect TypeScript

Mark a method read-only with readOnly: true. Effect handlers return an Effect, and state held in a Ref must only be read from the read-only handler:


import { Effect, Ref, Schema } from "effect"
import { defineAgent, method } from "@golemcloud/effect-golem"
 
export const CounterAgent = defineAgent({
  name: "CounterAgent",
  id: { name: Schema.String },
  methods: {
    increment: method({ input: {}, success: Schema.Number }),
    getCount: method({ input: {}, success: Schema.Number, readOnly: true }),
  },
}).implement({
  init: () => Ref.make(0),
  methods: (count) => ({
    increment: () => Ref.updateAndGet(count, (value) => value + 1),
    getCount: () => Ref.get(count),
  }),
})

Use the object form for another cache policy. Principal-aware caching is inferred when the input contains Principal.PrincipalSchema:


import { Principal } from "@golemcloud/effect-golem"
 
const recentSummary = method({
  input: {},
  success: Summary,
  readOnly: { cache: { ttlNanos: 30_000_000_000n } },
})
 
const pureCompute = method({
  input: { x: Schema.Number, y: Schema.Number },
  success: Schema.Number,
  readOnly: { cache: "no-cache" },
})
 
const myVisibleItems = method({
  input: { principal: Principal.PrincipalSchema },
  success: Schema.Array(Item),
  readOnly: true,
})

Rust

Use the #[read_only] attribute on the method:


use golem_rust::{agent_definition, agent_implementation, read_only};
 
#[agent_definition]
pub trait CounterAgent {
    fn new(name: String) -> Self;
 
    // Non-read-only: writes shared state
    fn increment(&mut self) -> u64;
 
    // Read-only: pure read over already-loaded state
    #[read_only]
    fn get_count(&self) -> u64;
}

Choose a cache policy via attribute arguments; per-principal caching is automatic when the method takes a Principal parameter:


use golem_rust::agentic::Principal;
 
#[read_only(cache = "ttl", ttl = "30s")]
fn recent_summary(&self) -> Summary;
 
#[read_only(cache = "no_cache")]
fn pure_compute(&self, x: u32, y: u32) -> u32;
 
// Principal-aware: cached per principal (uses_principal auto-derived)
#[read_only]
fn my_visible_items(&self, principal: Principal) -> Vec<Item>;

Scala

Use the @readOnly annotation on the method:


import golem.runtime.annotations.{agentDefinition, readOnly}
import golem.BaseAgent
 
import scala.concurrent.Future
 
@agentDefinition()
trait CounterAgent extends BaseAgent {
  class Id(val name: String)
 
  // Non-read-only: writes shared state
  def increment(): Future[Long]
 
  // Read-only: pure read over already-loaded state
  @readOnly
  def getCount(): Future[Long]
}

Choose a cache policy via the cache string argument; per-principal caching is automatic when the method receives a Principal:


import golem.runtime.annotations.readOnly
import golem.Principal
 
@readOnly(cache = "ttl(30 seconds)")
def recentSummary(): Future[Summary]
 
@readOnly(cache = "no-cache")
def pureCompute(x: Int, y: Int): Future[Int]
 
// Principal-aware: cached per principal (usesPrincipal auto-derived)
@readOnly
def myVisibleItems(principal: Principal): Future[List[Item]]

MoonBit

Use the #derive.read_only attribute, placed before the method (the same place as #derive.prompt_hint):


#derive.agent
struct CounterAgent {
  name: String
  mut count: UInt64
}
 
fn CounterAgent::new(name: String) -> CounterAgent {
  { name, count: 0 }
}
 
/// Increments the counter and returns the new value.
pub fn CounterAgent::increment(self: Self) -> UInt64 {
  self.count += 1
  self.count
}
 
/// Returns the current counter value.
#derive.read_only
pub fn CounterAgent::get_count(self: Self) -> UInt64 {
  self.count
}

Choose a cache policy via attribute arguments (TTL is given in nanoseconds); per-principal caching is automatic when the method takes a Principal parameter:


#derive.read_only(cache="ttl", ttl="30000000000") // 30s in nanoseconds
pub fn CounterAgent::recent_summary(self: Self) -> Summary { /* ... */ }
 
#derive.read_only(cache="no_cache")
pub fn CounterAgent::pure_compute(self: Self, x: UInt, y: UInt) -> UInt {
  x + y
}
 
// Principal-aware: cached per principal (uses_principal auto-derived)
#derive.read_only
pub fn CounterAgent::my_visible_items(self: Self, principal: Principal) -> Array[Item] { /* ... */ }

Go

Pass the golem.ReadOnly() option to the method descriptor in the definition package:


package counter
 
import "github.com/golemcloud/golem/sdks/go/golem"
 
type ID struct{ Name string }
 
var Agent = golem.DefineAgent[ID](golem.Spec{Name: "CounterAgent"})
 
var (
    // Non-read-only: writes shared state
    Increment = Agent.Method[golem.Unit, uint64]("increment")
 
    // Read-only: pure read over already-loaded state
    GetCount = Agent.Method[golem.Unit, uint64]("getCount", golem.ReadOnly())
)

The implementation package handles a read-only method like any other method:


func init() {
    agent.Handle(counter.Increment, func(ctx *golem.Context[state], _ golem.Unit) uint64 {
        ctx.State.count++
        return ctx.State.count
    })
    agent.Handle(counter.GetCount, func(ctx *golem.Context[state], _ golem.Unit) uint64 {
        return ctx.State.count
    })
}

Choose a cache policy by passing one to golem.ReadOnly; per-principal caching is automatic when the method’s input has a golem.Principal field:


import "time"
 
type ComputeIn struct{ X, Y uint32 }
 
type PrincipalIn struct{ Principal golem.Principal }
 
var (
    RecentSummary = Agent.Method[golem.Unit, Summary]("recentSummary",
        golem.ReadOnly(golem.CacheFor(30*time.Second)))
 
    PureCompute = Agent.Method[ComputeIn, uint32]("pureCompute",
        golem.ReadOnly(golem.NoCache()))
 
    // Principal-aware: cached per principal
    MyVisibleItems = Agent.Method[PrincipalIn, []Item]("myVisibleItems", golem.ReadOnly())
)

Performance contract

Queue bypass. On a cache hit the result is returned without acquiring the agent’s invocation queue, so a read-only call is not blocked behind a slow write that is currently being processed.
Agent-loading bypass. The cache lives on the worker independently of whether the WebAssembly instance is loaded. A cache hit is served even when the agent is currently evicted — no instance loading happens.
Automatic RPC fast path. The cache lookup sits at the single invocation entry point shared by the public API and agent-to-agent RPC, so an RPC into a read-only method on the same node hits the cache too.
Concurrent coalescing. Many identical first-time reads coalesce into a single execution; the rest wait for and share that one result.

HTTP cache headers

When a read-only method is mapped to an HTTP GET or HEAD endpoint (see Exposing agents over HTTP), Golem emits cache-friendly response headers derived from the cache policy and whether the method is principal-dependent:

Cache policy	Response headers
`no-cache`	`Cache-Control: no-store`
`until-write`	`Cache-Control: <visibility>, no-cache` + an opaque `ETag`
`ttl(d)`	`Cache-Control: <visibility>, max-age=<d>` + an opaque `ETag`

Where <visibility> is private when the method is principal-dependent, and public otherwise. Vary always names request headers bound as inputs; for principal-dependent methods it also names the configured authentication header.

A request that repeats the returned ETag in If-None-Match is revalidated cheaply. If it still matches the agent’s current agent-instance fingerprint and oplog position, Golem returns 304 Not Modified without executing the agent method or loading its WebAssembly instance.

A response a CDN or browser sees for a public, until-write method therefore looks like:


HTTP/1.1 200 OK
Cache-Control: public, no-cache
ETag: "<opaque-etag>"
Content-Type: application/json
 
{"count":7}

and a later conditional request short-circuits to:


GET /counter-1/count HTTP/1.1
If-None-Match: "<opaque-etag>"
 
HTTP/1.1 304 Not Modified
Cache-Control: public, no-cache
ETag: "<opaque-etag>"

Read-only methods bound to non-GET/HEAD verbs are allowed, but they do not get cache headers — caching a POST/PUT/DELETE response is not meaningful. Deployment validation emits a warning for each such binding.