> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Run Outcome • AI Agent SDK

> AgentRunOutcome: Structured outcome for agent execution, validation, and handoff operations.

# AgentRunOutcome

> Defined in the [**Run Outcome**](https://praison.ai/docs/sdk/reference/praisonaiagents/modules/run_outcome.md) module.

AI Agent

Structured outcome for agent execution, validation, and handoff operations.

Replaces freeform string parsing with typed status values that callers
can match exhaustively. Provides structured metadata for debugging and
retry policies.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#8B0000', 'primaryTextColor': '#fff', 'primaryBorderColor': '#710101', 'lineColor': '#189AB4', 'secondaryColor': '#189AB4', 'tertiaryColor': '#fff' }}}%%

graph LR
    input["Input Data"] --> agent["Agent: AgentRunOutcome"]
    agent --> output["Output Result"]
    style agent fill:#8B0000,color:#fff
    style input fill:#8B0000,color:#fff
    style output fill:#8B0000,color:#fff
```

## Properties

**status** `RunStatus`

No description available.

**output** `Optional[str]`

No description available.

**error** `Optional[str]`

No description available.

**error\_category** `Optional[str]`

No description available.

**elapsed\_s** `float`

No description available.

**agent\_name** `Optional[str]`

No description available.

**run\_id** `Optional[str]`

No description available.

**context** `Optional`

No description available.

## Methods

> [card] [success()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/AgentRunOutcome-success.md)
>
> Create a successful outcome.

> [card] [failure()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/AgentRunOutcome-failure.md)
>
> Create a general failure outcome.

> [card] [timeout()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/AgentRunOutcome-timeout.md)
>
> Create a timeout outcome.

> [card] [cancelled()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/AgentRunOutcome-cancelled.md)
>
> Create a cancelled outcome.

> [card] [invalid\_output()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/AgentRunOutcome-invalid_output.md)
>
> Create an invalid output outcome.

> [card] [is\_success()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/AgentRunOutcome-is_success.md)
>
> Check if the outcome represents successful completion.

> [card] [is\_failure()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/AgentRunOutcome-is_failure.md)
>
> Check if the outcome represents any kind of failure.

> [card] [is\_retryable()](https://praison.ai/docs/sdk/reference/praisonaiagents/functions/AgentRunOutcome-is_retryable.md)
>
> Check if this outcome represents a potentially retryable failure.

> [accordion] Internal & Generic Methods
>
> * **to\_dict**: Convert to dictionary for serialization or logging.

## Usage

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
Success case:
    >>> outcome = AgentRunOutcome(status="success", output="Task completed")
    >>> assert outcome.is_success()
    
    Validation failure:
    >>> outcome = AgentRunOutcome(
    ...     status="invalid_output", 
    ...     error="Output format is invalid",
    ...     error_category="validation"
    ... )
    >>> assert outcome.is_retryable()
    
    Timeout with context:
    >>> outcome = AgentRunOutcome(
    ...     status="timeout",
    ...     error="Agent timed out after 30s",
    ...     elapsed_s=30.0,
    ...     agent_name="researcher"
    ... )
```

## Source

> [card] [View on GitHub](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/run_outcome.py#L78)
>
> `praisonaiagents/run_outcome.py` at line 78

***

## Related Documentation

> [card] [Agents Concept](https://praison.ai/docs/docs/concepts/agents)

> [card] [Single Agent Guide](https://praison.ai/docs/docs/guides/single-agent)

> [card] [Multi-Agent Guide](https://praison.ai/docs/docs/guides/multi-agent)

> [card] [Agent Configuration](https://praison.ai/docs/docs/configuration/agent-config)

> [card] [Auto Agents](https://praison.ai/docs/docs/features/autoagents)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.