ExecutionConfig

Configure agent execution limits including iterations, rate limits, and timeouts

Next

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: positive int auto-builds a live RateLimiter
    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
)

Execution Presets

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

When the limit is reached

When the tool-calling loop reaches max_iter, the agent performs one final LLM call with tool_choice="none" and every advertised tool stripped, asking the model to summarise what it accomplished, what remains unfinished, and any suggested next steps using the tool results already in context. That synthesised text becomes the final answer.

The extra call is bounded to exactly one non-tool completion and is routed through the same retry / failover wrappers as every other completion, so a transient rate-limit error doesn’t drop straight to a placeholder. If the call still fails, the agent falls back to the last-turn text, then to "Reached the step limit before finishing this task." — behaviour never regresses.

There is no opt-out. To avoid truncation, increase max_iter so the agent can finish normally.

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

For tools, max_retry_limit / retry_* are translated into the same effective RetryPolicy as ToolConfig(retry_policy=...). An explicit retry_policy (or per-tool @tool(retry_policy=...)) wins over these fields. Users who never set retry_policy= see no behaviour change. The guardrail-retry backoff continues to use these fields regardless.

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.

Persistence

Save an ExecutionConfig to a dict for YAML/JSON storage and restore it later — every field round-trips.

from praisonaiagents import Agent, ExecutionConfig, CompactionStrategy

config = ExecutionConfig(
    max_iter=30,
    retry_initial_delay=3.0,
    retry_backoff_factor=4.0,
    retry_jitter=0.25,
    context_compaction=True,
    compaction_strategy=CompactionStrategy.LLM_SUMMARIZE,
)

# Save
saved = config.to_dict()

# Restore
restored = ExecutionConfig.from_dict(saved)

agent = Agent(name="Persisted Agent", instructions="...", execution=restored)

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,  # auto-builds a live RateLimiter(requests_per_minute=60)
        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

Related