Skip to Content
How-To GuidesMoonBitScheduling a Future Agent Invocation

Scheduling a Future Agent Invocation

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

Usage

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

The --schedule-at flag 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.

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

MoonBit-Specific Notes

  • Method names use snake_case — the same as written in the MoonBit source code
  • Agent type names use PascalCase — the struct name from the MoonBit source

Examples

Schedule a method to run at a specific time

golem agent invoke --trigger --schedule-at 2026-03-15T10:30:00Z 'MyAgent()' run_daily_report

Schedule with parameters

golem agent invoke --trigger --schedule-at 2026-04-01T00:00:00Z 'BatchProcessor("daily")' generate_report '"Q1-2026"'

Schedule in a specific environment

golem agent invoke --trigger --schedule-at 2026-03-15T08:00:00Z 'production/NotificationAgent()' send_reminders

Schedule with an idempotency key for deduplication

golem agent invoke --trigger --schedule-at 2026-03-15T10:30:00Z -i 'report-2026-03-15' 'ReportAgent()' generate_daily

Available Options

OptionDescription
-t, --triggerRequired with --schedule-at. Fire-and-forget mode
--schedule-at <DATETIME>The time to execute the invocation (ISO 8601 / RFC 3339)
-i, --idempotency-key <KEY>Set a specific idempotency key; use "-" for auto-generated
--no-streamDisable live streaming of agent stdout/stderr/log

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

Idempotency

Scheduled invocations use idempotency keys just like regular invocations. Providing the same idempotency key for a scheduled invocation ensures it is not executed more than once, even if the CLI command is retried.

Auto-Deploy

If the agent’s component has not been deployed yet and the CLI is run from an application directory, the command will automatically build and deploy the component before scheduling.

Value Syntax

Pass one native argument per user-supplied method parameter in signature order, excluding self and config parameters. Skip host-injected Principal fields; do not supply a principal value or placeholder. Do not wrap all parameters in a JSON object. No-parameter methods take no arguments, not '{}'. --format json controls output only. Load golem-invoke-agent-moonbit for the string fallback and the different HTTP body rules. Awaited, triggered, and scheduled invocations share the same CLI argument parser.

The agent ID parameters and method arguments use MoonBit syntax:

  • Field names use snake_case
  • Options: Some(value) / None
  • Records: MyRecord::{ field_one: 1, field_two: "hello" }
  • Enums/Variants: MyEnum::VariantName(value)
  • Tuples: (1, "hello")

This example assumes pub fn MyAgent::run_task(self : Self, config : TaskConfig) -> Unit, where TaskConfig has a priority : UInt field and a retry : Bool field. Pass the single config value, not a wrapper containing config:

golem agent invoke --trigger --schedule-at 2026-03-15T10:30:00Z 'MyAgent("user-123")' run_task 'TaskConfig::{ priority: 1, retry: true }'
Saga-Pattern Transactions (MoonBit)Scheduling a Future Agent Invocation (MoonBit)