Skip to main content
from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful.", output=True)
agent.start("Summarise this log file.")
Display callbacks let you react to agent events — tool calls, LLM turns, errors — without changing agent logic. The user runs the agent; display callbacks fire on tool calls, LLM turns, and errors for custom terminals or dashboards.

​
How It Works

​
Quick Start

1

Register a callback

from praisonaiagents import Agent, register_display_callback

def on_interaction(message=None, response=None, **kwargs):
    print(f"User: {message}")
    print(f"Agent: {response}")

register_display_callback("interaction", on_interaction)

agent = Agent(name="assistant", instructions="Be concise.")
agent.start("Say hello in one sentence.")
2

Log tool calls

from praisonaiagents import Agent, register_display_callback

def on_tool_call(tool_name=None, **kwargs):
    print(f"Tool: {tool_name}")

register_display_callback("tool_call", on_tool_call)

agent = Agent(
    name="researcher",
    instructions="Use tools when helpful.",
    tools=["web_search"],
)
agent.start("Latest Python release version?")
3

Async callback for dashboards

import asyncio
from praisonaiagents import Agent, register_display_callback

async def push_to_ui(message=None, response=None, **kwargs):
    await asyncio.sleep(0)  # replace with your WebSocket / HTTP call
    print({"message": message, "response": response})

register_display_callback("interaction", push_to_ui, is_async=True)

agent = Agent(name="assistant", instructions="Be helpful.")
agent.start("Summarise loop detection in one line.")

​
Callback Types

TypeWhen it fires
interactionUser message and agent response
tool_callBefore or during a tool invocation
errorAgent or tool error
llm_start / llm_endLLM request lifecycle
llm_contentStreaming token chunks
autonomy_iterationAutonomous loop iteration
autonomy_doom_loopDoom loop detected in autonomy mode
retryRetry after transient failure
Register with register_display_callback(type, fn, is_async=False). Alias: add_display_callback.

​
Configuration Options

OptionTypeDefaultDescription
display_typestr—One of the supported callback types above
callback_fncallable—Sync or async handler
is_asyncboolFalseStore in the async registry when True
Callbacks receive keyword arguments matching the event (for example message, response, tool_name, agent_name). Extra kwargs are filtered to the function signature automatically.

​
Best Practices

Display callbacks run on the hot path. Log or enqueue work — avoid heavy I/O in sync handlers.
Set is_async=True when writing to WebSockets, Slack, or dashboards so the agent loop stays responsive.
A failing callback should not crash the agent. Catch, log, and return.
Use display callbacks for output formatting; use hooks when you need to allow, block, or mutate tool calls.

Display System

TaskOutput, terminal rendering, and global registries

Callbacks

Broader callback patterns for agents and tasks