Skip to main content
Loop guardrails cap how many tool calls an agent can make in a single turn, stopping runaway loops from broken or chatty tools.

​
Quick Start

1

Default Protection

Every agent gets automatic loop protection:
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")
2

Custom Limit

Adjust the limit for your use case:
from praisonaiagents import Agent
from praisonaiagents.config import 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

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

# 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

ScenarioSuggested valueReasoning
Single-tool simple agent3–5Most tasks need 1-2 calls
Default agent10 (default)Balanced for most use cases
Multi-tool research agent20–30Complex workflows need more steps
Long-running autonomous workflowUse autonomy mode insteadDifferent protection mechanism

​
Common Patterns

​
Pattern 1: Protecting Experimental Tools

from praisonaiagents import Agent
from praisonaiagents.config import 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

from praisonaiagents import Agent
from praisonaiagents.config import 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.

ExecutionConfig

Configure all execution limits

Autonomy Mode

DoomLoop protection for autonomous agents