​
Overview

Jobs in Magma allow you to schedule recurring tasks for your agent to perform. Using the @job decorator, you can define tasks that run on a specified schedule using cron syntax.

If a job is not declared as static, it will be scheduled to run on the agent’s instance, for every session of the agent. Learn more about sessions

​
Basic Implementation

Here’s a simple example of implementing a job:

import { MagmaAgent } from "@pompeii-labs/magma";
import { job } from "@pompeii-labs/magma/decorators";

class MyAgent extends MagmaAgent {
    @job("0 0 * * *") // Runs daily at midnight
    async dailyBackup() {
        const result = await this.backupData();
        console.log(`Backup completed: ${result}`);
    }
}

​
Job Scheduling

Jobs use standard cron syntax for scheduling:

@job("* * * * *")      // Every minute
@job("0 * * * *")      // Every hour
@job("0 0 * * *")      // Every day at midnight
@job("0 0 * * 0")      // Every Sunday at midnight
@job("0 0 1 * *")      // First day of every month

You can learn more about cron syntax here, and you can use the Cron Editor to help you create the correct syntax.

​
Advanced Job Configuration

Jobs can accept configuration options:

@job("0 0 * * *", {
    timezone: "America/New_York",
})
async complexJob() {
    // Implementation here
}

​
Static Jobs

Some jobs don’t need to access the agent’s context, and don’t need to be run on every session of the agent. You can declare them as static methods:

@job("0 0 * * *")
static async dailyBackup() {
    const result = await this.backupData();
    console.log(`Backup completed: ${result}`);
}

This job will be handled without instantiating the agent.

​
Common Use Cases

​
Data Synchronization

class MyAgent extends MagmaAgent {
    @job("*/15 * * * *") // Every 15 minutes
    async syncData() {
        const updates = await this.fetchExternalData();
        await this.updateLocalDatabase(updates);
        console.log(`Synced ${updates.length} records`);
    }
}

​
Maintenance Tasks

class MyAgent extends MagmaAgent {
    @job("0 0 * * 0") // Weekly on Sunday
    async weeklyCleanup() {
        await this.cleanTempFiles();
        await this.optimizeDatabase();
        console.log("Weekly maintenance completed");
    }
}

​
Report Generation

class MyAgent extends MagmaAgent {
    @job("0 9 * * 1-5") // Weekdays at 9 AM
    async generateDailyReport() {
        const report = await this.compileMetrics();
        await this.emailReport(report);
        console.log("Daily report sent");
    }
}

​
Agent completions

class MyAgent extends MagmaAgent {
    @job("0 9 * * 1-5") // Weekdays at 9 AM
    async doAgentStuff() {
        const completion = await this.main();
        console.log(completion.content);
    }
}

Use caution when using the main method in a job. You should only use it if your agent will not be conducting conversations

​
Best Practices

  1. Error Handling

    @job("0 * * * *")
async hourlyTask() {
    try {
        const result = await this.processData();
        console.log(`Task completed: ${result}`);
    } catch (error) {
        await this.notifyAdmin(error);
        throw new Error(`Task failed: ${error.message}`);
    }
}

  2. Resource Management

    • Consider server load during job scheduling
    • Avoid overlapping job executions that modify the same resources
    • Implement proper cleanup in case of failures

  3. Monitoring

    • Log job execution results
    • Track execution time
    • Monitor success/failure rates

​
Limitations

  • Jobs must be async methods
  • Maximum execution time is 5 minutes
  • Timezone must be a valid IANA timezone string

For long-running tasks, consider breaking them into smaller sub-tasks or using a queue-based approach.

HooksSessions