Scheduling Agents

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

Cron schedules

There are two ways a cron schedule gets attached to an agent:

1. Declared on a competency. A competency's manifest can carry a default schedule (and schedule_action — the prompt sent when it fires). When the competency is realised into an agent (at agent install/hydrate — see Using competencies), the platform registers the cron job automatically:

---
description: "..."
skills: [claims-data-extraction]
schedule: "0 */6 * * *"
schedule_action: "Check for new loss reports and process any unhandled intake items."
---

2. Created directly against a running agent via the CLI or API — independent of any competency:

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

# Optionally name it
hoziron-cli cron create claims-agent "0 9 * * MON-FRI" "Generate daily claims summary" --name daily-summary

agent, spec (a standard 5-field cron expression), and prompt are all positional arguments — there are no --agent/--schedule/--prompt flags.

Via the API:

curl -X POST http://localhost:4200/agents/{id}/schedules \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hzk_..." \
  -d '{"expression": "0 9 * * MON-FRI", "prompt": "Generate daily claims summary"}'

Managing schedules

# List active schedules (optionally filter by agent)
hoziron-cli cron list --agent claims-agent

# Disable a schedule without deleting it
hoziron-cli cron disable <schedule-id>

# Re-enable it
hoziron-cli cron enable <schedule-id>

# Delete permanently
hoziron-cli cron delete <schedule-id>

enable/disable are the CLI verbs; under the hood they call POST /schedules/{id}/resume and POST /schedules/{id}/pause respectively.

Best practices

  • Use cron for periodic reports and batch processing — it's the fully-supported path
  • Use channel/API triggers for interactive, human-initiated work
  • Consider agent lifecycle overhead — suspend agents that only need to run on a schedule rather than keeping them Running continuously

Next steps

Related: