Jobs

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

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}`);
    }
}

Resource Management
- Consider server load during job scheduling
- Avoid overlapping job executions that modify the same resources
- Implement proper cleanup in case of failures
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.

Getting Started

Magma Framework

Agent Templates

Frontend Integration

Overview

Basic Implementation

Job Scheduling

Advanced Job Configuration

Static Jobs

Common Use Cases

Data Synchronization

Maintenance Tasks

Report Generation

Agent completions

Best Practices

Limitations

​Overview

​Basic Implementation

​Job Scheduling

​Advanced Job Configuration

​Static Jobs

​Common Use Cases

​Data Synchronization

​Maintenance Tasks

​Report Generation

​Agent completions

​Best Practices

​Limitations

Overview

Basic Implementation

Job Scheduling

Advanced Job Configuration

Static Jobs

Common Use Cases

Data Synchronization

Maintenance Tasks

Report Generation

Agent completions

Best Practices

Limitations