Skip to main content
Execution configuration controls how long an agent runs, how many times it retries, and what code it can execute. 
from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a thorough research assistant.",
    execution="thorough",
)

agent.start("Analyze the competitive landscape of the electric vehicle market.")
The user sends a research prompt; iteration limits, retries, and rate limits govern how long the agent runs.

​
Quick Start

1

Level 1 — String (preset)

Pick a named execution profile — the shortest way to set sensible limits.
from praisonaiagents import Agent

agent = Agent(
    name="Researcher",
    instructions="You are a research assistant.",
    execution="thorough",
)
agent.start("Compare five programming languages for web development.")
2

Level 2 — Config class (full control)

Use ExecutionConfig to set exact iteration, time, and retry limits.
from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    name="Researcher",
    instructions="You are a research assistant.",
    execution=ExecutionConfig(
        max_iter=50,
        max_execution_time=300,
        max_retry_limit=3,
    ),
)
agent.start("Research and summarize the latest AI safety papers.")

​
Execution Presets

​
How It Works

PhaseWhat happens
1. Budget checkExecution tracks iterations against max_iter
2. Rate limitEnforces max_rpm requests-per-minute
3. Time limitStops if max_execution_time seconds elapsed
4. RetryRetries failed steps up to max_retry_limit times
5. Step-limit wrap-upOn the final permitted step (max_steps, or max_iter when unset), the agent injects a wrap-up instruction so the model produces a coherent final answer summarising progress instead of being hard-cut. Detect truncation with agent.last_stop_reason == "max_steps". See Step Budget.

​
Configuration Options

Full list of options, types, and defaults — ExecutionConfig
Prefer max_steps for the tool-use budget — it’s the unified knob honoured by both execution loops, and you can detect truncation with agent.last_stop_reason. See Step Budget.
The most common options at a glance:
OptionTypeDefaultDescription
max_stepsint | NoneNoneUnified outer-loop step budget honoured by both tool-execution loops (OpenAI-native and LiteLLM). None falls back to max_iter. Must be >= 1 when set. See Step Budget.
max_iterint20Legacy per-loop iteration cap, used when max_steps is unset. On the final step the agent receives a graceful wrap-up instruction and returns a coherent summary — not the old canned "Task completed." placeholder.
max_tool_calls_per_turnint10Cap on tool calls within a single LLM response (parallel-tool guardrail). Independent of max_steps.
max_rpmint | NoneNoneMax requests per minute
max_execution_timeint | NoneNoneMax seconds per run
max_retry_limitint2Max retries on failure
code_executionboolFalseEnable code execution (code_mode="safe" by default)
max_budgetfloat | NoneNoneHard USD spend limit per run
context_compaction currently defaults to False but will default to True in the next release. To opt in early, set context_compaction=True in your ExecutionConfig. This provides automatic protection against context window overflow.

​
Common Patterns

​
Pattern 1 — Budget-capped agent

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    instructions="You are a research assistant.",
    execution=ExecutionConfig(max_budget=0.50, on_budget_exceeded="warn"),
)
response = agent.start("Research the history of computing.")
print(response)

​
Pattern 2 — Code execution agent

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    instructions="You are a Python coding assistant that runs code to verify answers.",
    execution=ExecutionConfig(
        code_execution=True,
        code_mode="safe",
        max_iter=30,
    ),
)
agent.start("Write and test a Python function to find prime numbers.")

​
Pattern 3 — Parallel tool calls for speed

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    instructions="You are a multi-source research agent.",
    execution=ExecutionConfig(parallel_tool_calls=True, max_iter=40),
)
agent.start("Gather weather, news, and stock prices for New York.")

​
Pattern 4 — Code that calls your tools

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    instructions="You solve tasks by writing code that calls the provided tools.",
    tools=[search_web, calculate],
    execution=ExecutionConfig(
        code_execution=True,
        code_tools=True,
        code_tools_allow=["search_web", "calculate"],
    ),
)
agent.start("Search for the population of three cities and sum them.")

​
Best Practices

execution="thorough" works well for most research and multi-step tasks. Only switch to custom ExecutionConfig when you need specific limits like budget caps or code execution.
For any agent making many API calls, set max_budget=0.50 to cap spend at 50 cents per run. Use on_budget_exceeded="warn" in development and "stop" in production.
When your agent calls multiple independent tools per turn (e.g., search + fetch + calculate), enable parallel_tool_calls=True to run them concurrently and cut latency.
Always use code_mode="safe" and code_sandbox_mode="sandbox" when enabling code execution. Only switch to "unsafe" or "direct" in fully isolated environments you control.
When code_tools=True, always set code_tools_allow to the exact tool names code may call. Leaving it None exposes no tools (the safe default), so name only what the task needs — never grant blanket access.
Set max_steps and check agent.last_stop_reason == "max_steps" to detect truncation — no string-matching needed. The returned text is a real LLM-authored wrap-up (“Here’s what I accomplished… here’s what remains…”), not a placeholder. See Step Budget.

Step Budget — cap tool-use steps and detect truncation

Output — control verbosity and response format

Step Budget — cap tool-use steps and detect truncation

Caching — avoid redundant LLM API calls