Enum FinishReason 

#[non_exhaustive]
pub enum FinishReason {
    Stop,
    Length,
    ToolCalls,
    ContentFilter,
    Other(String),
    MaxToolIterations,
    Unspecified,
}

Why the model stopped generating.

OpenAI-compatible servers report this as a finish_reason string on the final streaming chunk. The SDK maps the well-known values onto variants and preserves anything else verbatim in FinishReason::Other, so a provider-specific reason is never silently flattened into a generic one.

Why Unspecified exists

finish_reason is optional in practice. llama.cpp, vLLM, and several local gateways stream content and then close the connection (or send data: [DONE]) with finish_reason still null. Reporting that as FinishReason::Stop would claim the model finished cleanly when the SDK has no evidence either way, so it is reported as FinishReason::Unspecified instead — a distinct, checkable state.

Examples

The distinction that matters for callers parsing structured output:

use open_agent::FinishReason;

// A truncated response is worth retrying with a larger budget.
assert!(FinishReason::Length.is_truncated());
// A clean stop that produced unparseable output is a model behaviour problem.
assert!(!FinishReason::Stop.is_truncated());

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Stop

Generation completed naturally ("stop").

Length

Generation was cut off at the token limit ("length").

The content delivered before this point is a prefix of what the model intended to say.

ToolCalls

The model finished in order to call tools ("tool_calls").

ContentFilter

Generation was halted by a content filter ("content_filter").

Other(String)

A reason the SDK does not recognise, preserved exactly as the server sent it.

MaxToolIterations

The SDK’s automatic tool-execution loop stopped at max_tool_iterations.

Unlike every other variant this does not come from the server: generation was cut short by the client, and the model’s own finish_reason for the last round would have been ToolCalls — an accurate answer to a different question than “why did this operation stop?”. Reported only by Client::finish_reason() in auto-execution mode; it never appears in a StreamEvent::Finish, and FinishReason::from_wire never produces it.

Unspecified

The stream ended without the server ever reporting a reason.

This is not an error — it is the normal behaviour of several OpenAI-compatible servers. It means “no information”, which is deliberately distinct from FinishReason::Stop.

Implementations

impl FinishReason

pub fn from_wire(raw: &str) -> Self

Maps a raw finish_reason string from the wire onto a variant.

Matching is ASCII-case-insensitive because servers are inconsistent about casing. Unrecognised values are preserved verbatim (original casing intact) in FinishReason::Other.

Examples

use open_agent::FinishReason;

assert_eq!(FinishReason::from_wire("length"), FinishReason::Length);
assert_eq!(
    FinishReason::from_wire("ERR"),
    FinishReason::Other("ERR".to_string())
);

pub fn as_str(&self) -> &str

Returns the canonical wire string for this reason.

FinishReason::Unspecified has no wire representation — it is reported as "unspecified" so it can be logged without being mistaken for "stop".

pub fn is_truncated(&self) -> bool

Returns true when generation was cut short by the token limit.

This is the signal that a partial or unparseable response is the SDK caller’s budget problem rather than a model that refused to answer in the requested format.

Trait Implementations

impl Clone for FinishReason

fn clone(&self) -> FinishReason

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FinishReason

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for FinishReason

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for FinishReason

impl PartialEq for FinishReason

fn eq(&self, other: &FinishReason) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for FinishReason