Scheduler Replay Safety

Scheduler retries skip re-running a failed task when the agent holds an effectful (non-idempotent) tool

The scheduler will not re-run a failed task that may already have called an effectful tool, so one transient hiccup can never duplicate an email or double-charge a card.

Diagram

yes

no

📅 Scheduled Run

❌ Fail

🔍 Effectful tool?

🛑 Stop + on_failure

🔄 Retry with backoff

Quick Start

  1. Mark your effectful tool

    One attribute on the tool is all it takes.

    python
    from praisonaiagents import Agent
    
    def send_email(to: str, subject: str, body: str) -> str:
        """Send mail — must not be retried."""
        return f"Sent '{subject}' to {to}"
    
    send_email.restart_safe = False  # one line is enough
    
    agent = Agent(name="Notifier", instructions="Send the daily brief.", tools=[send_email])

    @tool(restart_safe=False) from praisonaiagents works the same way.

  2. Schedule it as usual

    No new scheduler params.

    python
    from praisonai.scheduler import AgentScheduler
    
    scheduler = AgentScheduler(agent, task="Send Alice her 9am brief", on_failure=print)
    scheduler.start("daily", max_retries=3)
    # A failed run is recorded and on_failure fires — the task is NOT re-run.
  3. Keep idempotent tools retryable

    Read-only tools keep the normal retry behaviour.

    python
    def fetch_report(url: str) -> str:
        """Read-only — safe to retry."""
        return f"Report from {url}"
    
    fetch_report.restart_safe = True  # explicit opt-in to retry

How It Works

A scheduler retry re-runs the whole task, so the gate checks the agent’s reachable tools before every re-run.

Diagram
send_emailAgentSchedulerUsersend_emailAgentSchedulerUserstart(“daily”, max_retries=3)attempt 1send_email(…)sent ✉️❌ error after the tool raneffectful tool declared?on_failure(“Failed after 1 attempts”)
StepWhat happens
Attempt failsThe error is logged and counted
Gate checkScheduler scans the agent’s tools for restart_safe=False / idempotent=False
UnsafeRetry loop stops; failure is recorded, state persisted, on_failure fires
Safe or undeclaredRetry with backoff, up to max_retries

The gate applies to both AgentScheduler and AsyncAgentScheduler, including the async timeout path. It does not know when the run failed, so a declared-effectful agent is never re-run, even if the tool had not been called yet.

What the Gate Checks

Source of toolChecked by the gate?
Agent(tools=[...])✅
PraisonAIAgents(agents=[...]) — team member tools✅ every member’s tools
Task(tools=[...]) on a team✅ every task’s tools
ToolConfig(allow_global_tools=True) — registry tools✅ registry scanned when the flag is set on any member
Undeclared tool (no restart_safe / idempotent)⏭️ Treated as safe to retry (backward-compatible)

Per tool, idempotent is checked first, then restart_safe; the first boolean wins.

What You See on a Blocked Retry

ERROR praisonai.scheduler: Agent execution failed on attempt 1: <error>
ERROR praisonai.scheduler: Not retrying: the agent has an effectful tool (restart_safe=False) that may already have run
ERROR praisonai.scheduler: Agent execution failed after 1 attempts

on_failure receives "Failed after 1 attempts". The count reflects actual attempts, not max_retries.

Which Flag Should I Set?

Diagram

Reads only

Mail, order, payment, external write

Not sure

What does the tool do?

restart_safe = True

restart_safe = False

Leave undeclared

Leaving a tool undeclared keeps the old retry behaviour — a transient error after the side effect may duplicate it, so restart_safe = False is the safer choice for anything effectful.

Best Practices

Declare restart_safe on anything that touches the outside world

Email, payments, orders, and external writes should all carry restart_safe = False. Undeclared tools are retried.

Expect actual attempt counts

The failure message reports attempts actually made ("Failed after 1 attempts"), not the configured max_retries.

Team, task, and registry tools all count

One effectful tool anywhere in the agent’s reachable toolset blocks the whole-task retry.

Pair with the per-turn gate

Replay-Safe Retries protects a single turn’s provider call; this gate protects the scheduler’s whole-task retry.

Related