Turn Completion Notes

Tell chat users why an agent turn stopped early instead of a silent truncation

Turn a coarse last_stop_reason into a concise, user-safe note so a chat user learns why a turn stopped early — instead of getting a silently truncated or empty reply.

Covered reasons mirror Agent.last_stop_reason: completed | max_steps | cancelled | error, plus the three provider-block reasons content_filtered | refused | length_truncated. A deep-research agent hits its step limit; instead of a truncated answer, the reply ends with ⏳ I stopped after reaching the step limit — reply "continue" to carry on. As of PR #5764, error is reliably set on a terminal LLM failure (server 500, revoked key, exhausted retries) in both the sync and async paths, so the gateway can surface the default ⚠️ This turn ended early due to an error — please try again. note instead of a silent empty reply.

from praisonaiagents import Agent
from praisonai.bots import BotSessionManager

agent = Agent(
    name="Deep Researcher",
    instructions="Do multi-step web research and summarise findings.",
    max_steps=20,  # long budget — truncation is possible
)

# Opt in on the session manager: tell the user *why* if a turn stops early.
session = BotSessionManager(
    platform="telegram",
    surface_completion_reason=True,
)
# When the agent hits its step budget, the reply ends with the completion note.
reply = await session.chat(agent, user_id="123", prompt="Research X in depth")

Quick Start

1. Enable the notes on the gateway

   Construct the session manager with surface_completion_reason=True. Clean completed turns still surface nothing.

   from praisonai.bots import BotSessionManager
   
   session = BotSessionManager(
       platform="telegram",
       surface_completion_reason=True,  # append the note when a turn stops early
   )

2. Customise a note per turn

   Override the default note for a turn by returning an AgentReply with a TurnCompletion that carries detail.

   from praisonaiagents.bots import AgentReply, TurnCompletion
   
   reply = AgentReply(
       text="Here's what I found so far.",
       completion=TurnCompletion(
           reason="max_steps",
           detail="Long research task — reply 'continue' to keep going.",
       ),
   )

How It Works

After each turn the session manager reads the agent’s last_stop_reason, wraps it in a TurnCompletion, and — when enabled — appends the note to the reply.

extract_completion recognises an AgentReply with a completion, a serialised dict, or any object exposing completion / last_stop_reason (including a bare Agent). append_completion_note returns the text unchanged when disabled, when there is no completion, or when the turn completed cleanly.

Reasons and Default Notes

TurnCompletion.note() maps each stop reason to a user-safe message. A clean completion is intentionally silent.

Configuration Options

TurnCompletion and append_completion_note take these fields:

Common Patterns

Long research agents with a high max_steps — enable the note so "continue" becomes a discoverable UX:

agent = Agent(name="Researcher", instructions="Deep multi-step research.", max_steps=20)
session = BotSessionManager(platform="telegram", surface_completion_reason=True)
# Hits the budget → reply ends with the "reply continue" note.

Cancellation UX — the user hits /stop and sees the cancelled note instead of no reply:

# reason="cancelled" → "🛑 This turn was interrupted before it finished — send it again to retry."

Error transparency — the user sees the error note and can retry without opening a ticket:

# reason="error" → "⚠️ This turn ended early due to an error — please try again."

Best Practices

Related