Cron Scheduling & Automation
Relevant source files
The following files were used as context for generating this wiki page:
Cron Scheduling & Automation in Hermes Agent enables the autonomous execution of recurring tasks and workflows. The system allows the agent to register, manage, and execute jobs based on specific time intervals or triggers, ensuring persistent background operations without constant user intervention.
This module provides the structural foundation for "Daily Briefing Bots," scheduled data extraction, and periodic maintenance tasks. It integrates with the broader skill system, allowing agents to invoke specific capabilities through the cronjob tool.
Sources: cron/AGENTS.md , agent/learn_prompt.py:27-30 , website/scripts/generate-llms-txt.py:94-96
Architecture and Components
The Cron system follows a standard scheduler-job pattern where a central manager coordinates the execution of discrete work units. The architecture ensures that scheduled tasks are decoupled from the main agent loop while remaining capable of utilizing the agent's tools.
Core Components
| Component | Responsibility |
|---|---|
| Scheduler | Manages the registry of jobs and triggers their execution at the correct intervals. |
| Job Registry | Stores persistent information about active and pending cron tasks. |
| Job Executor | Handles the actual invocation of a job, providing it with the necessary context and tools. |
| Cron Tool | The user/agent-facing interface used to create and modify schedules. |
Sources: cron/scheduler.py, cron/jobs.py, agent/learn_prompt.py:94-101
Data Flow for Task Execution
The following diagram illustrates the flow from job registration to automated execution.
The Cron Scheduler acts as the heartbeat of the automation system, periodically checking the registry for jobs whose execution criteria have been met.
Sources: cron/scheduler.py, cron/jobs.py
Job Management
Jobs are the primary unit of automation. Every job must be defined with a target action and a scheduling expression.
Job Definitions
A job in the Hermes Agent context typically points to a specific skill or a script. When an agent creates a new automation, it must specify:
- Target: The skill or command to execute.
- Schedule: A cron-style string (e.g.,
0 9 * * *for daily at 9 AM). - Context: Any environment variables or arguments required by the task.
Sources: cron/jobs.py, agent/learn_prompt.py:27-30
The cronjob Tool
Agents interact with the scheduling system exclusively through the cronjob tool. This tool abstracts the underlying implementation of the scheduler, allowing the agent to frame its requests in natural language or structured tool calls.
Integration with Skills
Scheduled tasks often leverage the Hermes Skill system. A recurring job might be configured to run a "Daily Research" skill or an "Infographic Generator" task periodically.
Automation Constraints
When authoring skills intended for automation, developers must follow strict formatting and predictability rules:
- Framing: Invocation must be framed through the
terminalor appropriate Hermes tool within the cron definition. - Completion Criteria: Every scheduled step must have a checkable completion criterion to allow the scheduler to log success or failure.
- Environment Stability: Cron jobs must use absolute paths or repo-relative paths to avoid execution failures in different working directories.
Sources: skills/software-development/hermes-agent-skill-authoring/SKILL.md:126-133, agent/learn_prompt.py:94-101
Execution Environment
Automated jobs are executed within the same environment as the agent, meaning they have access to:
- Configured API keys in the
.envfile. - Platform-specific tools (gated by
platforms:metadata). - Local file system access via
read_fileandwrite_file.
Sources: skills/software-development/hermes-agent-skill-authoring/SKILL.md:104-111
Monitoring and Logs
To maintain reliability, the system tracks the execution state of every scheduled task.
Status Tracking
| State | Description |
|---|---|
| Pending | Job is registered and waiting for its scheduled time. |
| Running | Job is currently being executed by the executor. |
| Success | Job completed without errors and met completion criteria. |
| Failed | Job encountered an error or timed out during execution. |
Sources: cron/scheduler.py, cron/AGENTS.md
Failure Handling
If a scheduled job fails, the scheduler logs the stack trace and output. Depending on the configuration, the agent may be notified of the failure in the next active session, or a retry mechanism may be triggered based on specific error codes.
Sources: cron/scheduler.py, cron/AGENTS.md
Conclusion
The Cron Scheduling & Automation system transforms the Hermes Agent from a reactive tool into a proactive assistant. By providing a robust framework for recurring job registration and execution, it enables complex workflows such as automated documentation generation, periodic research, and system maintenance. The tight integration with the cronjob tool and the existing skill system ensures that automation remains consistent with the agent's standard operational principles.