Schedule work and manage agent lifetime

Overview

Timers serve active-process work. Reminders are scheduled through Orleans and are durable only when the configured reminder provider is durable. Reset/reconfigure, deactivation, thread clearing and eviction have different effects and should not be interchangeable UI actions.

Timers require a live activation

A timer is useful for a short periodic action while an agent is active. It is not a promise that work will execute after the process exits. A reminder is registered with Orleans and can be recovered according to its reminder provider. A durable registration still needs idempotent business logic: a retry must not accidentally send a second notification or repeat a write.

Lifecycle actions are not interchangeable

Restart/reconfiguration reconstructs behavior using configuration and stored state. Reset can clear conversation or custom state. Eviction removes runtime/persisted agent state rather than merely pausing it. Choose an operation based on what should be retained. If a runbook says “restart to fix it,” make the intended retained state explicit before implementing the button.

Choose a scheduling lifetime

1. Use a timer for short local polling and a reminder for a persisted scheduled operation. Inject TimeProvider for deterministic scheduling tests.
2. Expose lifecycle actions with their effects: reconfigure changes behavior, deactivation allows later activation, and hard eviction removes the instance's durable state.
3. Record business operation identity before external work so a repeated reminder can check whether its effect already occurred.

// In OnInitialize or OnMessage
fabrcoreAgentHost.RegisterTimer(
    timerName: "health-check",
    messageType: "timer:health-check",
    message: null,
    dueTime: TimeSpan.FromMinutes(1),
    period: TimeSpan.FromMinutes(5));

// Timer fires come as regular messages in OnMessage
public override async Task<AgentMessage> OnMessage(AgentMessage message)
{
    if (message.MessageType == "timer:health-check")
    {
        var response = message.Response();
        response.Message = "Health check complete";
        return response;
    }
    // Normal message processing...
}

// Unregister
fabrcoreAgentHost.UnregisterTimer("health-check");

await fabrcoreAgentHost.RegisterReminder(
    reminderName: "daily-report",
    messageType: "reminder:daily-report",
    message: "Generate daily summary",
    dueTime: TimeSpan.FromHours(1),
    period: TimeSpan.FromHours(24));

// Override in your agent
public override Task OnReminder(string reminderName)
{
    if (reminderName == "daily-report")
    {
        // Perform periodic check
    }
    return Task.CompletedTask;
}

await fabrcoreAgentHost.UnregisterReminder("daily-report");

Go deeper

Explore the related documentation.

• FabrCore Persistence
• FabrCore Compaction
• FabrCore Configuration
• Reminders (Persistent)