Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.praison.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Background Tasks (TypeScript)

Run recipes and agents asynchronously in the background with progress tracking, cancellation support, and result retrieval.

​
Installation

npm install praisonai-ts

​
Basic Usage

​
Running a Recipe in Background

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

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

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: 
runtime:
  background:
    enabled: true
    max_concurrent: 3
    cleanup_delay_sec: 3600

​
Error Handling

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

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

​
See Also