Setting Up Recurring Background Jobs with Cron in Agent-Native

You configure recurring background jobs in Agent-Native by defining cron schedules in wrangler.toml and implementing job logic in server/plugins/ directories, with execution gated by the RUN_BACKGROUND_JOBS environment variable.

Agent-Native (BuilderIO/agent-native) leverages Wrangler's built-in cron triggers to handle automated tasks like mail processing and automation workflows. This architecture allows agents to run background logic on a schedule without external scheduling services. Understanding how to implement and control these jobs is essential for customizing agent behavior and managing resource usage in development environments.

How Cron Jobs Work in Agent-Native

Cron jobs in Agent-Native use Cloudflare Workers' cron trigger system, configured through the wrangler.toml file in each template directory. The configuration defines when the job runs, while the implementation resides in TypeScript files under server/plugins/.

In templates/mail/wrangler.toml, the cron schedule is declared in the [triggers] section:

[triggers]
crons = ["*/5 * * * *"]

This configuration tells Wrangler to trigger the worker every five minutes. When the cron fires, the worker executes the scheduled job logic defined in the corresponding plugin file.

Enabling Cron Jobs in Development

By default, cron jobs are disabled in development to prevent unnecessary resource consumption and accidental execution during local testing. You must explicitly enable them using the RUN_BACKGROUND_JOBS environment variable.

Set the variable before starting your development server:

export RUN_BACKGROUND_JOBS=1
wrangler dev --local

Alternatively, add it to your .env file in the template directory:

RUN_BACKGROUND_JOBS=1

In production environments, background jobs run automatically without this flag. The implementation in templates/mail/server/plugins/mail-jobs.ts checks this environment variable to gate execution:

// Only run background jobs if explicitly enabled in dev
if (process.env.RUN_BACKGROUND_JOBS !== '1' && process.env.NODE_ENV !== 'production') {
  console.log('[mail-jobs] Background jobs disabled. Set RUN_BACKGROUND_JOBS=1 to enable.');
  return;
}

The Mail Jobs Reference Implementation

The mail template provides a complete reference implementation for recurring background jobs in templates/mail/server/plugins/mail-jobs.ts. This file demonstrates the standard pattern for Agent-Native cron jobs.

The plugin initializes during worker startup and uses a setInterval-style execution pattern managed by Wrangler's cron system:

export default {
  async cron(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {
    console.log('[mail-jobs] Starting mail processing job');
    
    // Database interaction
    const db = getDatabase(env);
    
    // Process pending automations
    await processMailAutomations(db, env);
    
    console.log('[mail-jobs] Completed processing');
  }
};

The mail job interacts with the database via templates/mail/server/plugins/db.ts and triggers automation logic defined in templates/mail/server/lib/automation-engine.ts. It serves as the canonical example for implementing time-based background processing.

Creating Custom Cron Jobs

To implement a new recurring background job for your agent, follow this three-step process:

1. Configure the Cron Schedule

Add a new entry to the [triggers] section in your template's wrangler.toml:

[triggers]
crons = ["*/5 * * * *", "0 */6 * * *"]

The second entry runs every six hours. Use standard cron syntax to define your schedule.

2. Create the Plugin File

Create a new file under templates/<your-agent>/server/plugins/custom-jobs.ts:

import { getDatabase } from './db';

export default {
  async cron(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {
    // Dev gate check
    if (process.env.RUN_BACKGROUND_JOBS !== '1' && process.env.NODE_ENV !== 'production') {
      console.log('[custom-jobs] Skipping execution in development');
      return;
    }

    console.log('[custom-jobs] Running custom background task');
    
    // Your background logic here
    await performCustomTask(env);
  }
};

3. Expose Actions for Cron Invocation

If your cron needs to trigger agent actions, ensure those actions are exposed to non-interactive callers. In templates/mail/.agents/skills/actions/SKILL.md, actions triggered by cron should set agentTool: false to indicate they can be called programmatically:

export const customAction = {
  agentTool: false, // Accessible by cron, not just LLM
  async handler({ db, env }) {
    // Action logic
  }
};

Reference the templates/mail/actions/trigger-automations.ts file for an example of an action designed to be invoked by cron jobs.

Testing and Debugging Cron Jobs

Test cron jobs locally using Wrangler's development environment:

export RUN_BACKGROUND_JOBS=1
wrangler dev --local

Monitor the console output for [mail-jobs] or your custom job prefix to verify execution. The cron simulation in local development respects your wrangler.toml schedule, though you can manually trigger execution for testing:

# Trigger a specific cron handler manually via debug endpoint

curl http://localhost:8787/debug/trigger-cron

Check the AGENTS.md file in the repository root for template-specific background job documentation and troubleshooting steps.

Summary

• Configuration: Define schedules in wrangler.toml using the [triggers] section with standard cron syntax.
• Implementation: Create plugin files in server/plugins/ that export a cron handler function.
• Development Gate: Set RUN_BACKGROUND_JOBS=1 to enable execution in local development; production runs automatically.
• Reference: Study templates/mail/server/plugins/mail-jobs.ts for the canonical implementation pattern.
• Action Exposure: Set agentTool: false for actions that cron jobs should invoke directly.

Frequently Asked Questions

What is the default cron schedule for the mail agent?

The mail agent in templates/mail/wrangler.toml runs every five minutes (*/5 * * * *) by default. You can modify this schedule in the [triggers] section to run more or less frequently depending on your processing requirements.

Why are my cron jobs not running in local development?

Cron jobs are disabled in development by default to conserve resources. You must set the environment variable RUN_BACKGROUND_JOBS=1 before starting wrangler dev. Without this flag, the job logic exits early as implemented in the dev gate check within mail-jobs.ts.

Can I create multiple cron schedules for a single agent?

Yes. Add multiple cron expressions to the crons array in wrangler.toml. For example, crons = ["*/5 * * * *", "0 9 * * *"] creates two triggers—one every five minutes and one daily at 9 AM. Handle different schedules within your plugin by checking event.cron to determine which schedule triggered the execution.

How do cron jobs access the database?

Cron jobs access the database using the same pattern as HTTP handlers. Import your database utility from server/plugins/db.ts and call it with the env parameter passed to the cron handler. The templates/mail/server/plugins/mail-jobs.ts file demonstrates this pattern by initializing the database connection at the start of each cron execution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}