Agent Run Outcomes

Run outcomes give every agent execution a typed status so your code can handle success, failure, timeout, cancellation, and invalid output exhaustively — no string matching.

AgentRunOutcome (this page) and RunOutcome (see Run Outcome) are two different types with two different jobs:

	`AgentRunOutcome`	`RunOutcome`
Import	`from praisonaiagents import AgentRunOutcome`	`from praisonaiagents import RunOutcome`
Module	`praisonaiagents.run_outcome`	`praisonaiagents.agent.run_outcome`
Field	`status`	`reason`
Values	`success \| failure \| timeout \| cancelled \| invalid_output`	`completed \| hard_timeout \| cancelled \| aborted \| failed`
Where it comes from	Task validation, handoff results	`agent.run(..., return_outcome=True)` / `agent.astart(..., return_outcome=True)`
Purpose	Typed validation/handoff status (retry, invalid-output detection)	Host-facing terminal outcome for a whole run (bot/gateway dispatch)

from praisonaiagents import Agent, AgentRunOutcome

agent = Agent(name="Research Agent", instructions="Research and report clearly")
outcome = agent.start("Summarise agent run outcomes")
assert isinstance(outcome, AgentRunOutcome)

The user handles every finish state in code; the agent returns a typed AgentRunOutcome instead of an ambiguous string.

Quick Start

Simple Usage

Every agent execution returns an AgentRunOutcome that you can check for success.

from praisonaiagents import Agent, AgentRunOutcome

agent = Agent(
    name="Research Agent",
    instructions="Research the given topic thoroughly"
)

# Agent executes and produces an outcome
result = agent.start("Research renewable energy")

# Check the outcome
if result.outcome.is_success():
    print(f"Success: {result.outcome.output}")
else:
    print(f"Failed: {result.outcome.error}")

Exhaustive Matching

Match all five status types exhaustively to handle every possible outcome.

from praisonaiagents import Agent, AgentRunOutcome

agent = Agent(name="Validator")
result = agent.start("Validate this data")

# Handle all possible outcomes
if result.outcome.status == "success":
    process_success(result.outcome.output)
elif result.outcome.status == "timeout":
    retry_with_longer_timeout(result)
elif result.outcome.status == "invalid_output":
    fix_validation_and_retry(result)
elif result.outcome.status == "cancelled":
    handle_cancellation(result)
elif result.outcome.status == "failure":
    log_permanent_error(result.outcome.error)

Validation Routing

Access typed outcomes from task validation instead of parsing strings.

from praisonaiagents import Agent, Task, PraisonAIAgents

# Setup workflow with validation
workflow = PraisonAIAgents(
    agents=[validator_agent, executor_agent],
    tasks=[
        Task(description="Validate input", task_type="decision"),
        Task(description="Execute if valid")
    ]
)

result = workflow.kickoff()

# Check validation outcome
validation_task = result.tasks[0]
if validation_task.validation_outcome.status == "invalid_output":
    print(f"Validation failed: {validation_task.validation_outcome.error}")
    retry_with_fixes()
else:
    proceed_to_execution()

How It Works

Every agent execution produces an AgentRunOutcome with a typed status that enables exhaustive pattern matching:

Status	Meaning	Retryable	When It Occurs
`success`	Completed successfully	No	Agent produced valid output
`failure`	Non-retryable logic error	No	Unhandled exception, logic error
`timeout`	Operation exceeded time limit	Yes	Slow LLM, network hang
`cancelled`	External cancel signal	No	User Ctrl-C, parent cancelled child
`invalid_output`	Output didn’t pass validation	Yes	Wrong format, validator rejected

The Five Statuses

Status	Meaning	Retryable	Typical Cause
`success`	Completed successfully	No	Agent produced valid output
`failure`	Non-retryable logic error	No	Unhandled exception, validation logic error
`timeout`	Operation exceeded time limit	Yes	Slow LLM, slow tool, network hang
`cancelled`	External cancel signal	No	User Ctrl-C, parent agent cancelled child
`invalid_output`	Output didn’t pass validation	Yes	Wrong format, missing fields, validator rejected

Creating Outcomes

Create outcomes using factory methods — each sets appropriate defaults automatically.

from praisonaiagents import AgentRunOutcome

# Success with output
outcome = AgentRunOutcome.success(
    output="Task completed successfully",
    elapsed_s=2.5,
    agent_name="Research Agent"
)

# General failure
outcome = AgentRunOutcome.failure(
    error="Unexpected error occurred",
    error_category="execution",
    agent_name="Analysis Agent"
)

# Timeout - auto-sets error_category="timeout"
outcome = AgentRunOutcome.timeout(
    error="Agent timed out after 30s",
    elapsed_s=30.0
)

# Cancelled - auto-sets error_category="cancelled"
outcome = AgentRunOutcome.cancelled(
    error="User cancelled the operation"
)

# Invalid output - auto-sets error_category="validation"
outcome = AgentRunOutcome.invalid_output(
    error="Output format is invalid"
)

Retry Decisions

Use is_retryable() to determine if an operation can be retried safely.

from praisonaiagents import Agent

agent = Agent(name="Processor")

for attempt in range(3):
    result = agent.start("Process data")
    
    if result.outcome.is_success():
        break
    elif result.outcome.is_retryable():
        print(f"Attempt {attempt + 1} failed: {result.outcome.error}")
        continue
    else:
        print(f"Permanent failure: {result.outcome.error}")
        break

Reading the Outcome From a Task

After task validation routing, check both the new typed outcome and legacy feedback.

from praisonaiagents import Task, PraisonAIAgents

# Task with decision routing
validation_task = Task(
    description="Validate the user input",
    task_type="decision"
)

workflow = PraisonAIAgents(
    agents=[validator_agent],
    tasks=[validation_task]
)

result = workflow.kickoff()

# Access typed outcome (recommended)
outcome = validation_task.validation_outcome
if outcome.status == "invalid_output":
    print(f"Validation failed: {outcome.error}")

# Legacy dict still available for backward compatibility
feedback = validation_task.validation_feedback
print(f"Legacy status: {feedback['status']}")

HandoffResult Integration

Handoff results now include typed outcomes automatically derived from legacy fields.

from praisonaiagents import Agent, handoff

billing_agent = Agent(name="Billing Agent")
support_agent = Agent(
    name="Support Agent",
    handoffs=[billing_agent]
)

# Handoff to billing agent
result = support_agent.handoff_to(billing_agent, "Handle billing issue")

# Check typed outcome
if result.outcome.status == "timeout":
    print(f"Handoff timed out: {result.outcome.error}")
    retry_handoff()
elif result.outcome.is_success():
    print(f"Handoff successful: {result.outcome.output}")

Migration from String-Based Validation

Replace string parsing with typed status matching for safer code. Before:

# String parsing - error-prone
if decision_str in ["invalid", "retry", "failed", "errors"]:
    handle_validation_failure()
elif decision_str in ["success", "valid", "approved"]:
    proceed_with_task()

After:

# Typed matching - exhaustive and safe
if outcome.status == "invalid_output":
    handle_validation_failure()
elif outcome.status == "success":
    proceed_with_task()

For gradual migration, use the compatibility helper:

from praisonaiagents import validate_decision_string

# Convert legacy string to typed status
status = validate_decision_string(legacy_decision_str)
if status == "invalid_output":
    handle_invalid_output()

Decision Flow

Best Practices

Prefer status matching over string parsing

Always match against the typed status field instead of parsing error messages or legacy strings.

# Good - exhaustive type-safe matching
if outcome.status == "invalid_output":
    retry_with_fixes()

# Bad - brittle string parsing
if "invalid" in str(outcome.error):
    retry_with_fixes()

Use `is_retryable()` to drive retry logic

Let the outcome determine retry behavior instead of hardcoding status lists.

# Good - use built-in retry detection
if outcome.is_retryable():
    schedule_retry()

# Bad - maintain your own retry logic
if outcome.status in ["timeout", "invalid_output"]:
    schedule_retry()

Put structured data in `context`, not in `error`

Use the context field for machine-readable metadata, keep error human-readable.

# Good - structured context
outcome = AgentRunOutcome.failure(
    error="Database connection failed",
    context={
        "database_host": "db.example.com",
        "timeout_seconds": 30,
        "retry_count": 3
    }
)

# Bad - structured data in error message
outcome = AgentRunOutcome.failure(
    error="Database connection failed: host=db.example.com, timeout=30s"
)

Always handle all five statuses

Exhaustive matching prevents bugs from unhandled cases. Avoid fall-through else clauses.

# Good - explicit handling
if outcome.status == "success":
    handle_success(outcome.output)
elif outcome.status == "timeout":
    handle_timeout()
elif outcome.status == "invalid_output":
    handle_validation_error()
elif outcome.status == "cancelled":
    handle_cancellation()
elif outcome.status == "failure":
    handle_permanent_error()
# No else clause needed - all cases covered

# Bad - fall-through else
if outcome.status == "success":
    handle_success()
else:
    # What exactly happened? Unknown!
    handle_generic_error()

CLI Mapping (`praisonai run`)

The praisonai run CLI wraps the SDK outcome into a success / truncated / failure exit signal for pipelines: any falsy or empty result (None, "", all-whitespace) exits 1 with a machine-readable run_failed payload; a non-empty result that hit the step limit exits 2 with a truncated payload; any other non-empty result exits 0 with the existing text/JSON output.

SDK outcome	CLI exit code	`--output json` `status`
`success` (non-empty output, `agent.last_stop_reason != "max_steps"`)	`0`	absent (success payload)
`success` (non-empty output, `agent.last_stop_reason == "max_steps"`) — a step-limit-truncated finalisation summary	`2`	`"truncated"` (result preserved as the summary text)
`failure` / `timeout` / `cancelled` / `invalid_output` (falsy or empty result surfaced to `Agent.start` / `run`)	`1`	`"failed"` (with `code: "run_failed"`)

See praisonai run → Exit Codes for the full CLI contract, the failure and truncated payload schemas, and CI usage examples.

The SDK-level statuses stay available programmatically for Python/YAML users who want fine-grained matching. On the CLI, step-limit truncation is now surfaced distinctly (exit 2, status: "truncated") rather than masked as success — see Exit Codes.

Task Validation & Feedback

Task validation with typed outcomes

Agent Handoffs

Agent-to-agent delegation with outcomes

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)

Agent Run Outcomes

Quick Start

How It Works

The Five Statuses

Creating Outcomes

Retry Decisions

Reading the Outcome From a Task

HandoffResult Integration

Migration from String-Based Validation

Decision Flow

Best Practices

CLI Mapping (`praisonai run`)

Task Validation & Feedback

Agent Handoffs

​Quick Start

​How It Works

​The Five Statuses

​Creating Outcomes

​Retry Decisions

​Reading the Outcome From a Task

​HandoffResult Integration

​Migration from String-Based Validation

​Decision Flow

​Best Practices

​CLI Mapping (praisonai run)

​Related

Task Validation & Feedback

Agent Handoffs

Quick Start

How It Works

The Five Statuses

Creating Outcomes

Retry Decisions

Reading the Outcome From a Task

HandoffResult Integration

Migration from String-Based Validation

Decision Flow

Best Practices

CLI Mapping (`praisonai run`)

Related