Invoking a Golem Agent with golem agent invoke

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

Usage

golem agent invoke <AGENT_ID> <FUNCTION_NAME> [ARGUMENTS...]

This invokes a method on a deployed agent and waits for the result. The agent is automatically created on first invocation if it does not exist yet. Standard output, error, and log streams from the agent are streamed live to the terminal by default.

Agent ID Format

The agent ID identifies the agent type and its constructor parameters:

AgentTypeName(param1, param2, ...)

The agent ID can optionally be prefixed with environment or application paths:

For agents with no constructor parameters, use empty parentheses: AgentTypeName().

Examples

Invoke a method with no parameters

golem agent invoke 'MyAgent()' getStatus

Invoke a method with parameters

golem agent invoke 'MyAgent("user-123")' processOrder '"order-456"' 42

Invoke with an agent that has constructor parameters

golem agent invoke 'ChatRoom("general")' sendMessage '"Hello, world!"'

Invoke in a specific environment

golem agent invoke 'staging/MyAgent("user-123")' getStatus

Available Options

Idempotency

Every invocation uses an idempotency key. If not provided, one is generated automatically. The same idempotency key guarantees that the invocation is executed at most once, even if the CLI call is retried.

golem agent invoke -i my-unique-key 'MyAgent()' doWork

Auto-Deploy

If the agent's component has not been deployed yet and the CLI is run from an application directory, golem agent invoke will automatically build and deploy the component before invoking.

Value Syntax

The agent ID parameters and method arguments use Scala syntax:

• Field names use camelCase with = separator
• Options: Some(value) / None
• Records: MyRecord(fieldOne = 1, fieldTwo = "hello")
• Enums/Variants: MyEnum.VariantName or MyEnum.VariantName(value)
• Tuples: (1, "hello") or Tuple1(value) for single-element
• Results: WitResult.Ok(value) / WitResult.Err(value)

golem agent invoke 'MyAgent("user-123")' updateProfile 'MyProfile(displayName = "Alice", age = Some(30))'