Task Handlers

A task handler runs your own function in place of the model — for math, lookups, or calling existing code.

Quick Start

Run a function instead of the model

import { Agent, Team, Task } from 'praisonai';

const team = new Team({
  agents: [new Agent({ instructions: 'help' })],
  tasks: [new Task({
    name: 'compute',
    description: 'add the numbers',
    handler: () => 'computed without an LLM'
  })]
});

const results = await team.start();
console.log(results[0]); // "computed without an LLM" — the model was never called

Read the workflow context

new Task({
  name: 'compute',
  description: 'add the numbers',
  handler: ({ input, previousResult, currentStep, variables, task }) => {
    return `step ${currentStep} saw ${previousResult ?? 'nothing yet'}`;
  }
});

What the Handler Receives

The handler is called with one object.

Field	Description
`input`	The prompt this task would have sent the model.
`previousResult`	The output of the task before this one.
`currentStep`	The current task’s name.
`variables`	Run variables, including any a handler published earlier.
`task`	The `Task` instance itself.

What the Handler Returns

Return a string, or an object for more control.

Return	Effect
`string`	Used as the task output. Publishes no variables.
`{ output }`	The task output.
`{ variables }`	Merged into run variables for later `{{placeholder}}` substitution.
`{ stopWorkflow: true }`	Ends the run after this task.
`{ success, error }`	Marks the task failed.

Publish variables for later prompts

Variables a handler publishes fill {{placeholder}} slots in later tasks.

const team = new Team({
  agents: [member],
  tasks: [
    new Task({
      name: 'gather',
      description: 'gather',
      handler: () => ({ output: 'raw data', variables: { topic: 'whales' } })
    }),
    new Task({ name: 'write', description: 'write about {{topic}}' })
  ]
});

await team.start();
// The second task's prompt becomes "write about whales"

A handler that returns a plain string publishes nothing — {{topic}} stays unfilled. Return { output, variables } to publish.

Stop the workflow

new Task({
  name: 'halt',
  description: 'halt',
  handler: () => ({ output: 'stopping', stopWorkflow: true })
});
// Any task after this one never starts.

A throwing handler fails only its task

new Task({
  name: 'boom',
  description: 'boom',
  handler: () => { throw new Error('handler exploded'); }
});
// This task is marked failed; unrelated tasks still run.

How It Works

Best Practices

Use handlers for deterministic work

Math, database lookups, and API calls belong in a handler, not a prompt.

Publish variables to steer later prompts

Return { output, variables } so downstream {{placeholder}} slots fill in.

Fail loudly, stop deliberately

Throw to fail one task; return { stopWorkflow: true } to end the whole run.

Tasks

All task options

Routing

Branch between tasks

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

What the Handler Receives

What the Handler Returns

Publish variables for later prompts

Stop the workflow

A throwing handler fails only its task

How It Works

Best Practices

Tasks

Routing

​Quick Start

​What the Handler Receives

​What the Handler Returns

​Publish variables for later prompts

​Stop the workflow

​A throwing handler fails only its task

​How It Works

​Best Practices

​Related

Tasks

Routing

Quick Start

What the Handler Receives

What the Handler Returns

Publish variables for later prompts

Stop the workflow

A throwing handler fails only its task

How It Works

Best Practices

Related