Output Styles

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

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.

How It Works

Quick Start

Simple Usage

Pass output as a string preset:

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?")

With Configuration

Use OutputConfig for fine-grained control:

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")

Which Style Should I Use?

Pick a preset based on where the output is consumed.

How It Works

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

Concurrent execution (PR #5219)

status and trace route through a shared per-process singleton whose _output_lock is now actually acquired (PR #5219, fixes #5162). Reaching for output="status" / output="trace" under asyncio.gather is now safe for the aggregate timing and token/cost metrics — with the caveat that _tool_start_times / _agent_start_times are still keyed by name only. Give each agent a distinct name=. Full detail in Thread Safety → Output singleton lock.

Configuration Options

OutputConfig SDK Reference

Full parameter reference for OutputConfig

Precedence ladder — choose the level you need:

# 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"))

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

Mutual Exclusion of Console Output Modes

Three modes — editor_output, status_trace, and actions_trace — register callbacks on a process-wide registry, not on the individual Agent. Only one can be active at a time in a given Python process, no matter how many Agents you construct. First mode wins. If an earlier Agent already enabled a mode, a later Agent asking for a different one silently keeps the earlier mode’s routing. This stops an Agent-B trace construction from clobbering the callbacks Agent-A wired for editor — which would otherwise route Agent-A’s events through Agent-B’s sink with the wrong formatting and redaction.

from praisonaiagents import Agent

a = Agent(name="A", instructions="You are helpful.", output="editor")   # editor mode wins
b = Agent(name="B", instructions="You are helpful.", output="trace")    # keeps editor mode
c = Agent(name="C", instructions="You are helpful.", output="status")   # keeps editor mode

Precedence within a single Agent when multiple mode flags are set:

editor_output > status_trace > actions_trace

The check-and-enable runs under a per-process lock, so concurrently-constructed Agents cannot both observe “no mode active” and race each other. The silent path (no output mode requested) stays lock-free — the lock is acquired only when a mode is actually requested.

String Preset Aliases

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

Common Patterns

Silent (SDK Default)

from praisonaiagents import Agent

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

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

Status (CLI / Interactive)

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

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

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.

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.

Use stream mode for chat interfaces

Set output="stream" when building conversational UIs — tokens appear in real time for a responsive feel.

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.

Set the console mode once at the entry point

editor, trace, and status share one process-wide callback registry — the first one enabled wins. Configure the mode at the entry point (CLI flag or top-level Agent) and let downstream Agents inherit it, rather than setting different modes on multiple Agents in the same process.

Async Agents

Run agents asynchronously for better performance

Callbacks

Hook into agent lifecycle events

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)

How It Works

Quick Start

Which Style Should I Use?

How It Works

Concurrent execution (PR #5219)

Configuration Options

OutputConfig SDK Reference

Mutual Exclusion of Console Output Modes

String Preset Aliases

Common Patterns

Silent (SDK Default)

Status (CLI / Interactive)

Save Response to File

Best Practices

Async Agents

Callbacks

​How It Works

​Quick Start

​Which Style Should I Use?

​How It Works

​Concurrent execution (PR #5219)

​Configuration Options

OutputConfig SDK Reference

​Mutual Exclusion of Console Output Modes

​String Preset Aliases

​Common Patterns

​Silent (SDK Default)

​Status (CLI / Interactive)

​Save Response to File

​Best Practices

​Related

Async Agents

Callbacks

How It Works

Quick Start

Which Style Should I Use?

How It Works

Concurrent execution (PR #5219)

Configuration Options

Mutual Exclusion of Console Output Modes

String Preset Aliases

Common Patterns

Silent (SDK Default)

Status (CLI / Interactive)

Save Response to File

Best Practices

Related