Scheduler Delivery

Set deliver= on a scheduled agent and each result is pushed to a chat target — no gateway required.

New: every delivered brief is now a continuable conversation by default — a user’s reply in the same chat resumes the job’s turn with the brief in context. Opt out per-job with --no-continuable for pure notifications. See Continuable Delivery.

from praisonaiagents import Agent
from praisonai.scheduler import AgentScheduler

agent = Agent(name="Brief", instructions="Summarise the morning news")
AgentScheduler(agent, task="Morning brief", deliver="telegram:123456").start("hourly")

“Run this agent every hour and text me the result on Telegram.” That used to mean wiring up the scheduler and the full BotOS gateway. Now it’s one parameter — the scheduler talks to the shared DeliveryRouter directly.

If praisonai-bot isn’t installed, delivery logs a single warning and no-ops. The scheduled run itself never fails because delivery failed.

Quick Start

Deliver to a specific chat

from praisonaiagents import Agent
from praisonai.scheduler import AgentScheduler

agent = Agent(name="Brief", instructions="Summarise the morning news")

scheduler = AgentScheduler(agent, task="Morning brief", deliver="telegram:123456")
scheduler.start("hourly")

Deliver to the platform home channel

from praisonaiagents import Agent
from praisonai.scheduler import AgentScheduler

agent = Agent(name="Brief", instructions="Summarise the morning news")

# Bare platform token → router resolves the platform's home channel
scheduler = AgentScheduler(agent, task="Morning brief", deliver="telegram")
scheduler.start("daily")

Reply back to the origin chat

from praisonaiagents import Agent
from praisonai.scheduler import AgentScheduler

agent = Agent(name="Brief", instructions="Summarise the morning news")

# Inside a bot handler: the incoming request's origin is persisted on the job
# config, so deliver="origin" resolves it on the lightweight path.
scheduler = AgentScheduler(
    agent,
    task="Daily brief",
    deliver="origin",
    config={"origin": incoming_origin},  # persisted ScheduleJob.origin (DeliveryTarget or dict)
)
scheduler.start("daily")
# Fires every day and delivers back to the same channel/thread the user
# scheduled it from — no gateway required.

Async scheduler

import asyncio
from praisonaiagents import Agent
from praisonai.scheduler import AsyncAgentScheduler

async def main():
    agent = Agent(name="Brief", instructions="Summarise the morning news")
    scheduler = AsyncAgentScheduler(agent, task="Morning brief", deliver="telegram:123456")
    await scheduler.start("hourly")

asyncio.run(main())

Three Ways to Set the Target

The same delivery token works from Python, YAML, and the CLI.

Python
YAML
CLI

from praisonaiagents import Agent
from praisonai.scheduler import AgentScheduler

agent = Agent(name="Brief", instructions="Summarise the morning news")
AgentScheduler(agent, task="Morning brief", deliver="telegram:123456").start("hourly")

# agents.yaml
framework: praisonai

agents:
  - name: "Brief"
    instructions: "Summarise the morning news"

task: "Morning brief"

schedule:
  every: "hourly"          # alias for `interval` — new in PR #2934
  deliver: "telegram:123456"

praisonai schedule add "morning-brief" \
  -s hourly \
  -m "Morning brief" \
  --deliver telegram:123456

every: is a new alias for interval: in the YAML schedule: block — both accept hourly, daily, weekly, */30m, or raw seconds.

Tools in scheduled YAML

The tools: list inside agents.yaml resolves through the same ToolResolver that praisonai run agents.yaml uses — so any tool name the CLI accepts also works when the file is scheduled via AgentScheduler.from_yaml() or AsyncAgentScheduler.from_yaml(). See Tool Resolver.

# agents.yaml
framework: praisonai

agents:
  - name: "News Monitor"
    role: "News Analyst"
    goal: "Track AI news"
    instructions: "Search and summarise the last 24h."
    tools:
      - duckduckgo          # any tool praisonai run accepts, not just search_tool
      - internet_search

task: "Search for latest AI news"

schedule:
  every: "hourly"
  deliver: "telegram:12345"

Before PraisonAI #3420, the scheduled YAML loader only recognised the hardcoded names search_tool / InternetSearchTool — every other tool was silently dropped and the agent ran with tools=[]. The scheduler now uses the canonical ToolResolver, keeping CLI, Python, and scheduled surfaces identical.

Which surface fits which scenario?

Delivery Target Tokens

The deliver value is parsed by DeliveryTarget.parse() — the same serialisable model reused from the existing delivery machinery.

platform                          # bare platform, uses configured default channel
platform:channel_id               # concrete channel
platform:channel_id:thread_id     # threaded delivery (Slack thread ts,
                                  #   Telegram forum topic id, Discord thread id)
origin                            # persisted job origin (resolves on the lightweight path)
all                               # fan out to every bot (gateway only)

Token	Meaning
`"telegram"`	Default (home) channel of that platform
`"telegram:123456"`	Specific channel / chat ID
`"telegram:123456:789"`	Channel `123456`, delivered into thread `789`
`"origin"`	Reply to the same channel/thread the schedule was created from
`"all"`	Fan out to every configured bot (gateway only)

origin now works on the lightweight scheduler path when the job has a persisted origin (ScheduleJob.origin — set automatically when a job is created from a bot/webhook request). It resolves to the same channel/thread the request came in on, no gateway required. If the job has no persisted origin, the lightweight path logs a warning and skips delivery. Only all still needs the full gateway — it enumerates every registered bot.

Thread semantics per platform

The third :thread_id segment threads the outbound message. DeliveryRouter.resolve() returns (platform, channel_id, thread_id) and deliver() passes thread_id into bot.send_message(...). Adapters without a thread_id kwarg are unaffected — a guard introspects the adapter first.

Platform	`thread_id` semantics
Slack	Parent message `ts` (thread timestamp)
Telegram	Forum topic `message_thread_id`
Discord	Thread channel ID
WhatsApp	Ignored (no thread concept)
Others	Silently ignored — adapters without a `thread_id` kwarg are unaffected

from praisonaiagents import Agent
from praisonai.scheduler import AgentScheduler

agent = Agent(name="Notify", instructions="Post the hourly status")
AgentScheduler(agent, task="Notify", deliver="slack:C0123456:1728987654.001234").start("hourly")
# Delivers into the Slack thread rooted at message ts 1728987654.001234.

Swap telegram for discord, slack, or whatsapp — the grammar is identical.

Deliver back to the origin channel

Use deliver="origin" when the schedule was created from a chat and you want the recurring result to land back in that same chat — without wiring up a specific platform:channel_id token.

from praisonaiagents import Agent
from praisonai.scheduler import AgentScheduler

agent = Agent(name="Brief", instructions="Summarise the morning news")

# Job was created from a Telegram chat — its origin is persisted on
# ScheduleJob.origin at creation. deliver="origin" delivers back to it.
scheduler = AgentScheduler(agent, task="Morning brief", deliver="origin")
scheduler.start("hourly")

How origin resolution works: SchedulerDelivery.origin_from_config() normalises the origin whether it is a live DeliveryTarget or its persisted dict form (from to_dict()), so scheduled jobs restored from disk resolve correctly too.

deliver="origin" still logs a warning and no-ops if the job was created without an origin channel — for example, a job created purely from Python code with no chat context. In that case, use an explicit platform:channel_id token.

Continuable Delivery

A delivered brief is a conversation opener, not a dead-end. Reply in the same chat and the agent picks up where the brief left off — with the delivered text already in context. Zero configuration, on by default. Before / after #3449:

Scenario	Before #3449	After #3449 (default)
User replies to a delivered daily-brief with “why did revenue dip on Tuesday?”	Reply lands as a new turn — agent has no idea which report this refers to.	Reply resumes the job’s session — agent sees the brief it just delivered and answers in context.
Config required	Manually pre-wire `session_id` on `DeliveryTarget`.	None — `continuable=True` is the default.
Fire-and-forget notice (e.g. “backup finished”)	Same as above.	Set `continuable=False` (or `--no-continuable`) to opt out.

Quick start — nothing to do

Continuable delivery is default-on. Every scheduled job with a delivery target already resumes its conversation on reply:

from praisonaiagents import Agent
from praisonai.scheduler import AgentScheduler

agent = Agent(name="Brief", instructions="Summarise the morning news")
AgentScheduler(agent, task="Morning brief", deliver="telegram:123456").start("hourly")

# User replies "expand on item 2" in chat 123456 → resumes the job's conversation
# with the brief already in context. No wiring, no session id, no re-briefing.

Opt out for fire-and-forget alerts

Some deliveries are pure notifications (“build finished”, “backup ok”) — a reply should stay a fresh turn, not resume a maintenance job. Turn seeding off with a single flag:

cron: schedules (like cron:0 3 * * * below) honour wall-clock time-of-day and survive restarts (introduced in PR #3527). Install croniter (pip install croniter) to enable this — without it the wrapper falls back to a coarse interval and warns once. See Wall-clock cron.

CLI
Tool
Python

praisonai schedule add "backup-alert" \
  -s "cron:0 3 * * *" \
  -m "Backup ok" \
  --deliver "slack:C012345" \
  --no-continuable

from praisonaiagents.tools import schedule_add

schedule_add(
    name="backup-alert",
    schedule="cron:0 3 * * *",
    message="Backup ok",
    deliver="slack:C012345",
    continuable=False,      # fire-and-forget notification
)

from praisonaiagents.scheduler.models import DeliveryTarget, ScheduleJob, Schedule

job = ScheduleJob(
    name="backup-alert",
    schedule=Schedule(kind="cron", cron_expr="0 3 * * *"),
    message="Backup ok",
    delivery=DeliveryTarget(
        channel="slack",
        channel_id="C012345",
        continuable=False,   # opt out — reply lands as a fresh turn
    ),
)

The seed contract

Given a successful delivery of text to channel:channel_id, the gateway seeds a resumable session:

Precondition	What the gateway does
`continuable is True` (default)	Mirrors `text` into the destination bot’s session under the delivery chat id. The user’s next message in this chat resumes the conversation.
`continuable is False`	Skips seeding entirely. Reply lands as a brand-new, contextless turn.
Delivery failed (any path)	Does not seed. Nothing was delivered, so nothing is claimed to have been.
Seeding raises (session missing, adapter oddity)	Logs a single `debug` line and returns. The delivery has already succeeded and remains committed — a seeding failure never breaks it.
Intentional-silence run (`NO_REPLY` / `[SILENT]` / `SILENT`)	Delivery is skipped — no delivery, no seed. See Intentional Silence.

The continuable field is a declarable contract. Core (praisonaiagents/scheduler/models.py) owns the field and its round-trip; the actual seeding runs in the praisonai-bot gateway. Deployments running the scheduler without the bot wrapper (direct scheduler → agent, no gateway) still round-trip the field and honour the opt-out, but there is no session to seed.

Configuration options

Option	Where	Type	Default	Description
`continuable`	`DeliveryTarget(continuable=…)`	`bool`	`True`	When `True`, seed the destination bot’s session with the delivered brief so a reply resumes the job’s conversation. Set `False` for pure fire-and-forget notifications.
`continuable`	`schedule_add(…, continuable=…)`	`bool`	`True`	Threaded through to the constructed `DeliveryTarget`.
`--continuable / --no-continuable`	`praisonai schedule add`	flag	`--continuable`	Applied only when a delivery target is configured; a no-op on jobs with no delivery.

Serialisation. DeliveryTarget.to_dict() persists continuable only when it is False — the default is implied by absence, so existing on-disk schedule stores are byte-for-byte unchanged. from_dict() treats a missing field as True, so restored legacy jobs immediately gain the new behaviour on next fire.

When to opt out

Pure status alerts

Backup finished, deploy succeeded, monitoring “ok” heartbeat. There is no conversation to have — the reply, if any, is an unrelated command. Use --no-continuable so the chat context stays fresh.

Fan-out to shared channels (deliver="all")

A broadcast to every home channel implies the recipients aren’t a single continuing conversation. Seeding runs once per destination channel:channel_id, so a shared/group chat resumes the last fire’s context, not per-participant. If replies in the shared chat are noise, prefer --no-continuable.

Sub-minute ticks

A tight loop that seeds on every fire would overwrite the session before the user can read it. Prefer --no-continuable (or a coarser schedule) for high-frequency jobs.

Recurring briefs and digests (leave it on)

Recurring briefs, digests, standing reports, sensor summaries — the reader almost always wants to reply to the thing they just read. Leave continuable on.

How It Works

The scheduler runs the agent, then hands the result to SchedulerDelivery, which resolves the token and sends through the shared DeliveryRouter. SchedulerDelivery is built once per scheduler and reused across runs, so the router’s idempotency cache and rate limiters persist between ticks. After a successful delivery, a gateway-hosted job also seeds a resumable session so a reply resumes the conversation — see Continuable Delivery.

Intentional Silence

A scheduled run whose entire output is exactly NO_REPLY, [SILENT], or SILENT skips delivery — nothing is pushed to the chat target. The run is still recorded as succeeded in scheduler history and metrics.

from praisonaiagents import Agent
from praisonai.scheduler import AgentScheduler

agent = Agent(
    name="Watchdog",
    instructions=(
        "Every hour, check the log file for new ERROR lines. "
        "If there are none, reply with exactly: NO_REPLY. "
        "Otherwise summarise the errors."
    ),
)
AgentScheduler(agent, task="Hourly check", deliver="telegram:123456").start("hourly")

The noisy NO_REPLY control token is never posted to the channel — the tick just doesn’t produce any message.

Agent output	Delivery
`NO_REPLY` (exact, case-insensitive, whitespace-trimmed)	Suppressed
`[SILENT]` / `SILENT`	Suppressed
`I think NO_REPLY is a good idea` (prose)	Delivered normally
Any other text	Delivered normally

The marker check calls is_intentional_silence_response from praisonaiagents.bots.silence — the same primitive the chat-bot path uses. All three unattended paths honour it via the shared _BaseAgentScheduler._should_suppress_delivery helper: AgentScheduler._deliver_result (sync lightweight), AsyncAgentScheduler._deliver_result (async lightweight, wired in PraisonAI #3420), and the full-gateway ScheduledAgentExecutor.

Path	Silence marker suppressed
`AgentScheduler` (sync lightweight)	✅ Yes
`AsyncAgentScheduler` (async lightweight)	✅ Yes (fixed in #3420)
`ScheduledAgentExecutor` (full gateway)	✅ Yes

Unlike the chat-bot path — where silence is opt-in via allow_silence: true — the scheduled delivery path honours silence markers unconditionally. An unattended monitor should never post the raw control token to a channel, so there is no allow_silence toggle for the scheduler.

Reliability Guarantees

Delivery reuses the existing DeliveryRouter, so scheduled sends inherit the gateway’s guarantees.

Guarantee	What it means
Rate limiting	Inherits the router’s per-platform token-bucket limits
Idempotency dedup — lightweight `AgentScheduler`	Router LRU (in-process). A re-fired job delivering the same result to the same target is deduplicated within one process.
Idempotency dedup — gateway-hosted scheduled/proactive delivery	Durable — enqueued via SQLite `OutboundQueue` at `~/.praisonai/state/gateway_outbox.sqlite`. Survives a crash-and-restart: a re-fired job is a no-op INSERT that resolves to the already-`sent` row. Falls back to the router LRU only if the durable store cannot be built.
Dead-target self-heal	The router retries and skips/marks dead targets
Graceful degradation	When `praisonai-bot` is not installed, a single warning is logged and delivery no-ops — the scheduled run itself never fails
Intentional silence	An exact `NO_REPLY` / `[SILENT]` / `SILENT` output suppresses delivery; the run is still recorded as `succeeded`
Continuable delivery	On successful delivery of a `continuable` target, the gateway seeds a resumable session keyed to the reply address. A seed failure logs and never breaks the delivery — the brief still lands.

On the gateway-hosted scheduled path, delivery is enqueued into a durable SQLite outbox at ~/.praisonai/state/gateway_outbox.sqlite before it reaches the router. Its UNIQUE idempotency key survives a process restart, so the exact crash window a scheduler must survive (fire → deliver → crash → restart → re-fire) is deduplicated without a double-post. A pre-crash send that never landed stays retryable and is delivered at-least-once on the next tick. If the outbox cannot be built (missing dependency or permission error) the path falls back to the router’s in-process LRU exactly as before.

Common Patterns

Deliver from a blueprint

from praisonai.scheduler import AgentScheduler

scheduler = AgentScheduler.from_blueprint(
    "morning-brief",
    slots={"hour": 8, "weekdays": "mon-fri"},
    deliver="telegram",
)
scheduler.start(scheduler._yaml_schedule_config["interval"])

deliver= on from_blueprint overrides the blueprint’s default delivery target.

Deliver to a thread

from praisonaiagents import Agent
from praisonai.scheduler import AgentScheduler

agent = Agent(name="Standup", instructions="Post the daily standup summary")
AgentScheduler(agent, task="Standup", deliver="discord:555:thread-42").start("daily")

Attachments produced by the job (media returned by the agent) now travel into the same thread — parity with text delivery is preserved on Slack, Telegram, and Discord. See Outbound Media Delivery for the thread grammar.

Fire-and-forget notice

praisonai schedule add "backup-notice" -s daily \
  -m "post the backup-complete notice" \
  --deliver slack:C0123456 \
  --no-continuable

Use --no-continuable when a reply should not resume the job — the reply starts a fresh session, matching pre-#3449 behaviour.

Best Practices

Use an explicit channel ID for scheduled jobs

telegram:123456 targets a fixed chat and works without any request context.origin now works on the lightweight scheduler path when the job has a persisted origin (ScheduleJob.origin, set automatically when the job is created from a bot/webhook request) — it resolves to the same channel/thread the request came in on, no gateway required. all still needs the full gateway. For jobs created outside a bot request (no persisted origin), prefer an explicit platform:channel_id token.

Install the bot extra to enable delivery

Delivery needs the praisonai-bot package. Without it, the scheduled run still executes — only the push is skipped, with one warning. Install the bot extra to turn delivery on.

Reuse one scheduler instance per job

The router’s idempotency cache and rate limiters live on the scheduler’s delivery helper. Keep a single scheduler running so repeated identical results to the same target are deduplicated instead of re-sent.

Pick the surface that matches how you deploy

Use Python inside an app, YAML for a config-file deploy, and the CLI for one-off terminal jobs — all three accept the same deliver token grammar.

Async Agent Scheduler

Run agents on a recurring schedule with async execution

Pre-Run Gate

Skip ticks when a cheap check says nothing to do

Schedule CLI

The --deliver / -d flag and other schedule commands

Gateway Inbound Hooks

Shares the same delivery target format

​Quick Start

​Three Ways to Set the Target

​Tools in scheduled YAML

​Which surface fits which scenario?

​Delivery Target Tokens

​Thread semantics per platform

​Deliver back to the origin channel

​Continuable Delivery

​Quick start — nothing to do

​Opt out for fire-and-forget alerts

​The seed contract

​Configuration options

​When to opt out

​How It Works

​Intentional Silence

​Reliability Guarantees

​Common Patterns

​Deliver from a blueprint

​Deliver to a thread

​Fire-and-forget notice

​Best Practices

​Related

Async Agent Scheduler

Pre-Run Gate

Schedule CLI

Gateway Inbound Hooks

Quick Start

Three Ways to Set the Target

Tools in scheduled YAML

Which surface fits which scenario?

Delivery Target Tokens

Thread semantics per platform

Deliver back to the origin channel

Continuable Delivery

Quick start — nothing to do

Opt out for fire-and-forget alerts

The seed contract

Configuration options

When to opt out

How It Works

Intentional Silence

Reliability Guarantees

Common Patterns

Deliver from a blueprint

Deliver to a thread

Fire-and-forget notice

Best Practices

Related