Tasks

Define work for agents to complete

Tasks define specific work for agents to complete with clear objectives.

Quick Start

1. Run a task through a team

   import { Agent, Team } from 'praisonai';
   
   const team = new Team({
     agents: [new Agent({ instructions: 'You research and summarize topics' })],
     tasks: ['Research AI trends in 2024']
   });
   
   const results = await team.start();
   console.log(results[0]);
   
2. With a Task object

   import { Agent, Team } from 'praisonai';
   
   const analyst = new Agent({ instructions: 'You analyse data' });
   
   const team = new Team({
     agents: [analyst],
     tasks: [{
       name: 'analyse',
       description: 'Analyze sales data',
       expectedOutput: 'A summary with top 3 insights',
       agent: analyst
     }]
   });
   
   await team.start();
   

import { Task } from 'praisonai' resolves to the workflow-step class — its shape is { name, execute }, not { description, expectedOutput }. To give a Team a rich task with description, expectedOutput, agent, and the routing fields below, pass a plain object (or a task string), as shown above. Team reads those fields directly; you do not need to call new Task(...).

Only autonomy, web, reflection, and planning are still accepted for Python-SDK parity but not yet implemented in the TypeScript SDK. Passing one emits a [praisonai] … not yet honoured notice — see Parity Notices. Every other Task option below is fully live through team.start().

---

How a Task Runs

team.start() runs every task through the same pipeline, in this exact order.

Step	What happens
Rerun gate	A re-queued completed task is skipped unless rerun (or execution.rerun) is set.
Dependency check	If a dependsOn task failed, skipOnFailure marks this one degraded; otherwise it fails.
Start hooks	Team onTaskStart, then the task’s own hooks.onTaskStart.
Resolve agent	With no agent but an agentConfig, one is built at run time named <taskName>Agent.
handler	Runs instead of the model when provided.
Context	retainFullContext carries every earlier result; the default carries only the latest.
Memory + knowledge	Recalled and folded into the prompt.
Images	Per-task images attach as multimodal image_url parts.
Cache	A caching hit returns the stored answer and skips the retries.
Retries	retryDelay backs off min(delay * 2^attempt, 300) seconds.
Output	outputPydantic / outputConfig.pydanticModel parse the answer and strip ```json fences.
Complete	Result stored to memory, then team and task onTaskComplete hooks.

---

Task Options

Every option below changes what team.start() does.

Core

Option	Type	Default	Description
description	string	—	What the task should accomplish.
expectedOutput	string	"Complete the task successfully"	Desired format of the result.
agent	Agent	null	Agent assigned to the task.
agentConfig	object	null	Build an agent at run time when none is set.
dependsOn / context	Task[]	[]	Tasks whose results feed this one.
handler	function	null	Run a function instead of the model.
hooks	{ onTaskStart, onTaskComplete }	null	Per-task lifecycle callbacks.

// task objects inside team.tasks
// handler runs instead of the model
{
  name: 'compute',
  description: 'add the numbers',
  handler: () => 'computed without an LLM'
}

// agentConfig builds `researchAgent` at run time
{
  name: 'research',
  description: 'research whales',
  agentConfig: { llm: 'gpt-4o-mini', instructions: 'be brief' }
}

Context, memory & knowledge

Option	Type	Default	Description
retainFullContext	boolean	false	Carry every earlier result, not just the latest.
memory	store	null	Recall into the prompt and write the answer back.
failOnMemoryError	boolean	false	Re-throw memory failures instead of swallowing them.
config.memory_config	object	null	Auto-create a per-task memory store.
knowledge	string | string[] | base	null	Fold matching knowledge into the prompt.
images	string[]	[]	Attach pictures as multimodal parts.

// a task object inside team.tasks
{
  name: 'summarise',
  description: 'summarise whales',
  memory,                 // recalled into the prompt, answer written back
  retainFullContext: true,
  knowledge: 'penguins cannot fly'
}

Output

Option	Type	Default	Description
outputPydantic	schema	null	Parse the answer into a typed object.
outputConfig	{ pydanticModel }	null	Same parsing through its own field.

// a task object inside team.tasks
{
  name: 'shape',
  description: 'shape it',
  outputPydantic: { type: 'object', properties: { title: { type: 'string' } } }
}

Execution & retries

Option	Type	Default	Description
asyncExecution	boolean	false	Batch consecutive async tasks together.
caching	boolean	false	Serve a repeated prompt from cache.
rerun	boolean	false	Run again when the team reaches it a second time.
execution	{ rerun }	null	Alternate switch for rerun.
retryDelay	number	0	Seconds to back off between attempts (doubles each retry).
skipOnFailure	boolean	false	Run even if a dependency failed.

// task objects inside team.tasks
{ name: 'alpha', description: 'alpha', asyncExecution: true }
{ name: 'quote', description: 'quote the price', caching: true, rerun: true }

Routing & loops

Option	Type	Default	Description
isStart	boolean	false	Entry point of a workflow graph.
nextTasks	string[]	[]	Tasks to run after this one.
taskType	string	"task"	'decision' drives the routing table.
routing / condition	{ [decision]: string[] }	null	Route by the decision the model returned.
when	string	null	Condition gating thenTask / elseTask.
thenTask / elseTask	string	null	Branch targets.
loopOver	string	null	Variable name of an array to fan out over.
loopVar	string	"item"	Placeholder each loop item binds to.
inputFile	string	null	CSV file — one subtask per row.

Routing lives on Routing; loops live on Loops.

---

User Interaction Flow

---

API Reference

TaskConfig

Task configuration options

Task

Task class documentation

A few Python Task helper methods have no TypeScript counterpart yet. Configure tasks with the plain-object fields above and let team.start() drive them — see the parity baseline for the current method list.

---

Best Practices

Be specific in descriptions

“Write 500-word blog post about AI benefits” beats “Write about AI”.

Use handler for deterministic steps

A handler runs instead of the model — perfect for math, lookups, or calling your own code.

Chain tasks with dependsOn

Pass earlier tasks so their output feeds the next one.

Reach for caching on repeated prompts

caching: true skips the model entirely on a repeat.

---

Related

Handlers

Run a function instead of the model

Routing

Branch between tasks

Loops

Fan out over lists and CSVs

Teams

Multi-agent teams