Golem CLI Agents

Using golem agent command you can:

• Start and stop agent
• Interrupt and resume agents
• Invoke agent function
• Get agent stdout, stderr and logs
• Update agents
• Search agents, get metadata, etc.
• Revert a agent to a previous state

Create a new agent

Even though agents can automatically start on the first invocation, it is possible to explicitly start an agent. This allows specifying environment variables (--env) and configuration values (--config) for the agent.

golem agent new 'CounterAgent("my-counter")' --env A=1 --env B=2

Get agent metadata

Using the agent ID

You can get the agent metadata using the agent-id (the agent type and it’s constructor parameters), optionally prefixed by the environment name (<ENVIRONMENT>/, <APPLICATION>/<ENVIRONMENT>/ or <ACCOUNT>/<APPLICATION>/<ENVIRONMENT>/) if it is not inferrable from the current context:

golem agent get 'CounterAgent("my-counter")'
golem agent get 'staging/CounterAgent("my-counter")'

Search agents

You can search for agents of some components or agent types using the agent list command with one or more --filter arguments.

For instance lets find idle agents with component revision older than 2 of the component example:counter:

golem agent list --filter "status = Idle" --filter "revision < 2" --component-name example:counter

Invoking agent methods

The folowing section shows the basics of invoking agents through the CLI. See the dedicated invocation with CLI page for more details.

Without waiting for result

You can invoke an agent function without waiting for function result using agent invoke --trigger command:

golem agent invoke --trigger 'CounterAgent("my-counter")' add 5

Waiting for result

You can invoke an agent method and wait for result using agent invoke command:

golem agent invoke 'CounterAgent("my-counter")' value

Invocation result in TypeScript syntax:
5

The result is rendered using the source-language syntax of the agent.

Using idempotency key

If you want to make sure function was called only once even if you called CLI multiple times (for instance due to retries on network errors) you can use the --idempotency-key parameter of the invoke command, both with and without --trigger.

You can use any string as idempotency key.

Live streaming agent logs

You can connect to your running agent and stream its logs using the agent stream command:

golem agent stream 'CounterAgent("my-counter")'

By default, the invoke command streams the agent’s output. Use the --no-stream option to disable this.

Agent update

To update the agent to a specific component revision, use the agent update command:

golem agent update 'CounterAgent("my-counter")' auto 2

Interrupt and resume agents

If you want to interrupt and later resume a long-running agent you can use interrupt and resume commands:

golem agent interrupt 'CounterAgent("my-counter")'
golem agent resume 'CounterAgent("my-counter")'

Testing crash recovery

There is a special command to simulate a crash on an agent:

golem agent simulate-crash 'CounterAgent("my-counter")'

Deleting agents

Idle agents are not actively consuming resources but they take storage as their state is persisted. An agent can be deleted using the agent delete command:

golem agent delete 'CounterAgent("my-counter")'

This command deletes agent state.

Please note that a next invocation to the same agent will recreate it with fresh state:

golem agent delete 'CounterAgent("my-counter")'
golem agent invoke 'CounterAgent("my-counter")' value

Invocation result in TypeScript syntax:
0

Oplog query

It is possible to query an existing agent’s oplog for debugging purposes. To get the full oplog of an agent, use the agent oplog command:

golem agent oplog 'CounterAgent("my-counter")'

With the optional --from parameter it is possible to only get oplog entries after a certain oplog index:

golem agent oplog --from 100 'CounterAgent("my-counter")'

Oplog entries are indexed from 1, and the first entry is always a create entry that defines the initial state of the agent.

Viewing the oplog in a browser

The oplog can be explored in an interactive HTML viewer instead of the terminal. The viewer groups the entries by invocation, merges each durable host call’s start and end entries into one foldable row with its duration, nests the entries executed by tool entities under the tool invocation, and marks the regions skipped by a jump or a revert. It can filter by entry category, log level or index range, search the content of the entries, decode typed payloads, binary and snapshot data, and it shows per-invocation and per-type statistics.

The --serve parameter starts a local server that hosts the viewer and opens it in the default browser:

golem agent oplog 'CounterAgent("my-counter")' --serve

The served viewer loads the oplog page by page through the API, so it works for oplogs of any size. It can run a Lucene query on the server (the same syntax as --query, see below), load the context around a query hit, jump to any oplog index, and follow a running agent by polling for new entries. --from and --query select the initial position and query of the viewer. Use --port to choose the port and --no-open to skip opening the browser. The server runs until it is interrupted.

The --html parameter writes a self-contained HTML file instead, with every selected entry embedded in the page:

golem agent oplog 'CounterAgent("my-counter")' --html oplog.html --open

The generated file has no external dependencies, so it can be opened directly from disk or shared. --open opens it in the default browser. Because the page embeds all entries, it is meant for oplogs of moderate size; use --from or --query to narrow the selection, or --serve for large oplogs. The static viewer can also load a dump produced by --format json through its Load JSON button.

Searching for oplog entries

Use golem agent oplog --query to return matching entries. --query cannot be combined with --from. The query language supports a subset of Lucene syntax:

• search terms requires both terms. Unquoted terms are case-insensitive substring matches.
• Uppercase AND, OR, and NOT combine or exclude matches. Each condition applies to the same entry, but can match a different value within it.
• Parentheses () group conditions. Use explicit operators and parentheses when mixing AND and OR: whitespace conjunction has lower precedence than OR, unlike explicit AND.
• "quoted terms" matches a case-sensitive substring, not a whole field value.
• /regex/ uses Rust regular expression syntax . Matches are case-sensitive unless the pattern enables another mode, such as /(?i)timeout/. Use ^ and $ to match a complete value.
• field:value or field=value restricts a match to an exposed field path. field:(first OR second) groups conditions under that path.

Wildcards, range queries, and fuzzy matching are not supported. Use regular expressions rather than treating * or ? in a bare term as wildcards.

The terms and fields are interpreted in the following way:

Unquoted terms match substrings: start also matches agent-invocation-started, and snapshot also matches snapshot-confirmed. These are searchable aliases, not exact entry-type filters; a term can also match a payload. Most entry kinds also match their name without dashes (for example pendingupdate), except CancelPendingInvocation.

Search does not inspect every displayed field. Displayed metadata such as timestamps, indices, and the host function’s name does not automatically provide a field qualifier. Search a host function or agent method name with a bare term, not function_name:.... Invocation arguments and results are not searched by the invocation entries above.

The cases marked with (*) support paths into typed values. For host calls, start with request, response, or partial, followed by record field names, for example request.product-id:123. Tuple elements use numeric segments, such as request.0; list elements share the list’s path rather than adding an index. Field paths are case-insensitive and must match the complete exposed path. Tool attachment and stream records start at their own typed root, without a request prefix. A stream handle inside a typed value does not cause search to read the stream’s contents.

Span information belongs to host-call entries, not separate StartSpan, FinishSpan, or SetSpanAttribute entries:

For example, span-started.attributes.region:eu searches a span attribute named region. Attribute keys containing dots cannot be addressed by a field qualifier; search their values with an unqualified term instead.

To find host-call requests with a product-id field whose complete value is 123 or 456, use an anchored regular expression:

golem agent oplog 'CounterAgent("my-counter")' --query 'request.product-id:/^(123|456)$/'

Reverting an agent

It is possible to revert an agent to its previous state. This can be useful if an agent got into a failed state to make it usable again, or to undo some accidental invocations or updates.

There are two possible ways to specify which state to revert to:

• By index: The index of the oplog entry to revert to. Use the oplog query command to check the agent’s oplog and find the index of the desired state.
• By undoing the last invocations: The given number is the number of invocations to revert.

To revert to a given oplog, use the agent revert command:

golem agent revert 'CounterAgent("my-counter")' --last-oplog-index 42

To revert some of the last invocations, use the --number-of-invocations parameter instead:

golem agent revert 'CounterAgent("my-counter")' --number-of-invocations 3

Cancelling a pending invocation

If an invocation is enqueued for an agent, but it has not been started yet, it can be removed from the invocation queue by using it’s idempotency key:

golem agent cancel-invocation 'CounterAgent("my-counter")' my-key

Shell access

Use golem ssh to run shell commands on an agent. See Agent Shell Access for interactive sessions, scripts, access controls, and recovery after a disconnect.