What Are Agents?
Agents are Clojure's tool for uncoordinated, asynchronous state changes: you create one with (agent initial-state), and instead of updating it directly, you send it an action — a function that will eventually be applied to its current state on a background thread. The call to send returns immediately with the agent itself, not the new state, so the caller never blocks waiting for the update to actually happen, and multiple actions queue up to run one after another.
Cricket analogy: Like sending a message to the ground announcer to update the crowd display 'at some point soon' without waiting for confirmation — you fire off the instruction (send an action to an agent) and move straight on to bowling the next over.
An agent's action function receives the current state as its first argument plus any extra arguments passed to send/send-off, and its return value becomes the agent's new state — the same shape as swap!'s function on an atom, but applied asynchronously.
send vs send-off and Thread Pools
Clojure gives you two ways to dispatch an action, and choosing the right one matters for throughput. send uses a small, fixed-size thread pool sized to your CPU cores, intended for quick, non-blocking, CPU-bound work; if you queue a blocking call there, you can starve the whole pool. send-off uses a separate, expandable thread pool designed for actions that legitimately block, such as network calls, file I/O, or database queries, so blocking work on one agent doesn't stall unrelated CPU-bound work on another.
Cricket analogy: Like assigning quick scoring calculations to the in-stadium scorer, a small fixed team doing fast CPU-bound work (send), versus assigning a slow task like retrieving decades-old match archives to an external researcher, an expandable pool of freelancers for blocking work (send-off).
(def audit-log (agent []))
(defn log-event! [event]
(send audit-log conj event))
(log-event! {:type :login :user "asha"})
(log-event! {:type :purchase :user "asha" :amount 42.50})
(await audit-log)
@audit-log
;; => [{:type :login ...} {:type :purchase ...}]
(def uploader (agent {:pending 0}))
(set-error-handler! uploader
(fn [ag ex] (println "upload agent failed:" (.getMessage ex))))
(set-error-mode! uploader :continue)
(send-off uploader
(fn [state file]
(upload-to-s3! file) ;; blocking I/O, so use send-off
(update state :pending dec))
"report.pdf")Error Handling and Agent Error Modes
If an action function throws, the agent enters a failed state whose behavior depends on its error mode. Under the default :fail mode, the agent stops processing any further queued actions until you call restart-agent with a new state; under :continue mode, the error is logged (or passed to a handler set with set-error-handler!) and the agent simply moves on to the next queued action. You can inspect the exception at any time with agent-error, which returns the exception object or nil if the agent isn't currently failed.
Cricket analogy: Like a bowler who's had a no-ball called — under a lenient mode the over just continues (:continue, error logged but the agent keeps processing new actions), whereas under a strict mode the whole spell is suspended until the umpire manually clears the bowler (:fail, requiring a manual restart-agent).
Calling await or await-for inside a dosync transaction, or sending actions to an agent from inside a transaction that might retry, is unsafe and can lead to actions being queued multiple times — keep agent interactions outside of STM transactions.
Coordinating with await
Because send and send-off return immediately, you sometimes need to know when the queued work has actually finished before reading the agent's final state — that's what await (and its timeout-bounded cousin await-for) are for: they block the calling thread until every action already dispatched to the given agent(s) completes. Clojure also guarantees that actions sent to the same agent from the same thread are processed strictly in the order they were dispatched, so a sequence of send calls from one thread will always apply in that same sequence, even though the actual work happens asynchronously on a pool thread.
Cricket analogy: Like waiting at the boundary rope until the third umpire's review is fully resolved before play resumes — await blocks until all queued actions on an agent finish, and actions dispatched from the same over (thread) are always processed in the order they were bowled.
- Agents hold one value, updated asynchronously via a queue of action functions.
- Use send for fast, non-blocking work; use send-off for actions that block on I/O.
- agent-error inspects a failed agent's exception; restart-agent recovers it under :fail mode.
- set-error-mode! :continue keeps an agent processing after logging an error instead of halting it.
- Ordering is preserved for actions sent from the same thread to the same agent.
- await blocks until queued actions complete — never call it inside an STM transaction.
Practice what you learned
1. What is the key difference between an atom's swap! and an agent's send?
2. When should you use send-off instead of send?
3. What does await do?
4. In the default :fail error mode, what happens to an agent after its action function throws an exception?
5. Are actions sent to the same agent from a single thread guaranteed to execute in order?
Was this page helpful?
You May Also Like
Atoms in Clojure
Atoms provide Clojure's simplest managed reference type for safe, synchronous, uncoordinated mutable state backed by lock-free compare-and-swap updates.
core.async Basics
core.async brings Go-style CSP concurrency to Clojure through channels and lightweight go blocks, decoupling producers and consumers.
Concurrency Primitives Compared
A side-by-side comparison of atoms, refs, agents, and core.async channels to help you choose the right Clojure concurrency primitive for each situation.
Related Reading
Related Study Notes in Programming
Browse all study notesApache Spark Study Notes
Programming · 30 topics
ProgrammingApache Flink Study Notes
Programming · 30 topics
ProgrammingHadoop Study Notes
Programming · 30 topics
ProgrammingSnowflake Study Notes
Programming · 30 topics
ProgrammingApache Airflow Study Notes
Programming · 30 topics
Programmingdbt (Data Build Tool) Study Notes
Programming · 30 topics