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.

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.

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")

   The user starts a workflow loop; guardrails cap iterations and stop runaway tool calls.

2. Custom Limit

   Adjust the limit for your use case:

   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

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 a batch would exceed the limit, it is trimmed before the assistant turn is recorded, so every declared tool_call_id still gets a reply.
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

Common Patterns

Pattern 1: Protecting Experimental Tools

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

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

Related