Display Callbacks

Hook into agent output events for custom terminals, logs, and dashboards

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, tool_input=None, tool_output=None,
                    elapsed_time=None, success=None, **kwargs):
       status = "ok" if success else "failed"
       print(f"[{status}] {tool_name}({tool_input}) -> {tool_output}")
   
   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?")

   Fires on non-streaming and streaming turns since PR #4735. See Streaming coverage.

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

Register with register_display_callback(type, fn, is_async=False). Alias: add_display_callback.

Streaming coverage

Since PR #4735, tool_call fires on all three execution paths — not just non-streaming.

Before #4735 the streaming paths ran tools silently — a streaming UI saw no tool activity even though a tool ran and its result reached the model. The callback now fires once per tool (parallel tools each get their own call), in both the success and failure branches.

tool_call kwargs

A tool_call handler receives these keyword arguments on every path. Accept **kwargs so future additions never break your handler.

Streaming example

tool_call fires the same way whether you stream or not.

from praisonaiagents import Agent, register_display_callback

def on_tool_call(tool_name=None, tool_input=None, tool_output=None,
                 elapsed_time=None, success=None, **kwargs):
    status = "ok" if success else "failed"
    secs = f"{elapsed_time:.3f}s" if elapsed_time is not None else "n/a"
    print(f"[{status}] {tool_name}({tool_input}) -> {tool_output} in {secs}")

register_display_callback("tool_call", on_tool_call)

def my_tool(query: str) -> str:
    """Look something up."""
    return f"Result for {query}"

agent = Agent(
    name="researcher",
    instructions="Use tools when helpful.",
    tools=[my_tool],
)

# Same callback now fires whether stream=True or not.
for chunk in agent.start("Look up the weather in Paris", stream=True):
    print(chunk, end="", flush=True)

Configuration Options

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

Related