Enum AgentError 

pub enum AgentError {
    MaxIterationsReached(usize),
    LoopDetected {
        signature: String,
    },
    ParallelToolLimitExceeded {
        count: usize,
        limit: usize,
    },
    StagnationDetected {
        repeated_text_hash: String,
        count: usize,
        max_steps: usize,
    },
    Internal(String),
}

Errors that terminate the agentic loop.

These represent conditions where AgentLoopPort::run cannot continue. They do not include tool execution failures — those are encoded as ToolResult { success: false } and fed back to the LLM as context.

Variants

MaxIterationsReached(usize)

The loop reached AgentConfig::max_iterations without producing a final answer.

LoopDetected

The loop detected a tool-call signature repeated back to back and answered the same way, indicating the model is stuck rather than working.

The signature field is a stable hash of the tool-call batch that recurred, with nothing in between and getting the same answer back each time, more times than AgentConfig::max_repeated_batch_steps allows. A batch that repeats with other work between occurrences is not a cycle and does not raise this; neither does one whose answers keep changing, which is an agent polling for output rather than a stuck one.

It is also raised when a batch that is not read-only has been carried past max_observation_steps by changing answers. The two are not distinguished here: the remedy is the same, and this variant is mirrored into the proxy’s 400 body.

Fields

signature: String

Stable hash of the repeated tool-call batch (for diagnostics).

ParallelToolLimitExceeded

The LLM produced more tool calls in a single batch than configured by AgentConfig::max_parallel_tools.

This is a model protocol violation: the LLM returned more concurrent calls than the loop is configured to dispatch. The loop aborts rather than silently truncating the batch, because partial execution could leave the model with an incoherent view of which calls were handled.

Fields

count: usize

Number of tool calls the LLM returned.

limit: usize

The configured maximum (AgentConfig::max_parallel_tools).

StagnationDetected

The assistant produced the same text content too many times in a short span of prose turns, indicating a non-tool-calling repetition loop.

Preserves the FNV-1a hash of the repeated text, the occurrence count within the window (including baseline), and the configured max_stagnation_steps limit — giving callers structured access to the stagnation evidence without parsing an error string.

Detection is windowed: both strictly consecutive repetitions and A → B → A oscillations are caught inside the window.

Fields

repeated_text_hash: String

FNV-1a hash of the repeated assistant text, hex-encoded for diagnostics. Stored as String to decouple the public API from the internal u64 representation so callers never need to know the hashing algorithm.

count: usize

Total number of times this text has been seen in the session (including the baseline occurrence).

max_steps: usize

The configured stagnation limit at the time of detection.

Internal(String)

An unrecoverable internal error inside the loop implementation.

Trait Implementations

impl Debug for AgentError

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

Formats the value using the given formatter.

impl Display for AgentError

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

Formats the value using the given formatter.

impl Error for AgentError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.