Updating Running Agents

Both golem and golem-cli can be used — all commands below work with either binary.

When a new version of a component is deployed, existing running agents continue using their previous version by default. To move agents to the new version, you must explicitly trigger an update using one of the methods below.

Update Modes

Golem supports two update modes:

When to Use Each Mode

• Use auto when the target can replay the relevant retained history. For periodically snapshotted agents, Golem starts from a usable snapshot and validates only the history after it; without a usable snapshot it validates the complete retained history from the authoritative baseline.
• Use manual when the change is breaking — renamed or removed functions, changed parameter types, restructured internal state. The agent’s state must be explicitly migrated via snapshot functions.

Method 1: Update During Deploy

The simplest way to update agents is to pass --update-agents (or -u) to golem deploy:

golem deploy --yes --update-agents auto
golem deploy --yes --update-agents manual
golem deploy --yes -u auto

This deploys the new component version and triggers an update for all existing agents of all affected components in one step.

Other Deploy Strategies

These flags are mutually exclusive — only one can be used at a time.

Method 2: Explicit Agent Update Command

Update a single agent to a specific (or the current deployed) component revision:

golem agent update <AGENT_ID> [MODE] [TARGET_REVISION]

Arguments

Flags

Examples

# Update to the current deployed revision with automatic mode (default)
golem agent update 'Counter("my-counter")'
 
# Update to the current deployed revision with manual (snapshot-based) mode
golem agent update 'Counter("my-counter")' manual
 
# Update to a specific revision
golem agent update 'Counter("my-counter")' auto 3
 
# Wait for the update to finish
golem agent update 'Counter("my-counter")' auto --await
 
# Don't wake suspended agents
golem agent update 'Counter("my-counter")' auto --disable-wakeup

Method 3: Bulk Update All Agents of a Component

Update all existing agents belonging to a specific component:

golem component update-agents [OPTIONS] [COMPONENT_NAME]

Arguments

Examples

# Update all agents of a component
golem component update-agents my-component
 
# With manual mode
golem component update-agents my-component -u manual --await

Method 4: Application-Level Bulk Update

Update all agents across all components in the current application:

golem update-agents [OPTIONS] [COMPONENT_NAME]...

Arguments

Examples

# Update all agents in the application
golem update-agents
 
# Update only agents of specific components
golem update-agents comp-a comp-b -u manual

Method 5: Programmatic Update (Agent-to-Agent)

An agent can trigger an update on another agent programmatically using the Golem host API:

update-agent(agent-id, target-revision, mode)

This is exposed in each SDK’s host bindings. The function returns immediately — it does not wait for the update to complete.

How Automatic Update Works

1. Admission records the target and an exact attempt identity.
2. When that request reaches the queue head, Golem selects an automatic snapshot record of the source revision: the last record, else the usable record before it. The record must be usable (confirmed, or without a filesystem snapshot name), not rejected, before any queued manual update, and without a filesystem snapshot name on an executor without filesystem snapshots. The target revision must be newer than the source revision. A record committed after admission is eligible. Golem durably records either that record, with its filesystem snapshot name, or full replay from the authoritative recovery baseline before executing the strategy, so restart reconstruction does not recompute the choice.
3. The worker is restarted promptly, including when an invocation is in flight. When the agent is loaded and the upload of its newest periodic snapshot is in progress, the agent first waits for that upload, so the update can use that snapshot. The wait ends at the operator’s confirmation wait (60 seconds by default), at a terminal interrupt, at a stop of the agent, or when the executor retires the agent, for example when the agent moves to another executor. The wait does not shorten the time that the agent has to stop.
4. Golem restores the agent’s files from the filesystem snapshot of the selected record (a record without a name gives the initial files of the source revision). The target loads the application snapshot of the same record and replays the committed history after it with the source revision’s configuration and initial files. The replay can extend beyond the request entry because source work may finish while execution is stopping.
5. At the update point, Golem applies the initial files of the target revision, as a full replay does. A changed declaration of an initial file at a path that the agent wrote, changed or deleted fails the update.
6. Success is recorded only after replay validation and before target live effects continue. The selected record then becomes the authoritative recovery baseline. Every later start from it restores the same filesystem snapshot, and retention keeps that snapshot.
7. If the attempt fails, one failed outcome is recorded and the healthy source revision is reconstructed. In that attempt, Golem does not try an older snapshot or switch to full replay. A component service that does not answer, a temporary storage error, or no free memory on the executor writes no failed outcome: the start retries with the same record. A target revision that does not exist or that the component service refuses fails the update with a code (see below). While the start replays the history, the agent keeps the status that it had before the restart. An idle agent stays Idle, so an interrupt during that replay is ignored: no Interrupted entry and no failed outcome are written, and the update completes without a resume. When the agent moves to another executor during the replay, that executor runs the attempt again. One case fails the start instead of the update: a full replay whose authoritative baseline cannot be restored fails the start of the agent with a visible cause.

--await waits for that terminal success or failure, including a repeated request for the same target. Reverting away an outcome while retaining the request makes the request pending and retryable again. Snapshot assistance bounds historical replay to the suffix after the selected snapshot; it does not guarantee a wall-clock update bound.

Failure Codes

The details of a failed update start with a code for these causes. golem agent get <AGENT_ID> shows the details in the update history, and golem agent oplog <AGENT_ID> shows them on the FAILED UPDATE entry. The agent stays on its source revision.

Other failures, such as a change of the agent mode, a conflict of the initial files, or a failed check of the agent’s files for a manual update on an executor without filesystem snapshots, have no code; the details give the cause.

How Manual (Snapshot-Based) Update Works

1. The update is queued behind the current and any earlier invocations.
2. At that idle invocation boundary, the old component version’s save-snapshot export is called, which serializes the agent’s current state into a fresh byte payload with a MIME type. Golem also takes a filesystem snapshot of the agent’s files and waits for its upload. On an executor without filesystem snapshots, the update works only while the agent’s files are its initial files; otherwise it fails with UPDATE_NEEDS_FILESYSTEM_SNAPSHOTS.
3. The agent is restarted with the new component version. Golem restores the agent’s files from that filesystem snapshot and applies the initial files of the new version. A changed declaration of an initial file at a path that the agent wrote, changed or deleted fails the update.
4. The new version’s load-snapshot export is called with the fresh snapshot payload.
5. If load-snapshot returns Ok, the agent continues with the new version.
6. If load-snapshot returns Err, the update fails and the agent reverts to the old version.

To implement manual updates, the component must export the save-snapshot and load-snapshot WIT interfaces. Each SDK provides helpers for this — see the language-specific golem-custom-snapshot-* skills for implementation details.