> ## 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.

# Output Styles

> Control how agents display responses — from silent SDK mode to verbose interactive output

Control what your agent prints during a run — silent for APIs, status for CLI, stream for chat UIs.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are helpful.",
    output="status",
)
result = agent.start("What is the capital of France?")
```

The user runs the agent; output presets control whether responses stay silent, stream, or show status lines.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Output Styles"
        SILENT["🔇 silent\n(default)"]
        STATUS["📊 status"]
        VERBOSE["📋 verbose"]
        STREAM["🌊 stream"]
        JSON["📄 json"]
    end

    Agent["🤖 Agent"] --> SILENT
    Agent --> STATUS
    Agent --> VERBOSE
    Agent --> STREAM
    Agent --> JSON

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef success fill:#10B981,stroke:#7C90A0,color:#fff

    class Agent agent
    class SILENT,STATUS,VERBOSE tool
    class STREAM,JSON success
```

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant OutputStyles

    User->>Agent: Request
    Agent->>OutputStyles: Process
    OutputStyles-->>Agent: Result
    Agent-->>User: Response
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    Pass `output` as a string preset:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="Assistant",
        instructions="You are a helpful assistant.",
        output="status"
    )

    result = agent.start("What is the weather in Tokyo?")
    ```
  </Step>

  <Step title="With Configuration">
    Use `OutputConfig` for fine-grained control:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, OutputConfig

    agent = Agent(
        name="Assistant",
        instructions="You are a helpful assistant.",
        output=OutputConfig(
            verbose=True,
            markdown=True,
            stream=True,
            metrics=True,
        )
    )

    result = agent.start("Explain machine learning in simple terms")
    ```
  </Step>
</Steps>

***

## Which Style Should I Use?

Pick a preset based on where the output is consumed.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start([Where does output go?]) --> Q1{How is it consumed?}
    Q1 -->|API / programmatic| A[silent<br/>default, zero overhead]
    Q1 -->|CLI progress| B[status<br/>timestamped status lines]
    Q1 -->|User-facing terminal| C[verbose<br/>Rich panels + color]
    Q1 -->|Chat UI| D[stream<br/>real-time tokens]
    Q1 -->|Pipe to other tools| E[json<br/>JSONL events]

    classDef start fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef question fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef answer fill:#10B981,stroke:#7C90A0,color:#fff

    class Start start
    class Q1 question
    class A,B,C,D,E answer
```

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as Output Styles

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result
    Agent-->>User: Response
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph "Which preset should I use?"
        Q1{"Building an\napp or API?"}
        Q2{"Want to see\ntool calls?"}
        Q3{"Need timestamps\nor metrics?"}
        Q4{"Streaming\nchat UI?"}
    end

    SILENT["🔇 silent\n(return value only)"]
    STATUS["📊 status\n(inline tool trace)"]
    TRACE["🕐 trace\n(timestamped trace)"]
    STREAM["🌊 stream\n(real-time tokens)"]
    VERBOSE["📋 verbose\n(full panels)"]

    Q1 -->|Yes| SILENT
    Q1 -->|No| Q2
    Q2 -->|Yes| Q3
    Q2 -->|No, just response| VERBOSE
    Q3 -->|Yes| TRACE
    Q3 -->|No| STATUS
    Q1 --> Q4
    Q4 -->|Yes| STREAM

    classDef question fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class Q1,Q2,Q3,Q4 question
    class SILENT,STATUS,TRACE,STREAM,VERBOSE result
```

| Preset    | Description                             | Best For               |
| --------- | --------------------------------------- | ---------------------- |
| `silent`  | No output, returns value only (default) | SDK / programmatic use |
| `editor`  | `Step 1: 📄 Creating file → ✓ Done`     | CLI default, beginners |
| `status`  | `▸ AI → thinking` + inline tool calls   | Simple CLI output      |
| `trace`   | Status with `[HH:MM:SS]` timestamps     | Progress monitoring    |
| `debug`   | Trace + metrics, no boxes               | Developer debugging    |
| `verbose` | Task + Tools + Response panels          | Interactive sessions   |
| `stream`  | Real-time token streaming               | Chat interfaces        |
| `json`    | JSONL events on stdout                  | Scripting / piping     |

***

## Configuration Options

<Card title="OutputConfig SDK Reference" icon="code" href="/docs/sdk/reference/python/classes/OutputConfig">
  Full parameter reference for OutputConfig
</Card>

**Precedence ladder** — choose the level you need:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Level 1: String preset
agent = Agent(output="verbose")   # "silent" | "minimal" | "normal" | "verbose" | "debug"

# Level 2: OutputConfig (full control)
agent = Agent(output=OutputConfig(verbose=True, stream=True, output_file="results.md"))
```

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, OutputConfig

agent = Agent(
    instructions="...",
    output=OutputConfig(
        verbose=False,
        markdown=False,
        stream=False,
        metrics=False,
        reasoning_steps=False,
        actions_trace=False,
        json_output=False,
        simple_output=False,
        status_trace=False,
        editor_output=False,
        show_parameters=False,
        output_file=None,
        template=None,
        tool_output_limit=16000,
    )
)
```

| Option              | Type   | Default | Description                                        |
| ------------------- | ------ | ------- | -------------------------------------------------- |
| `verbose`           | `bool` | `False` | Show Rich panels for tasks and responses           |
| `markdown`          | `bool` | `False` | Render markdown formatting                         |
| `stream`            | `bool` | `False` | Stream tokens in real time                         |
| `metrics`           | `bool` | `False` | Display token usage and cost after each response   |
| `reasoning_steps`   | `bool` | `False` | Show internal reasoning steps                      |
| `actions_trace`     | `bool` | `False` | Show tool calls and lifecycle events on stderr     |
| `json_output`       | `bool` | `False` | Emit JSONL events for piping                       |
| `simple_output`     | `bool` | `False` | Print response without Rich panels                 |
| `status_trace`      | `bool` | `False` | Clean inline status updates                        |
| `editor_output`     | `bool` | `False` | Numbered steps with emoji icons (CLI default)      |
| `show_parameters`   | `bool` | `False` | Show LLM parameters (debug preset)                 |
| `style`             | `Any`  | `None`  | Custom output styling object                       |
| `output_file`       | `str`  | `None`  | File path to automatically save the agent response |
| `template`          | `str`  | `None`  | Format template for the response                   |
| `tool_output_limit` | `int`  | `16000` | Maximum characters for tool output                 |

### String Preset Aliases

| Alias              | Maps To   |
| ------------------ | --------- |
| `plain`, `minimal` | `silent`  |
| `normal`           | `verbose` |
| `text`, `actions`  | `status`  |

***

## Common Patterns

### Silent (SDK Default)

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    instructions="You are a helpful assistant.",
)

result = agent.start("Summarize this article: ...")
print(result)
```

### Status (CLI / Interactive)

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(
    instructions="You are a helpful assistant.",
    output="status"
)

result = agent.start("What is the capital of France?")
```

### Save Response to File

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, OutputConfig

agent = Agent(
    instructions="Write a detailed report",
    output=OutputConfig(
        output_file="report.md",
        markdown=True,
    )
)

agent.start("Write a report on renewable energy trends")
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use silent mode for production APIs">
    Silent mode (the default) has zero output overhead. Use it when the agent's return value is consumed by code rather than displayed to users.
  </Accordion>

  <Accordion title="Use editor mode for beginner-facing CLIs">
    `output="editor"` shows human-friendly numbered steps with emoji icons. It is the default when running `praisonai "prompt"` from the command line.
  </Accordion>

  <Accordion title="Use stream mode for chat interfaces">
    Set `output="stream"` when building conversational UIs — tokens appear in real time for a responsive feel.
  </Accordion>

  <Accordion title="Use output_file to persist long-form responses">
    Set `output=OutputConfig(output_file="result.md")` to automatically save the agent's response. Useful for reports, summaries, and generated documents.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Async Agents" icon="clock" href="/docs/features/async">
    Run agents asynchronously for better performance
  </Card>

  <Card title="Callbacks" icon="webhook" href="/docs/features/callbacks">
    Hook into agent lifecycle events
  </Card>
</CardGroup>