Skip to content

proactive_agent

diapason.agents.proactive_agent

Proactive Agent — runs on a cron (default 5am local) to autonomously handle routine tasks based on learned user behavior.

Lifecycle per run

  1. Load USER.md + MEMORY.md for behavioral context.
  2. Collect overnight data from connected sources via digest_collect.
  3. Use the LLM to classify each item and propose actions with a tier + permission key.
  4. For each proposed action:
  5. TRIVIAL tier → queue + immediately approve
  6. Known always_approve → queue + immediately approve
  7. Known always_deny → skip silently
  8. Everything else → queue as pending, notify user
  9. Execute all approved actions via execute_pending_actions.
  10. Send the user a concise summary: what was done + numbered list of what needs approval.

Approval reply format (user replies to the notification message): {action_id} yes approve one action {action_id} no deny one action always yes {action_id} approve + remember for this pattern always no {action_id} deny + remember for this pattern yes all / no all bulk decision

Wire up parse_approval_response from proactive_tools in your channel message handler to process replies without running the full agent.

Scheduling

The agent self-registers a 5am daily cron task when register_cron is called from your app startup:

from diapason.agents.proactive_agent import register_cron
register_cron(scheduler, notification_channel_id="your-channel-id")

ProactiveAgent

Bases: ToolUsingAgent

Autonomous agent that handles routine tasks based on learned user behavior.

register_cron(scheduler, *, notification_channel_id='', cron_expr='', hours_back=0, timezone='')

Register the proactive agent as a daily cron task.

All defaults are read from config.toml [proactive] when not explicitly passed. Call this once from app startup after the scheduler is started.

Parameters

scheduler: A TaskScheduler instance. notification_channel_id: Override the channel ID from config. If empty, uses notification_channel from [proactive] in config.toml. cron_expr: Override the cron schedule. Defaults to config value ("0 5 * * *"). hours_back: Override hours of data to scan. Defaults to config value (24). timezone: Override timezone string. Defaults to config value.