Task Configuration Objects

Group a Task's output, execution, routing and context settings into four small config objects

Four small config objects keep a Task tidy. Each one groups a few settings you could otherwise pass as separate arguments.

python
from praisonaiagents import Agent, Task
from praisonaiagents.workflows import TaskOutputConfig

analyst = Agent(name="Analyst", instructions="Summarise reports clearly.")

task = Task(
    description="Summarise the quarterly report",
    agent=analyst,
    output=TaskOutputConfig(file="summary.md", variable="summary"),
)
Diagram

📋 Task

📄 output
TaskOutputConfig

⚙️ execution
TaskExecutionConfig

🔀 routing
TaskRoutingConfig

🔗 context
TaskContextConfig

The flat arguments (output_file=, max_retries=, …) keep working. Use whichever reads better.

Quick Start

  1. Plain arguments
    python
    from praisonaiagents import Agent, Task
    
    analyst = Agent(name="Analyst", instructions="Summarise reports clearly.")
    
    task = Task(
        description="Summarise the quarterly report",
        agent=analyst,
        output_file="summary.md",
    )
  2. One config object
    python
    from praisonaiagents import Agent, Task
    from praisonaiagents.workflows import TaskOutputConfig
    
    analyst = Agent(name="Analyst", instructions="Summarise reports clearly.")
    
    task = Task(
        description="Summarise the quarterly report",
        agent=analyst,
        output=TaskOutputConfig(file="summary.md"),
    )
  3. All four
    python
    from praisonaiagents import Agent, Task
    from praisonaiagents.workflows import (
        TaskOutputConfig,
        TaskExecutionConfig,
        TaskRoutingConfig,
        TaskContextConfig,
    )
    
    analyst = Agent(name="Analyst", instructions="Summarise reports clearly.")
    
    task = Task(
        name="summarise",
        description="Summarise the quarterly report",
        agent=analyst,
        output=TaskOutputConfig(file="summary.md", variable="summary"),
        execution=TaskExecutionConfig(max_retries=2, on_error="stop"),
        routing=TaskRoutingConfig(next_steps=["review"]),
        context=TaskContextConfig(from_steps=["ingest"], retain_full=False),
    )

Configuration Options

All four live in praisonaiagents.workflows.

TaskOutputConfig → output=

OptionTypeDefaultDescription
fileOptional[str]NoneSave the result to this file
json_modelOptional[Any]NonePydantic model for JSON output
pydantic_modelOptional[Any]NonePydantic model for a typed result
variableOptional[str]NoneStore the result as a workflow variable

TaskExecutionConfig → execution=

OptionTypeDefaultDescription
async_execboolFalseRun the task asynchronously
quality_checkboolTrueCheck the output quality
rerunboolTrueAllow the task to run again
max_retriesint3Retry attempts on failure
on_errorstr"stop""stop", "continue" or "retry"

TaskRoutingConfig → routing=

OptionTypeDefaultDescription
next_stepsOptional[List[str]]NoneSteps to run next
branchesOptional[Dict[str, List[str]]]NoneMap a decision to the steps it leads to

TaskContextConfig → context=

OptionTypeDefaultDescription
from_stepsOptional[List[str]]NoneSteps whose output this task receives
retain_fullboolTruePass all prior task outputs, not just the previous one

Runtime state — do not set

status, result, id, retry_count and loop_state are filled in by the framework while the task runs. They are accepted for backward compatibility; leave them at their defaults.


Which one do I need?

Diagram

Yes

No

Yes

No

Yes

No

Yes

No

Care where the
output goes?

TaskOutputConfig

Retries, async
or error policy?

TaskExecutionConfig

Branch to
other steps?

TaskRoutingConfig

Need upstream
step output?

TaskContextConfig

✅ Plain Task is enough


Best Practices

Start with plain arguments

A Task with just description and agent covers most cases. Reach for a config object only when you set two or more related options.

Don't mix flat and grouped for the same setting

Setting both output_file= and output=TaskOutputConfig(file=...) makes it unclear which wins. Pick one style per setting.

Name tasks you route to

next_steps, branches and from_steps refer to tasks by name, so give those tasks a name=.


Related