Scheduling Agents

What you'll accomplish: Set up cron-based schedules and event triggers for agent execution.

Cron schedules

Competencies can declare a schedule for periodic execution:

# In COMPETENCY.toml
schedule = "0 */6 * * *"   # Every 6 hours

Or configure via the CLI:

hoziron cron create --agent claims-agent --schedule "0 9 * * MON-FRI" --prompt "Generate daily claims summary"

Managing schedules

# List active schedules
hoziron cron list

# Pause a schedule
hoziron cron pause <schedule-id>

# Resume
hoziron cron resume <schedule-id>

# Delete
hoziron cron delete <schedule-id>

Event triggers

Agents can be triggered by events beyond cron:

  • Lifecycle triggers — agent starts when a lifecycle event occurs
  • Webhook triggers — external systems trigger agent execution via webhook
  • Channel triggers — messages in connected channels (Slack, Teams)

Configure triggers at agent creation:

{
  "name": "alert-handler",
  "triggers": [
    {"webhook": {"path": "/hooks/alerts"}},
    {"lifecycle": {}}
  ]
}

Best practices

  • Use cron for periodic reports and batch processing
  • Use webhooks for event-driven workflows (new ticket, new claim)
  • Consider agent lifecycle overhead — schedule start/stop rather than keeping agents perpetually running for infrequent tasks

Next steps

Related: