Visible-Outcome Guarantee

Every inbound turn ends in a visible reply or a deliberate, recorded silence — never a blank.

Every inbound message ends in one of two recorded states: a visible reply, or a deliberate silence — a blank or placeholder final is never dropped.

Quick Start

1. It's on by default

   The guarantee is always active — you don’t enable it. A normal agent already benefits:

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Support Bot",
       instructions="Answer the user's question.",
   )

2. Customise the fallback sentence

   Set empty_final_message in BotConfig.metadata to change the sentence shown when a turn produces no visible text:

   from praisonaiagents import Agent
   from praisonaiagents.bots import BotConfig
   
   agent = Agent(
       name="Support Bot",
       instructions="Answer the user's question.",
   )
   
   config = BotConfig(
       metadata={"empty_final_message": "I'm on it — no message this turn."}
   )

How It Works

Classification and substitution happen once, at fire_message_sending() — the single delivery funnel every adapter shares — so no adapter re-decides “blank” differently.

A blank, whitespace-only, or [tool_calls: …] final is treated as empty, not silence and substituted with the fallback. A blank reply is never confused with a deliberate NO_REPLY.

classify_final

classify_final is the single decision the bot layer uses to tell a real reply, an empty final, and a deliberate silence apart.

from praisonaiagents.bots import classify_final

classify_final("NO_REPLY")                  # "silence"
classify_final("")                          # "empty"
classify_final("   ")                       # "empty"
classify_final("[tool_calls: search_web]")  # "empty"
classify_final("Here is your answer.")      # "text"

Configuration Options

The fallback sentence is the only knob. Precedence: direct attribute > metadata > default.

from praisonaiagents.bots import BotConfig

# Programmatic callers can set the attribute directly
config = BotConfig(empty_final_message="I'm on it — no message this turn.")

from praisonaiagents.bots import BotConfig

# YAML-friendly seam — no new typed knob needed
config = BotConfig(metadata={"empty_final_message": "I'm on it — no message this turn."})

metadata:
  empty_final_message: "I'm on it — no message this turn."

Best Practices

Related