Creating a Golem Agent Instance with golem agent new

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

Usage

golem agent new <AGENT_ID> [OPTIONS]

This creates a new agent instance without invoking any method on it. The agent is initialized with its constructor parameters and starts in an idle state, ready to receive invocations. If the agent's component has not been deployed yet and the CLI is run from an application directory, it will automatically build and deploy the component first.

Unlike golem agent invoke, which implicitly creates the agent on first call, golem agent new explicitly pre-creates the agent — useful when you need to set environment variables or configuration at creation time.

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:

Format	Description
AgentTypeName(params)	Standalone agent name
env/AgentTypeName(params)	Environment-specific
app/env/AgentTypeName(params)	Application and environment-specific
account/app/env/AgentTypeName(params)	Account, application, and environment-specific

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

Examples

Create an agent with no constructor parameters

golem agent new 'MyAgent()'

Create an agent with constructor parameters

golem agent new 'ChatRoom("general")'

Create an agent with environment variables

golem agent new 'MyAgent("user-123")' --env API_KEY=sk-abc123 --env LOG_LEVEL=debug

Create an agent with configuration

golem agent new 'MyAgent()' --config maxRetries=5 --config timeoutSeconds=30

Create an agent in a specific environment

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

Combine environment variables and configuration

golem agent new 'OrderProcessor("us-east")' \
  --env DATABASE_URL=postgres://... \
  --config batchSize=100 \
  --config retryPolicy.maxAttempts=3

Available Options

Option	Description
-e, --env <ENV=VAL>	Environment variables visible to the agent (can be repeated)
-c, --config <PATH=VALUE>	Configuration entries for the agent, using dot-separated paths (can be repeated). Only configuration declared by the agent can be provided. If not provided, the default from the manifest (agents.*.config) is used.

Auto-Deploy

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

Value Syntax

The agent ID parameters 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 new 'UserManager(MyConfig(region = "us-east", maxConnections = Some(10)))'

When to Use golem agent new vs golem agent invoke

• Use golem agent new when you need to pre-create an agent with specific environment variables or configuration before any invocation.
• Use golem agent invoke when you want to call a method — the agent is created automatically on first invocation if it doesn't exist.
• An agent created with golem agent new can be invoked later with golem agent invoke using the same agent ID.