> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Loop Guardrails
> Stop broken tools from calling forever and burning tokens
Loop guardrails cap how many tool calls an agent can make in a single turn, stopping runaway loops from broken or chatty tools.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
name="Protected Agent",
instructions="Safe from infinite loops",
)
agent.start("Search the docs and summarise findings.")
```
The user sends a request; the guardrail stops the turn once tool-call limits are reached.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Loop Guardrail Protection"
Request[📝 Request] --> Counter{🔍 Count Tools}
Counter -->|Under Limit| Execute[🔧 Execute Tools]
Counter -->|At Limit| Stop[🛑 Stop with Message]
Execute --> Counter
end
classDef request fill:#6366F1,stroke:#7C90A0,color:#fff
classDef counter fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef execute fill:#189AB4,stroke:#7C90A0,color:#fff
classDef stop fill:#8B0000,stroke:#7C90A0,color:#fff
class Request request
class Counter counter
class Execute execute
class Stop stop
```
## Quick Start
Every agent gets automatic loop protection:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
# Default protection (10 tool calls per turn)
agent = Agent(
name="Protected Agent",
instructions="Safe from infinite loops",
tools=[my_tool]
)
agent.start("Your request")
```
The user starts a workflow loop; guardrails cap iterations and stop runaway tool calls.
Adjust the limit for your use case:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, ExecutionConfig
agent = Agent(
name="Custom Protected Agent",
instructions="Custom loop protection",
tools=[experimental_tool],
execution=ExecutionConfig(max_tool_calls_per_turn=5)
)
```
***
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant LLM
participant Counter
participant Tool
User->>Agent: Request
Agent->>LLM: Process
LLM->>Counter: Check tool call count
Counter-->>LLM: Count: 3/10 (OK)
LLM->>Tool: Execute tool
Tool-->>LLM: Result
Note over LLM,Counter: Repeat until task complete or limit reached
LLM->>Counter: Check tool call count
Counter-->>LLM: Count: 10/10 (LIMIT)
LLM-->>Agent: Stop with message
Agent-->>User: "Tool call limit reached..."
```
The agent tracks `tool_call_count` across iterations within a single chat turn:
1. **Before each batch**: Checks if `tool_call_count >= max_tool_calls_per_turn`
2. **At limit**: Stops execution with clear message
3. **Batch trimming**: If batch would exceed limit, trims to remaining calls
4. **Reset**: Counter resets for each new chat turn
***
## When the limit is hit
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# When the limit is reached, you'll see this message:
"Tool call limit reached (10 calls). Task may be too complex or there may be a broken tool causing repeated calls."
```
The agent stops cleanly instead of burning tokens indefinitely.
***
## Choosing a limit
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
Start[What type of agent?] --> Simple{Simple single-tool?}
Simple -->|Yes| Low[3-5 calls]
Simple -->|No| Complex{Complex multi-tool?}
Complex -->|Yes| High[20-30 calls]
Complex -->|No| Default[10 calls - default]
subgraph Examples
Low --> E1[Search agent, Calculator]
Default --> E2[General assistant, Q&A]
High --> E3[Research, Analysis, Multi-step workflows]
end
classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef limit fill:#6366F1,stroke:#7C90A0,color:#fff
classDef example fill:#10B981,stroke:#7C90A0,color:#fff
class Start,Simple,Complex decision
class Low,Default,High limit
class E1,E2,E3 example
```
| Scenario | Suggested value | Reasoning |
| -------------------------------- | ------------------------- | --------------------------------- |
| Single-tool simple agent | 3–5 | Most tasks need 1-2 calls |
| Default agent | 10 (default) | Balanced for most use cases |
| Multi-tool research agent | 20–30 | Complex workflows need more steps |
| Long-running autonomous workflow | Use autonomy mode instead | Different protection mechanism |
***
## Common Patterns
### Pattern 1: Protecting Experimental Tools
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, ExecutionConfig
agent = Agent(
name="Experimental Agent",
instructions="Testing new tools safely",
tools=[experimental_api_tool],
execution=ExecutionConfig(max_tool_calls_per_turn=3)
)
```
### Pattern 2: Complex Research Agent
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, ExecutionConfig
agent = Agent(
name="Research Agent",
instructions="Multi-step analysis and research",
tools=[search_tool, analyze_tool, summarize_tool],
execution=ExecutionConfig(max_tool_calls_per_turn=25)
)
```
***
## Best Practices
Use the default limit (10) unless you have a specific reason to change it. It handles most use cases well.
Set 3-5 calls when testing new or potentially buggy tools to prevent token waste.
Increase to 20-30 for agents that need multiple tool calls for complex, multi-step tasks.
If agents hit the limit frequently on legitimate tasks, increase it. If they waste tokens on broken tools, decrease it.
***
## Related
Configure all execution limits
DoomLoop protection for autonomous agents