Skip to main content
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. 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.
surface_completion_reason is a BotSessionManager constructor parameter — not a BotConfig field. Enable it where the session manager is built.

​
Quick Start

1

Enable the notes on the gateway

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

Customise a note per turn

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

​
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:
Off by default: existing deployments and clean completions are byte-for-byte unchanged.

​
Common Patterns

Long research agents with a high max_steps — enable the note so "continue" becomes a discoverable UX:
Cancellation UX — the user hits /stop and sees the cancelled note instead of no reply:
Error transparency — the user sees the error note and can retry without opening a ticket:

​
Best Practices

Enable it for public-facing gateways. Internal bots often prefer silence, so keep the default False there.
TurnCompletion.detail overrides the default note per turn — use it to keep messages localised and on-brand.
Notes never surface on a clean completion, so enabling this adds no noise to successful turns.
Combine with the step-limit docs so users understand the “reply continue” flow when a turn hits its budget.

Max Steps

Cap tool-use steps and detect graceful truncation with last_stop_reason.

Error Handling

Detect and recover from turns that end early with last_stop_reason.