A crucial framework-agnostic skill designed to prevent infinite loop recursion, runaway token bills, and stuck behaviors in LLM-driven agent workflows.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install agentsop-bounded-loop
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install agentsop-bounded-loop using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Bounded Loop Control for AI Agents (agentsop-bounded-loop)?
This skill establishes a universal control mechanism for any LLM-driven loop—such as agent retries, plan-act-observe steps, multi-agent handoffs, and self-correcting test-fix cycles. It addresses the fundamental truth that language models are not reliable terminators on their own. By decoupling the termination logic from the AI's internal state and placing it in a framework-agnostic control structure, developers can reliably prevent runaway loops and catastrophic API billing spikes.
With Openclaw Skills, you can design deterministic safeguards including explicit iteration counters, progress witnesses, stagnation detectors, and graceful escalation paths. Implementing this design pattern ensures that when an agent gets stuck or repeats its attempts, the system halts and escalates properly instead of throwing generic framework recursion errors or exhausting your API token budgets.
Bounded Loop Control for AI Agents (agentsop-bounded-loop) Use Cases
- Preventing infinite delegation ping-pong loops in hierarchical multi-agent teams where agents recursively hand off tasks to one another.
- Protecting budgets in self-healing code agent workflows (e.g., test-fix cycles) by hard-capping retries and checking for stagnant errors.
- Implementing self-refining optimization loops where "stop when good enough" is protected by an explicit iteration and time safety budget.
- Intercepting runaway workflows before they hit expensive API limits or trigger framework-level recursion exceptions.
- Safely building long-running background tasks with absolute wall-clock timeout caps and token limits.
How Bounded Loop Control for AI Agents (agentsop-bounded-loop) Works
- Define the Loop Body and Cycle Invariant: Identify the cyclic node or function and designate a progress witness—a state variable that must strictly change (e.g., error list shrinking, revision count incrementing) to prove progress on iteration N+1.
- Initialize a Shared Monotonic Counter: Set up a shared iteration counter in the global state container (such as LangGraph's TypedDict or CrewAI's shared context) instead of relying on isolated, per-agent iteration configurations.
- Run Stagnation Checks: Compare the current state against previous iteration snapshots. If identical inputs, tool calls, or error messages are repeated, trigger an immediate halt.
- Expose Counter Context to LLM Prompts: Pass the current attempt count, total budget, and prior failure records straight into the active system prompts so the model modifies its approach strategically instead of repeating identical queries.
- Route to Escalation: When the counter is exhausted or stagnation is detected, break out of the loop into a designated, non-crashing escalation node.
- Enforce Secondary Safety Nets: Superimpose independent constraints like wall-clock timeouts, token thresholds, and model rate limits on the outer caller wrapper.
Bounded Loop Control for AI Agents (agentsop-bounded-loop) Setup
To apply this skill, configure your agent's state schema and verification logic inside your code setup. Below is an example setup initializing state tracking components:
# Create a schema definition for your bounded agent loop
touch state_schema.py
Next, register a monotonic counter and stagnation check in your agent's control loop:
from typing import TypedDict, Literal, Annotated
import operator
class BoundedState(TypedDict):
messages: list
retries: Annotated[int, operator.add]
last_error: str | None
witness_hash: str | None
def check_termination(state: BoundedState) -> Literal["continue", "escalate"]:
# Cap iteration budget
if state.get("retries", 0) >= 3:
return "escalate"
# Stagnation check
if state.get("last_error") == state.get("previous_error"):
return "escalate"
return "continue"
Bounded Loop Control for AI Agents (agentsop-bounded-loop) Data Schema & Taxonomy
The skill establishes a strict, auditable state taxonomy to ensure control loops run deterministically. Use the following structured fields in your agent's persistent state container:
| State Key | Type | Description | Invariant Rules |
|---|---|---|---|
retries |
int |
Monotonic loop counter tracked via system state. | Must strictly increment by 1 each iteration. |
last_error |
str |
Text representing the error returned in the last iteration. | Empty if the previous iteration succeeded. |
witness_hash |
str |
MD5 or SHA256 signature of tool arguments, plan revisions, or output values. | Used to detect duplicate calls; triggers stagnation if repeated. |
escalation_reason |
str |
Human-readable explanation of why the loop halted (e.g., budget_exhausted or stagnation_detected). |
Populated solely when routing to the escalation branch. |
Bounded Loop Control for AI Agents (agentsop-bounded-loop) Advanced Features
- Three-Axis Defense Configuration: Simultaneously integrates step budgets, token consumption ceilings, and wall-clock execution limits to capture runaway operations at multiple network levels.
- Cryptographic Stagnation Tracking: Automatically hashes tool parameters and schema payloads to spot identical execution patterns, forcing immediate loop termination.
- Human-in-the-Loop (HITL) Callbacks: Features built-in escalation hooks that cleanly convert fatal loop errors into interactive requests (e.g., slack alerts or LangGraph interruptions) rather than raising raw traceback errors.
- Shared Multi-Agent Counter Memory: Fixes isolation issues where agents in hierarchical networks (like CrewAI or AutoGen) delegate endlessly to each other without sharing localized iteration totals.
SKILL.md
Loading
Related Openclaw Skills
Database Helper (Sun-Panel & MIMIC Postgres Setup)
A utility skill designed to guide developers and homelab enthusiasts in setting up Sun-Panel-Helper, Docker apps, and complex database environments like MIMIC III Postgres and Oracle 23ai.
Aspen Energy Analyzer & Chemical Design (data-analyzer-622b06)
An interactive AI agent skill that guides chemical engineers through the design of energy-efficient heat exchanger networks and pinch temperature analysis using Aspen Energy Analyzer.
Data Analyzer
An auto-crystallized AI skill that automates descriptive statistics, anomaly detection, and trend analysis for tabular datasets.
Deep Search Function Mastery
A practical utility skill that optimizes data querying and text manipulation by demonstrating why the Search function outperforms the Find function.
Aider AI Pair Programming SOP
A master Standard Operating Procedure (SOP) for driving terminal-based, git-native AI pair programming workflows using Aider.
Bio-Fraud Forensics (agentsop-bio-fraud-forensics)
An AI-powered screening methodology designed to identify potential data fabrication, image manipulation, and statistical anomalies in biomedical and life-science publications.
Featured*
