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 command line arguments and environment variables for the agent.

golem agent new 'example:counter/counter-agent("my-counter")' --env A=1 --env B=2 arg1 arg2

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) and (optionally prefixed by the component name, if it is not inferrable from the current context):

golem agent get 'counter-agent("my-counter")'
golem agent get 'example:counter/counter-agent("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 version older than 2 of the component example:counter:

golem agent list --filter "status = Idle" --filter "version < 2" example:counter

⚠️

Enumerating agents is a slow operation and should only be used for debugging an administrative tasks.

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 --enqueue command:

golem agent invoke --enqueue 'counter-agent("my-counter")' 'increment-by' 5

Function parameters can be specified using repeated --arg parameters.

Waiting for result

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

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

Invocation results in WAVE format:
- '5'

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 --idempotency-key parameter for both invoke and invoke-and-await commands.

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 'counter-agent("my-counter")'

You can also use the --stream option on invoke command to connect to the agent right after invoking the command.

Agent update

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

golem agent update 'counter-agent("my-counter")' --target-version 2 --mode auto

The agent update-many with the same --filter parameters as in agent list command can update multiple agents:

golem agent update-many example:counter --filter 'version < 2' --target-version 2 --mode auto

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 'counter-agent("my-counter")'
golem agent resume 'counter-agent("my-counter")'

Testing crash recovery

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

golem agent simulated-crash 'counter-agent("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 'counter-agent("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 'counter-agent("my-counter")'
golem agent invoke 'counter-agent("my-counter")' 'get-value'

Invocation results in WAVE format:
- '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 'counter-agent("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 'counter-agent("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.

Searching for oplog entries

The same command can also be used to search for oplog entries, using the --query parameter. This parameter requires a query using lucene query syntax. The following syntax elements are supported:

search terms looks for search AND terms
AND, OR and NOT
grouping using parentheses ()
"quoted terms"
regular expression matches using /regex/
field:value to search for a specific information

The terms and fields are interpreted in the following way:

Oplog entry	Matching queries
`Create`	`create`
`ImportedFunctionInvoked`	`imported-function-invoked`, match on invoked function's name, match on function arguments(), match on result value()
`ExportedFunctionInvoked`	`exported-function-invoked`, `exported-function`, match on invoked function's name, match on idempotency key, match on function arguments(*)
`ExportedFunctionCompleted`	`exported-function-completed`, `exported-function`, match on response value(*)
`Suspend`	`suspend`
`Error`	`error`, match on error message
`NoOp`	`noop`
`Jump`	`jump`
`Interrupted`	`interrupted`
`Exited`	`exited`
`ChangeRetryPolicy`	`change-retry-policy`
`BeginAtomicRegion`	`begin-atomic-region`
`EndAtomicRegion`	`end-atomic-region`
`BeginRemoteWrite`	`begin-remote-write`
`EndRemoteWrite`	`end-remote-write`
`PendingWorkerInvocation`	`pending-worker-invocation`, match on invoked function's name, match on idempotency key, match on function arguments(*)
`PendingUpdate`	`pending-update`, `update`, match on target version
`SuccessfulUpdate`	`successful-update`, `update`, match on target version
`FailedUpdate`	`failed-update`, `update`, match on target version, match on error details
`GrowMemory`	`grow-memory`
`CreateResource`	`create-resource`
`DropResource`	`drop-resource`
`DescribeResource`	`describe-resource`, match on resource name, match on resource parameters(*)
`Log`	`log`, match on context, match on message
`Restart`	`restart`
`ActivatePlugin`	`activate-plugin`
`DeactivatePlugin`	`deactivate-plugin`
`Revert`	`revert`
`CancelInvocation`	`cancel`, `cancel-invocation`, match on idempotency key
`StartSpan`	`start-span`, `startspan`, match on span ID, match on parent ID, match on linked context, match on attributes(*)
`FinishSpan`	`finish-span`, `finishspan`, match on span ID
`SetSpanAttribute`	`set-span-attribute`, `setspanattribute`, match on key, match on value
`ChangePersistenceLevel`	`change-persistence-level`, `changepersistencelevel`, `persistence-level`

The cases marked with (*) can use the field:value syntax to look into the typed, structured parameter and result values.

For example to look for oplog entries that contain parameters or return values of exported functions where any of these input/output values is a record having a field product-id with either value 123 or 456, we can use the following query:

golem agent oplog --query 'exported-function AND (product-id:123 OR product-id:456)' 'counter-agent("my-counter")'

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 'counter-agent("my-counter")' --last-oplog-index 42

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

golem agent revert 'counter-agent("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 'counter-agent("my-counter")' my-key

Components Profiles