Building Scheduled Workflows in Astreus

Astreus enables developers to build time-based automated workflows with simple schedule strings and dependency management. This guide shows you how to create workflows that run automatically on your schedule.

Get started by cloning the example repository or installing the package:

BashCopy
git clone https://github.com/astreus-ai/scheduled-workflows
cd scheduled-workflows
npm install

Or install directly:

BashCopy
npm install @astreus-ai/astreus

Create a .env file with your configuration:

OPENAI_API_KEY=sk-your-openai-api-key-here
DB_URL=sqlite://./astreus.db
NODE_ENV=development

The database persists workflow state, ensuring tasks continue after restarts.

Every workflow starts with an agent that handles the AI operations:

TypeScriptCopy
const agent = await Agent.create({
  name: 'ContentAgent',
  model: 'gpt-4o',
  systemPrompt: 'You are a content creation specialist.'
});

The agent encapsulates the AI model and behavior. You can create multiple agents with different capabilities for different tasks.

Workflows are represented as graphs with nodes and dependencies:

TypeScriptCopy
const graph = new Graph({
  name: 'Quick Test Pipeline',
  description: 'Test automated workflow with seconds interval',
  maxConcurrency: 2
}, agent);

The graph manages execution order, concurrency limits, and task dependencies. Setting maxConcurrency prevents overwhelming your API limits or system resources.

Add task nodes with schedules and dependencies:

TypeScriptCopy
const researchNode = graph.addTaskNode({
  name: 'Content Research',
  prompt: 'Research trending topics in AI and technology...',
  schedule: 'after:5s'
});

const creationNode = graph.addTaskNode({
  name: 'Content Creation',
  prompt: 'Create a blog post summary...',
  schedule: 'after:10s',
  dependsOn: ['Content Research']
});
more

The dependsOn array ensures tasks execute in the correct order. If a dependency fails, dependent tasks won't run.

Astreus uses human-readable schedule strings:

• daily@06:00 - Execute daily at 6 AM
• weekly@monday@09:00 - Weekly on Monday at 9 AM
• monthly@15@10:00 - 15th of each month at 10 AM
• after:5s - Delay 5 seconds (testing)
• after:2h - Delay 2 hours
• every:30m - Repeat every 30 minutes

Use short intervals like after:5s during development for rapid testing, then switch to production schedules.

Execute your workflow with a simple call:

TypeScriptCopy
const result = await graph.run();

The run method returns detailed execution results:

TypeScriptCopy
{
  success: true,
  completedNodes: 2,
  failedNodes: 0,
  duration: 15432,
  results: {
    'node-id-1': { output: '...' },
    'node-id-2': { output: '...' }
  },
  errors: []
}
more

You get full visibility into which tasks succeeded, how long they took, and what outputs they produced.

Here's a practical example that chains multiple tasks:

TypeScriptCopy
const agent = await Agent.create({
  name: 'ContentAgent',
  model: 'gpt-4o',
  systemPrompt: 'You are a content creation specialist.'
});

const graph = new Graph({
  name: 'Daily Content Pipeline',
  description: 'Automated content research and creation',
  maxConcurrency: 2
}, agent);

const researchNode = graph.addTaskNode({
  name: 'Topic Research',
  prompt: 'Research trending topics in technology',
  schedule: 'daily@07:00'
});

const draftNode = graph.addTaskNode({
  name: 'Draft Creation',
  prompt: 'Create a blog post draft from research',
  schedule: 'daily@08:00',
  dependsOn: ['Topic Research']
});

const optimizeNode = graph.addTaskNode({
  name: 'SEO Optimization',
  prompt: 'Optimize draft for SEO',
  schedule: 'daily@09:00',
  dependsOn: ['Draft Creation']
});

const result = await graph.run();
more

This pipeline researches topics at 7 AM, creates drafts at 8 AM, and optimizes them at 9 AM, all automatically.

Don't wait hours between test runs. Use short schedules during development:

TypeScriptCopy
const testGraph = new Graph({
  name: 'Quick Test Pipeline',
  description: 'Test automated workflow with seconds interval',
  maxConcurrency: 2
}, agent);

const testNode = graph.addTaskNode({
  name: 'Quick Test',
  prompt: 'Test task execution',
  schedule: 'after:5s'
});

const result = await testGraph.run();
more

Using after:5s lets you iterate quickly and catch issues early.

Process workflow results to integrate with other systems:

TypeScriptCopy
const result = await graph.run();

if (result.success) {
  console.log(`Completed ${result.completedNodes} tasks in ${result.duration}ms`);
  
  // Access individual task outputs
  for (const [nodeId, output] of Object.entries(result.results)) {
    console.log(`${nodeId}:`, output);
  }
} else {
  console.error(`Failed tasks: ${result.failedNodes}`);
  result.errors.forEach(error => {
    console.error(`Error in ${error.nodeId}:`, error.message);
  });
}
more

The results object gives you everything you need to monitor, debug, and respond to workflow outcomes.

Deploy your workflow as a long-running process:

TypeScriptCopy
import { Agent, Graph } from '@astreus-ai/astreus';

async function main() {
  const agent = await Agent.create({
    name: 'ProductionAgent',
    model: 'gpt-4o',
    systemPrompt: 'You are a production workflow agent.'
  });

  const graph = new Graph({
    name: 'Production Pipeline',
    description: 'Automated daily workflows',
    maxConcurrency: 3
  }, agent);

  // Add your scheduled tasks
  graph.addTaskNode({
    name: 'Daily Report',
    prompt: 'Generate daily summary report',
    schedule: 'daily@08:00'
  });

  // Run and keep process alive
  await graph.run();
  
  process.on('SIGTERM', async () => {
    console.log('Shutting down gracefully...');
    process.exit(0);
  });
}

main().catch(console.error);
more

This setup ensures your workflows continue running and handle shutdown signals gracefully.

Follow these guidelines for reliable workflows:

• Start with after:5s schedules during development for rapid testing
• Use descriptive names for nodes to make debugging easier
• Set appropriate maxConcurrency limits to avoid overwhelming APIs
• Always check result.success before processing outputs
• Use dependsOn to enforce correct task ordering
• Store sensitive configuration in environment variables
• Monitor result.duration to optimize performance

Explore the full implementation at https://github.com/astreus-ai/scheduled-workflows. The repository includes working examples, additional patterns, and production-ready configurations.

Now you can build automated workflows that run on your schedule. Try creating a daily report generator, weekly content summarizer, or hourly data processor. The Astreus API handles the complexity of timing and execution while you focus on the tasks themselves.

This experiment is written for Astreus v0.5.37. Please ensure you are using a compatible version.