| name | golem-update-running-agents |
| description | Updating running agents to a new component version. Use when asked to update existing agents, explain update modes (auto/manual), or trigger updates via the CLI or deploy command. |
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:
| Mode | CLI Value | Description |
|---|
| Automatic | auto (default) | Replays the agent's operation log against the new component version. Works when the new version is compatible with the old one (same exported functions, compatible signatures). Fails if there is a divergence. |
| Manual | manual | Uses user-defined save-snapshot and load-snapshot functions to serialize the agent's state from the old version and restore it in the new version. Required when the new component is incompatible with the old one (changed function signatures, removed functions, restructured state). |
When to Use Each Mode
- Use
auto when the change is backward-compatible — adding new functions, fixing bugs in existing logic, or changing internal implementation without altering the exported API shape. The operation log can be replayed successfully against the new version.
- 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
| Flag | Description |
|---|
-u, --update-agents <MODE> | Update existing agents with auto or manual mode |
--redeploy-agents | Delete and recreate all existing agents (loses state) |
-r, --reset | Delete agents and the environment, then deploy from scratch |
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 latest) component revision:
golem agent update <AGENT_ID> [MODE] [TARGET_REVISION]
Arguments
| Argument | Description |
|---|
<AGENT_ID> | The agent identifier (e.g., Counter("my-counter")) |
[MODE] | auto (default) or manual |
[TARGET_REVISION] | Target component revision number. Defaults to the latest revision if omitted. |
Flags
| Flag | Description |
|---|
--await | Wait for the update to complete before returning |
--disable-wakeup | Do not wake up suspended agents; the update is applied next time the agent wakes up |
Examples
# Update to latest revision with automatic mode (default)
golem agent update 'Counter("my-counter")'
# Update to latest 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]
Arguments
| Argument | Description |
|---|
--component-name <NAME> | Component to update agents for |
-u, --update-mode <MODE> | auto (default) or manual |
--await | Wait for all updates to complete |
--disable-wakeup | Do not wake up suspended agents |
Examples
# Update all agents of a component
golem component update-agents --component-name my-component
# With manual mode
golem component update-agents --component-name my-component -u manual --await
Method 4: Application-Level Bulk Update
Update all agents across all components in the current application:
golem app update-agents [OPTIONS]
Arguments
| Argument | Description |
|---|
--component-name <NAME> | Optional filter to specific components (can be repeated) |
-u, --update-mode <MODE> | auto (default) or manual |
--await | Wait for all updates to complete |
--disable-wakeup | Do not wake up suspended agents |
Examples
# Update all agents in the application
golem app update-agents
# Update only agents of specific components
golem app update-agents --component-name comp-a --component-name 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
- The agent is interrupted.
- The agent's operation log (oplog) is replayed from the beginning against the new component version.
- If replay succeeds, the agent resumes with the new version.
- If replay fails (e.g., a function no longer exists or has an incompatible signature), the update fails and the agent reverts to the old version.
How Manual (Snapshot-Based) Update Works
- The agent is interrupted.
- The old component version's
save-snapshot export is called, which serializes the agent's state into a byte payload with a MIME type.
- The agent is restarted with the new component version.
- The new version's
load-snapshot export is called with the snapshot payload.
- If
load-snapshot returns Ok, the agent continues with the new version.
- 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.
