reduced to a single conditional check against the model's `stop_reason`. When the mode

Difficulty

Beginner

Read Time

59 min

Your Agent Loop Needs a Real Exit: llm-stop-conditions

By Codcompass Team·2026-05-26·59 min read

Resilient Agent Orchestration: Composable Exit Strategies for Unbounded LLM Loops

Current Situation Analysis

The fundamental risk in agentic workflows is the unbounded loop. Unlike deterministic scripts, LLM-driven agents operate on probabilistic outputs. A model may fail to signal completion, enter a recursive reasoning cycle, or exhaust its token budget without terminating. When this occurs, the loop continues executing, consuming API credits and compute resources until an external force intervenes.

This failure mode is frequently overlooked because developers prioritize the "happy path"—the scenario where the model returns a valid termination signal. Consequently, exit logic is often reduced to a single conditional check against the model's stop_reason. When the model deviates from expected behavior, this check never fires, resulting in silent runaway execution.

Real-world incidents highlight the severity. In documented production cases, agents have executed hundreds of iterations without termination, accumulating costs exceeding $40 per run. These events typically involve models repeatedly hitting max_tokens limits, generating truncated responses, and looping back for retry. Without iteration caps, cost ceilings, or duration limits, the system has no mechanism to halt the process autonomously.

The solution is not to add ad-hoc if statements within the loop body. This approach fragments exit logic, reduces testability, and obscures the reason for termination. The robust pattern is to externalize exit strategy into a composable evaluator that enforces guardrails independently of the agent's core logic.

WOW Moment: Key Findings

Comparing loop architectures reveals significant differences in safety, observability, and maintainability. The composable evaluator pattern provides deterministic boundaries while preserving the flexibility of the agent's reasoning process.

Architecture	Cost Exposure	Failure Visibility	Implementation Complexity
Naive Loop	Unbounded	None (Silent failure)	Low
Single Guard	Partial	Low (Generic error)	Medium
Composable Evaluator	Capped	High (Specific trigger)	Low (via library)

The composable approach enables precise control over multiple dimensions simultaneously. You can enforce a budget limit while also detecting stagnation, all within a unified interface. When the loop terminates, the system reports the exact condition that triggered the exit, facilitating immediate debugging and post-run analysis.

Core Solution

The implementation relies on a StopEvaluator pattern. This component aggregates multiple named conditions and assesses the loop state on each iteration. Conditions are defined declaratively and combined using logical operators. The evaluator maintains internal state, such as elapsed time and iteration count, reducing the b

urden on the loop logic.

Architecture Decisions

Separation of Concerns: Exit logic is decoupled from the agent's execution flow. The loop focuses on task progression, while the evaluator enforces boundaries.
Stateless Evaluation: The evaluator accepts current metrics (cost, time, response data) and returns a decision. This design allows the evaluator to be tested in isolation and reused across different agent implementations.
Composability: Conditions are combined using AnyOf (stop if any condition triggers) or AllOf (stop only when all conditions trigger). AnyOf is the standard for safety guardrails, ensuring the most restrictive limit halts execution.

Implementation Example

The following TypeScript example demonstrates the pattern using the llm-stop-conditions library. Interface names are adapted for clarity, mapping directly to the library's core classes.

import { 
    IterationCap, 
    BudgetLimit, 
    DurationLimit, 
    StagnationDetector, 
    CompositeGuard, 
    StopEvaluator 
} from 'llm-stop-conditions';

// Define guardrails with explicit thresholds
const safetyGuard = new CompositeGuard(
    new IterationCap(15),
    new BudgetLimit(5.00),
    new DurationLimit(45.0),
    new StagnationDetector({ turns: 4, minTokens: 30 })
);

const exitController = new StopEvaluator(safetyGuard);

async function runAgent(initialPrompt: string) {
    let context = [initialPrompt];
    
    while (true) {
        // Execute agent step
        const response = await invokeModel(context);
        context.push(response.content);

        // Evaluate exit conditions
        const assessment = exitController.check({
            currentIteration: exitController.iterationCount,
            accumulatedCost: calculateResponseCost(response),
            elapsedSeconds: exitController.timer.elapsed(),
            responsePayload: response
        });

        if (assessment.halt) {
            console.warn(`Agent terminated: ${assessment.trigger}`);
            break;
        }
    }
    
    return context;
}

Rationale for Condition Selection

IterationCap: Prevents infinite loops caused by models that fail to terminate. A limit of 15–20 iterations is typical for most reasoning tasks.
BudgetLimit: Caps financial exposure. This is critical for production systems where runaway loops can incur significant costs.
DurationLimit: Ensures the agent returns within acceptable latency bounds, preventing resource starvation in concurrent environments.
StagnationDetector: Detects when the model is spinning without making progress. This heuristic identifies loops where the model generates short, tool-free responses repeatedly, indicating a loss of coherence.

Pitfall Guide

Production agents encounter edge cases that can bypass naive guardrails. The following pitfalls describe common mistakes and their resolutions.

The "End Turn" Fallacy
- Explanation: Relying solely on the model's stop_reason field. Models may return max_tokens or other non-termination reasons indefinitely.
- Fix: Always include hard caps (IterationCap, BudgetLimit) regardless of the model's reported status.
Stagnation Heuristic Misconfiguration
- Explanation: Setting minTokens too low or turns too aggressively can cause false positives, halting valid reasoning steps that produce concise output.
- Fix: Tune minTokens based on the domain. For tasks requiring detailed analysis, increase the threshold. Use turns: 4 as a conservative default.
Tool Loop Blindness
- Explanation: The StagnationDetector checks for the absence of tool calls. It does not detect loops where the model repeatedly invokes the same tool with identical arguments.
- Fix: Combine the stop evaluator with a tool-call budget library (e.g., tool-call-budgets) to cap per-tool usage.
State Leakage Across Sessions
- Explanation: Reusing an evaluator instance across multiple agent runs without resetting state. This causes accumulated metrics from previous runs to trigger premature termination.
- Fix: Instantiate a new evaluator for each session or explicitly call the reset method before starting a new loop.
Cost Calculation Latency
- Explanation: Passing stale or estimated cost data to the evaluator. If cost updates lag behind actual usage, the BudgetLimit may be exceeded before the evaluator detects the breach.
- Fix: Extract cost metrics directly from the API response payload and pass the precise value on each iteration.
AllOf vs. AnyOf Confusion
- Explanation: Using AllOf for safety conditions. This requires all limits to be breached simultaneously, effectively disabling individual guardrails.
- Fix: Default to AnyOf for guardrails. Use AllOf only for specific business logic, such as "stop when done AND under token limit."
Ignoring Input Token Costs
- Explanation: Calculating cost based only on output tokens. In long-running loops, input context grows, and input token costs can dominate the budget.
- Fix: Include input token costs in the calculateResponseCost function to ensure accurate budget tracking.

Production Bundle

Action Checklist

Define Hard Caps: Establish maximum iterations, cost, and duration before implementing the loop.
Instrument Cost Extraction: Ensure accurate, real-time cost calculation from API responses.
Configure Stagnation Heuristics: Tune StagnationDetector parameters based on task complexity and expected output length.
Implement Logging: Record the assessment.trigger on termination for post-run debugging.
Handle Graceful Degradation: Define fallback behavior when the agent stops prematurely (e.g., return partial results).
Test Edge Cases: Verify loop behavior when the model returns unexpected stop_reason values.
Reset State: Ensure evaluator state is cleared between independent agent sessions.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Development / Debugging	Aggressive caps (`IterationCap: 5`, `BudgetLimit: 0.50`)	Fast feedback; prevents waste during iteration.	Minimal
Production / Critical Path	Budget-first (`BudgetLimit` strict, `DurationLimit` moderate)	Ensures financial predictability; prevents runaway spend.	Capped
Complex Reasoning Tasks	Lenient stagnation (`StagnationDetector: turns: 6`)	Allows deeper exploration without false positives.	Moderate
Multi-Agent Pipeline	Shared budget pool (`BudgetLimit` per stage)	Prevents one stage from consuming the entire pipeline budget.	Distributed

Configuration Template

Use this template to define guardrails in a structured format. This can be loaded from environment variables or a configuration file.

{
  "guardrails": {
    "max_iterations": 20,
    "max_cost_usd": 5.00,
    "max_duration_seconds": 60,
    "stagnation": {
      "enabled": true,
      "turns": 4,
      "min_tokens": 30
    }
  },
  "behavior": {
    "on_stop": "return_partial",
    "log_reason": true
  }
}

Quick Start Guide

Install the Library:
```
pip install llm-stop-conditions
```

Import Core Classes:

from llm_stop_conditions import MaxIterations, MaxCost, MaxSeconds, NoProgress, AnyOf, Evaluator

Define Your Guardrails:

stopper = Evaluator(AnyOf(
    MaxIterations(15),
    MaxCost(5.00),
    MaxSeconds(45),
    NoProgress(turns=4, min_tokens=30)
))

Integrate into Loop: Call stopper.evaluate() on each iteration and check result.should_stop. Break the loop if true and log result.reason.
Verify: Run the agent with a prompt designed to trigger a loop. Confirm that the evaluator halts execution and reports the correct trigger.

Ecosystem Extensions

The stop evaluator addresses exit conditions. For comprehensive agent resilience, combine it with complementary libraries that manage adjacent boundaries:

Tool Call Budgets: Enforces per-tool call limits to prevent tool spam loops.
Token Budget Pool: Manages a shared token/USD pool across concurrent agents.
Agent Deadline: Provides a cooperative deadline mechanism that raises exceptions from any point in the code.
Circuit Breaker: Detects high error rates and halts execution to prevent cascading failures.

These tools operate independently and can be composed within the same loop architecture to build robust, production-grade agent systems.

🎉 Mid-Year Sale — Unlock Full Article

Base plan from just $4.99/mo or $49/yr

7-day free trial · Cancel anytime · 30-day money-back