Triggering a Fire-and-Forget Agent Invocation

Overview

The --trigger (or -t) flag on golem agent invoke sends the invocation request to the agent and returns immediately without waiting for the result. The invocation is enqueued and executed asynchronously by the Golem runtime.

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 enqueue (e.g. increment, add).
3. Run golem agent invoke --trigger — the CLI returns as soon as the invocation is accepted.

Usage

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

When to Use Trigger

• When the caller does not need the return value
• When you want to start a long-running operation without blocking
• When enqueuing work for background processing
• When combined with --schedule-at for future execution (see golem-schedule-agent-go)

Examples

Trigger a method with no wait

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

Trigger with an argument

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

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

Trigger in a specific environment

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

Trigger with an explicit idempotency key

golem agent invoke --trigger -i 'increment-2026-01-15' 'CounterAgent("my-counter")' increment

Available Options

Difference from Regular Invoke

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

• Triggered invocations still use idempotency keys — the same key is not executed twice.
• There is no way to read a return value from a triggered invocation; use plain golem agent invoke when you need the result.
• If the component is not deployed yet and the CLI runs from an application directory, the command auto-builds and deploys it before triggering.

Related Guides