Invoking a Go Golem Agent with golem agent invoke

Overview

golem agent invoke calls a method on a deployed agent and waits for the result. The agent is created automatically 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.

Both golem and golem-cli can be used — every command below works with either binary.

Steps

1. Identify the agent by its type name and constructor parameters (CounterAgent("my-counter")).
2. Pick the method to call (the WIT name, e.g. increment, add, value).
3. Run golem agent invoke with the agent ID, method name, and any arguments.
4. Read the result — text by default, or --format json / --format yaml for machine output.

Usage

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

Encoding Parameters

Pass one shell argument per exported field of the method’s input struct, in declaration order. Do not pass a JSON object wrapping all fields. A struct-valued field is one argument.

Skip golem.Principal fields: the host fills them. Do not supply a principal value or placeholder, and keep the order of the other fields. Awaited, triggered, and scheduled invocations share the same CLI argument parser.

For a method whose input is golem.Unit or has no user-supplied fields, omit arguments; history '{}' supplies an extra argument. Quote each Go literal as one shell argument. For a string field, if Go literal parsing fails, the CLI uses the argument as raw text. Passing '{"text": "hello"}' to prompt therefore passes that entire JSON text as the string; it does not extract text.

Custom HTTP endpoints use a different rule: structured JSON bodies contain the named body fields, even for one field. The submit method above needs {"request": {"text": "hello"}} over HTTP when Request is a body field. Path/query/header fields are not body fields; unstructured text and binary fields use raw bodies. Load golem-http-params-go for HTTP mapping.

--format json selects output formatting, not input encoding. Triggered and scheduled CLI invocations use the same positional arguments.

Agent ID Format

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

AgentTypeName(param1, param2, ...)

For a Go agent, the constructor parameters are the fields of its ID struct in declaration order. CounterAgent’s ID is struct{ Name string }, so its ID is CounterAgent("my-counter"). For an agent whose ID has no fields (a singleton), use empty parentheses: AgentTypeName().

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

Examples

Invoke a method with no parameters

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

Invoke a method with an argument

add takes one parameter (the By field of AddIn), passed positionally:

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

Read the current value

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

Invoke in a specific environment

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

Invoke with an explicit idempotency key

golem agent invoke -i my-unique-key 'CounterAgent("my-counter")' increment

Output

Text output renders return values in Go syntax, as in the value syntax below. Methods returning golem.Unit or no value print void in text mode.

For machine-readable output, use --format json or --format yaml. A single return value includes result plus resultJson; multiple return values include result plus resultsJson; methods returning no value omit result fields.

Available Options

Value Syntax

Agent ID parameters and method arguments use Go syntax, read against the agent’s schema:

• Strings "my-counter", runes 'x', integers 5, floats 2.5, booleans true / false.
• Each exported field of a Go input struct is one positional parameter, named in lowerCamelCase with each initialism as one word (AmountCents → amountCents, UserID → userId, APIKey → apiKey).
• Structs, lists and tuples are composite literals without their type, with field names as published: {zone: "a", level: 2}, {"x", "y"}.
• Maps: { "k" => 1 }. Options (pointer fields): the value itself, or nil. Results: Ok(v) / Err(e).
• Enum constants and variant cases by their published name: closed, card{number: "1"}, amount(42).
• Rich values as constructors: Uuid("…"), Datetime("2026-01-01T00:00:00Z"), Duration("PT30S") (or 30 * time.Second).

For example: golem agent invoke 'ShelfAgent({zone: "a", level: 2}, closed, {"x"})' describe '"fragile"' '{ "k" => 2 }'.

Key Constraints

• golem agent invoke blocks until the agent returns; use --trigger for fire-and-forget.
• Every invocation uses an idempotency key (auto-generated if not supplied), guaranteeing at-most-once execution even if the CLI retries.
• If the component is not deployed yet and the CLI runs from an application directory, the command auto-builds and deploys it before invoking.
• The agent ID’s constructor arguments must match the fields of the Go ID struct in order.

Related Guides