agentsop-bounded-loop
Universal discipline for any LM-driven loop — agent retries, plan-act-observe, multi-agent handoffs, optimiser passes, test-fix cycles. Encodes the one rule every framework documents quietly and every team relearns expensively: the LM in the loop is NEVER a reliable terminator. Termination must be provided by an explicit counter + exit predicate + stagnation signal + escalation path that live OUTSIDE the LM's control. This is a tool- level, framework-agnostic skill. It maps onto LangGraph (recursion_limit + state counter + interrupt), CrewAI (max_iter + max_rpm + human_input), Claude / OpenAI SDKs (max_iterations + tool_use_budget), DSPy (declared evaluation budget), Aider (REPL + explicit retry cap), and AutoGen (max_consecutive_auto_reply). Search keywords: infinite loop, recursion limit, recursion_limit, GraphRecursionError, max iterations, max_iter, agent stuck, agent won't stop, runaway agent, ReAct loop not terminating, agent repeating itself.
agentsope · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add agentsope/SkillAlchemy --skill agentsop-bounded-loop技能说明
name: agentsop-bounded-loop version: 0.1.0 description: >- Universal discipline for any LM-driven loop — agent retries, plan-act-observe, multi-agent handoffs, optimiser passes, test-fix cycles. Encodes the one rule every framework documents quietly and every team relearns expensively: the LM in the loop is NEVER a reliable terminator. Termination must be provided by an explicit counter + exit predicate
- stagnation signal + escalation path that live OUTSIDE the LM's control. This is a tool- level, framework-agnostic skill. It maps onto LangGraph (recursion_limit + state counter + interrupt), CrewAI (max_iter + max_rpm + human_input), Claude / OpenAI SDKs (max_iterations + tool_use_budget), DSPy (declared evaluation budget), Aider (REPL + explicit retry cap), and AutoGen (max_consecutive_auto_reply). Search keywords: infinite loop, recursion limit, recursion_limit, GraphRecursionError, max iterations, max_iter, agent stuck, agent won't stop, runaway agent, ReAct loop not terminating, agent repeating itself.
bounded-loop · O7
Source posture: every load-bearing claim is cited inline with a short tag resolved against
references/R1-source-evidence.mdandreferences/R2-cross-framework.md. Examples cite the real GitHub issues they're distilled from.
1. 何时激活 (Activation Rules)
Activate this skill when any of the following is true:
- The task involves a workflow that contains a cycle — tool-call → reflect → retry, plan → act → observe → re-plan, draft → critique → revise, test → fix → re-test.
- The user is hitting a framework's "loop too deep" error:
GRAPH_RECURSION_LIMIT(LangGraph),MaxIterationsExceeded(LangChainAgentExecutor), "agent exceeded max_iter" (CrewAI),max_turns reached(OpenAI Agents SDK),stop_reason="max_tokens"mid-tool-use (Anthropic). - The user proposes "let's just raise the limit" / "set max_iter to 100" /
recursion_limit=200— this is the canonical anti-pattern this skill exists to prevent. - The user is building a multi-agent system with delegation, handoff,
or supervisor patterns — these are exposure-multipliers for unbounded
loops (see
[gh/crewai-330]). - The user is building an optimiser / evaluator loop (DSPy, AutoEval, RLHF, self-refining agent) where "stop when good enough" is the termination criterion — this is never sufficient on its own.
- The user wants a test-fix loop, self-healing code agent, or iterative refinement workflow — every code-agent in production (Cursor, Aider, Devin, Claude Code) ships with an explicit step budget.
Do not activate for: single LLM calls, one-shot RAG queries, stateless tool pipelines, or flows where the cycle is provably bounded by data (e.g., "iterate once per row in this fixed list").
2. 核心心智模型 (Core Mental Model)
Every loop body must produce a state change that proves progress — and the proof must be checkable without calling another LM.
Read that twice. It contains four claims:
-
The body must change state. A no-op iteration (same input → same output) is the definition of a stuck loop. If your body might return the same value twice, the loop is already broken; the safety net just hasn't fired yet.
-
The change must be progress, not just diff. A retry that says "I tried again, same error" is a change but not progress. The witness has to be monotone: counter strictly increasing, error list strictly shrinking, confidence strictly rising, or a new fact added to the plan.
-
The proof must be checkable. Pure Python. A
dict.get("retries") < N, notawait llm.ainvoke("are we done?"). If you ask the LM to evaluate termination, you've recreated the problem one level up — now that loop needs bounding. -
The LM is not allowed to vote. It can suggest finality (
stop_reason="end_turn",final_answertool, etc.) but the framework must verify against the predicate before terminating. Otherwise an LM that always says "let me try once more" runs forever.
Why the framework's default safety net is not enough
Every framework ships a default cap:
- LangGraph:
recursion_limit=25[lc-docs/errors] - CrewAI:
Agent.max_iter=20,Crew.max_rpm[crewai-docs/agents] - LangChain
AgentExecutor:max_iterations=15(deprecated default) - OpenAI Agents:
Run.max_turns - Anthropic Messages:
max_tokensper call (per-call, not per-loop)
These are billing safety nets, not control flow. The LangGraph docs say so explicitly:
"If you are not expecting your graph to go through many iterations, you likely have a cycle. Check your logic for infinite loops." —
[lc-docs/errors]https://docs.langchain.com/oss/python/langgraph/errors/GRAPH_RECURSION_LIMIT
And the cheatsheet adds:
"Hitting the limit typically indicates an underlying design flaw. The recursion limit is a safety net for runaway code, not a primary control flow mechanism." —
[cheatsheet/gotchas]
When you raise the limit to "fix" the error, you've moved the bug
further away, not removed it. The text-to-SQL agent in [gh/6731]
would have hit recursion_limit=100 after burning 5× the Databricks
quota.
The three-axis termination model
A bounded loop has three independent termination axes; you need at least two firing in series:
┌─── (a) success predicate met → exit success
│
[loop body] ────┼─── (b) counter / budget exhausted → exit escalation
│
└─── (c) stagnation detected → exit escalation
If you only have (a), the LM controls termination — it doesn't. If you only have (b), you'll burn the budget on N identical iterations. If you only have (c), one-shot flake will look like success.
Compose all three.
3. SOP 工作流 (Standard Operating Procedure)
A coder agent walks this top-down. Each step has a decision gate — answer "no" and you go back, not forward.
阅读完整来源 ↗