Praison AI

Background Tasks

Run recipes and agents as background tasks in TypeScript

Run recipes and agents asynchronously in the background with progress tracking and cancellation.

Diagram

User

Background Runner

Task

Result

Quick Start

  1. Simple Usage
    bash
    npm install praisonai-ts
    typescript
    import { recipe } from 'praisonai-ts';

const task = await recipe.runBackground('my-recipe', {
  input: { query: 'What is AI?' },
});
const result = await task.wait(600);
  2. With Configuration
    typescript
    const task = await recipe.runBackground('my-recipe', {
  input: { query: 'What is AI?' },
  timeoutSec: 300,
  sessionId: 'session_123',
});

Basic Usage

Running a Recipe in Background

typescript
import { recipe } from 'praisonai-ts';

// Submit recipe as background task
const task = await recipe.runBackground('my-recipe', {
  input: { query: 'What is AI?' },
  config: { maxTokens: 1000 },
  sessionId: 'session_123',
  timeoutSec: 300,
});

console.log(`Task ID: ${task.taskId}`);
console.log(`Session: ${task.sessionId}`);

// Check status
const status = await task.status();
console.log(`Status: ${status}`);

// Wait for completion
const result = await task.wait(600);
console.log(`Result: ${result}`);

// Cancel if needed
await task.cancel();

BackgroundTaskHandle Interface

typescript
interface BackgroundTaskHandle {
  taskId: string;
  recipeName: string;
  sessionId?: string;

  status(): Promise<TaskStatus>;
  wait(timeout?: number): Promise<any>;
  cancel(): Promise<boolean>;
}

type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';

Using with Agents

typescript
import { Agent, BackgroundRunner } from 'praisonai-ts';

// Create agent
const agent = new Agent({
  instructions: 'You are a helpful assistant',
  verbose: true,
});

// Create background runner
const runner = new BackgroundRunner({ maxConcurrentTasks: 5 });

// Submit task
const task = await runner.submit(
  () => agent.start('Analyze this data'),
  {
    name: 'analysis-task',
    timeout: 300,
  }
);

// Wait for result
const result = await runner.waitForTask(task.id);

Configuration

Safe Defaults

SettingDefaultDescription
timeoutSec300Maximum execution time (5 minutes)
maxConcurrent5Maximum concurrent tasks
cleanupDelaySec3600Time before completed tasks are cleaned up

Runtime Configuration

Configure in your recipe’s TEMPLATE.yaml:

yaml
runtime:
  background:
    enabled: true
    max_concurrent: 3
    cleanup_delay_sec: 3600

Error Handling

typescript
import { recipe, RecipeError } from 'praisonai-ts';

try {
  const task = await recipe.runBackground('my-recipe', { input: 'test' });
  const result = await task.wait(60);
} catch (error) {
  if (error instanceof RecipeError) {
    console.error(`Recipe error: ${error.message}`);
  } else if (error.name === 'TimeoutError') {
    console.error('Task timed out');
    await task.cancel();
  }
}

Best Practices

Always set timeouts
  • Prevent tasks from running indefinitely
Use session IDs
  • Track related tasks across executions
Handle cancellation
  • Clean up resources when tasks are cancelled
Monitor progress
  • Use status checks for long-running tasks
Limit concurrency
  • Don’t overwhelm system resources

Related

Background Tasks CLI

CLI commands

 Async Jobs

Server-based jobs

 Scheduler

Periodic scheduling