Scheduling a Future Agent Invocation from the CLI

Overview

The --schedule-at flag on golem agent invoke schedules the invocation to execute at a specific future time. It requires the --trigger flag, because scheduled invocations are always fire-and-forget — the CLI returns immediately after the invocation is enqueued, and the Golem runtime executes it when the scheduled time arrives.

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 and any arguments (e.g. increment, add 5).
3. Choose the time in ISO 8601 / RFC 3339 format with a timezone.
4. Run golem agent invoke --trigger --schedule-at <DATETIME> — the CLI returns immediately.

Usage

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

DateTime Format

The --schedule-at value must be in ISO 8601 / RFC 3339 format with a timezone:

2026-03-15T10:30:00Z          # UTC
2026-03-15T10:30:00+02:00     # With timezone offset

Examples

Schedule a method to run at a specific time

golem agent invoke --trigger --schedule-at 2026-03-15T10:30:00Z 'CounterAgent("my-counter")' increment

Schedule with an argument

golem agent invoke --trigger --schedule-at 2026-04-01T00:00:00Z 'CounterAgent("my-counter")' add 5

Schedule in a specific environment

golem agent invoke --trigger --schedule-at 2026-03-15T08:00:00Z 'production/CounterAgent("my-counter")' increment

Schedule with an idempotency key for deduplication

golem agent invoke --trigger --schedule-at 2026-03-15T10:30:00Z -i 'increment-2026-03-15' 'CounterAgent("my-counter")' increment

Available Options

How It Works

1. The CLI sends the invocation request with the scheduled time to the Golem server.
2. The server enqueues the invocation to execute at the specified time.
3. The CLI returns immediately with the idempotency key.
4. At the scheduled time, the Golem runtime executes the invocation.

Value Syntax

Pass one Go literal per exported field of the method’s input struct, in declaration order. Skip golem.Principal fields; do not supply a principal value or placeholder. Do not wrap all fields in a JSON object. A method whose input is golem.Unit takes no arguments, not '{}'. --format json controls output only. Load golem-invoke-agent-go for the string fallback and the different HTTP body rules. Awaited, triggered, and scheduled invocations share the same CLI argument parser.

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 }'.

This example assumes type RunTaskIn struct{ Config TaskConfig } with type TaskConfig struct{ Priority uint32; Retry bool }. Pass the single config value, not a wrapper containing config:

golem agent invoke --trigger --schedule-at 2026-03-15T10:30:00Z 'MyAgent("user-123")' runTask '{priority: 1, retry: true}'

Key Constraints

• --schedule-at requires --trigger; a scheduled invocation is always fire-and-forget.
• The datetime must include a timezone (RFC 3339); use Z for UTC.
• Scheduled invocations use idempotency keys just like regular invocations — the same key is not executed more than once.
• To schedule a future call from inside agent code (rather than the CLI), use Method.Schedule — see golem-schedule-future-call-go.

Related Guides