Skip to main content
Control agent execution behavior with limits on iterations, rate limiting, timeouts, and retries.

​
Quick Start

1

Using Presets

Use string presets for common configurations:
from praisonaiagents import Agent

# Fast execution (fewer iterations)
agent = Agent(
    name="Fast Agent",
    instructions="Quick tasks",
    execution="fast"
)

# Thorough execution (more iterations)
agent = Agent(
    name="Thorough Agent",
    instructions="Complex analysis",
    execution="thorough"
)
2

With Configuration

Fine-grained control:
from praisonaiagents import Agent
from praisonaiagents.config import ExecutionConfig

agent = Agent(
    name="Custom Agent",
    instructions="Custom execution limits",
    execution=ExecutionConfig(
        max_iter=50,
        max_rpm=100,
        max_execution_time=300,
        max_retry_limit=5,
        max_tool_calls_per_turn=10
    )
)

​
Configuration Options

from praisonaiagents.config import ExecutionConfig

config = ExecutionConfig(
    # Iteration limits
    max_iter=20,
    
    # Rate limiting (requests per minute)
    max_rpm=None,
    
    # Time limits (seconds)
    max_execution_time=None,
    
    # Retry settings
    max_retry_limit=2,
    
    # Tool call limits (loop protection)
    max_tool_calls_per_turn=10
)
ParameterTypeDefaultDescription
max_iterint20Maximum tool-calling iterations. Now propagated to the LLM instance, so it controls every internal loop (previously some loops were hardcoded to 5/10/20/50). Both the ExecutionConfig default and the LLM-direct-construction default are 20 (aligned as of PR #1898).
max_rpmint | NoneNoneMax requests per minute (rate limit)
max_execution_timeint | NoneNoneMax execution time in seconds
max_retry_limitint2Max retries for retryable tool failures and guardrail validation failures. Total attempts = 1 + max_retry_limit. Retries use exponential backoff with jitter (see retry_initial_delay, retry_backoff_factor, retry_jitter).
retry_initial_delayfloat1.0First retry delay in seconds. Subsequent delays grow exponentially. Must be > 0.
retry_backoff_factorfloat2.0Multiplier applied each attempt (base = initial × factor^(attempt−1)). Must be >= 1.0.
retry_jitterfloat0.1Random jitter added as a fraction of the base delay. Must be >= 0.
max_tool_calls_per_turnint10Maximum tool calls allowed in a single chat turn. When exceeded, execution stops with a clear message instead of looping forever.
context_compactionbool | ContextCompactionPolicyFalseProactive context-overflow protection. True uses the BALANCED_POLICY preset. Pass a ContextCompactionPolicy instance for custom routing. Default flips to True in the next release — a DeprecationWarning is emitted today when left at False. See Context Compaction Policy.
max_budgetfloat | NoneNoneHard USD cap per agent run. None = no limit.
on_budget_exceededstr | callable"stop"Action when limit is hit: "stop" raises BudgetExceededError, "warn" logs and continues, or a callable(total_cost, max_budget).
For simple budget limits, use the Agent(max_budget=...) convenience parameter instead of importing ExecutionConfig. See Agent max_budget for details.These retry settings apply to both tool execution and guardrail validation retries.
Invalid values raise ValueError: retry_initial_delay must be > 0, retry_backoff_factor must be >= 1.0, retry_jitter must be >= 0.

​
Execution Presets

Presetmax_iterDescription
"fast"10Quick tasks, fewer iterations
"balanced"20Default, balanced approach
"thorough"50Complex tasks, more iterations
"unlimited"1000Long-running tasks

​
Iteration Propagation

ExecutionConfig.max_iter is now the single source of truth for iteration limits, replacing previously hardcoded internal caps. Before: Internal LLM loops were hardcoded to different limits (5, 10, 20, 50) After: All loops respect the configured max_iter value 
from praisonaiagents import Agent
from praisonaiagents.config import ExecutionConfig

# This now controls ALL iteration loops, not just agent-level loops
agent = Agent(
    name="Unified Control",
    instructions="Respect iteration limits everywhere",
    execution=ExecutionConfig(max_iter=15)
)
# The agent's LLM will respect 15 iterations in all internal loops

​
Tool Retry & Exponential Backoff

Tool and guardrail retries use exponential backoff with jitter so transient failures recover without hammering APIs. Delay formula: delay = min(initial_delay × factor^(attempt−1), 60s) + random(0, jitter × base). With defaults (retry_initial_delay=1.0, retry_backoff_factor=2.0), three retries wait roughly 1.0s, 2.0s, 4.0s (plus up to 10% jitter). See Tool Retry & Backoff for retry classification and patterns.

​
Proactive Context Compaction

Context compaction proactively prevents overflow before LLM calls instead of reacting after errors. 
from praisonaiagents import Agent, ExecutionConfig, BALANCED_POLICY

agent = Agent(
    name="Researcher",
    execution=ExecutionConfig(
        max_iter=30,
        context_compaction=BALANCED_POLICY,  # explicit preset
    ),
)
See Context Compaction Policy for detailed configuration options.

​
Common Patterns

​
Pattern 1: Rate-Limited Agent

from praisonaiagents import Agent
from praisonaiagents.config import ExecutionConfig

agent = Agent(
    name="Rate Limited Agent",
    instructions="Respect API limits",
    execution=ExecutionConfig(
        max_rpm=60,  # 60 requests per minute
        max_retry_limit=3
    )
)

​
Pattern 2: Time-Bounded Agent

from praisonaiagents import Agent
from praisonaiagents.config import ExecutionConfig

agent = Agent(
    name="Timed Agent",
    instructions="Complete within time limit",
    execution=ExecutionConfig(
        max_execution_time=60,  # 60 seconds max
        max_iter=100
    )
)

​
Pattern 3: Resilient Agent

from praisonaiagents import Agent
from praisonaiagents.config import ExecutionConfig

agent = Agent(
    name="Resilient Agent",
    instructions="Handle failures gracefully",
    execution=ExecutionConfig(
        max_retry_limit=5,
        retry_initial_delay=0.5,
        retry_backoff_factor=2.0,
        retry_jitter=0.2,
    )
)

​
Pattern 4: Loop-Protected Agent

from praisonaiagents import Agent
from praisonaiagents.config import ExecutionConfig

agent = Agent(
    name="Protected Agent",
    instructions="Agent with experimental tools",
    execution=ExecutionConfig(
        max_tool_calls_per_turn=5,  # Lower limit for potentially noisy tools
        max_iter=20
    )
)

​
Best Practices

Always set max_iter to prevent runaway agents consuming resources.
Set max_rpm when calling external APIs to avoid rate limit errors.
Use max_execution_time in production to prevent hung processes.
Adjust max_tool_calls_per_turn based on your tools: lower for experimental tools (3-5), higher for complex multi-tool workflows (20-30).

Context Compaction Policy

Proactive context overflow protection

LLM Error Classification

Iteration control and error handling integration

Async Execution

Async agent execution

Background Tasks

Run agents in background

Structured LLM Errors

LLM error handling and retry policies

Tool Retry & Backoff

Exponential backoff for tool and guardrail retries