Execution

Execution configuration controls how long an agent runs, how many times it retries, and what code it can execute.

Replaces the deprecated allow_code_execution, code_execution_mode, and rate_limiter kwargs — see Legacy Agent Parameters.

The string form of execution= must name a valid preset (fast, balanced, thorough, …). A typo raises ValueError at construction time with a “Did you mean …?” suggestion — see Fail-Loud Defaults. Matching is case-insensitive, whitespace-tolerant, and treats -/_ interchangeably.

from praisonaiagents import Agent
from praisonaiagents.config.presets import EXECUTION_PRESETS

# All spellings apply the 'thorough' preset (max_iter=50):
for value in ("thorough", " thorough ", "THOROUGH"):
    agent = Agent(instructions="t", execution=value)
    assert agent.max_iter == EXECUTION_PRESETS["thorough"]["max_iter"]

Call (Python)	Before PR #4186	After PR #4186
`Agent(execution="thorough")`	✅ `max_iter=50`	✅ `max_iter=50`
`Agent(execution=" thorough ")`	⚠ validated → `max_iter=20` (default)	✅ `max_iter=50` (`thorough`)
`Agent(execution="THOROUGH")`	⚠ validated → `max_iter=20` (default)	✅ `max_iter=50` (`thorough`)

Before PraisonAI PR #4186, hyphen / uppercase / padded variants were accepted by the validator but silently fell back to the default max_iter. Upgrade to a build that includes PR #4186 to get the behaviour shown above.

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

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

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

Phase	What happens
1. Budget check	Execution tracks iterations against `max_iter`
2. Rate limit	Enforces `max_rpm` requests-per-minute
3. Time limit	Stops if `max_execution_time` seconds elapsed
4. Retry	Retries failed steps up to `max_retry_limit` times
5. Step-limit wrap-up	On 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:

Option	Type	Default	Description
`max_steps`	`int \| None`	`None`	Unified 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_iter`	`int`	`20`	Legacy 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_turn`	`int`	`10`	Cap on tool calls within a single LLM response (parallel-tool guardrail). Independent of `max_steps`.
`max_rpm`	`int \| None`	`None`	Max requests per minute — when set and no `rate_limiter` is passed, the Agent auto-builds one. `max_rpm <= 0` raises `ValueError`
`max_execution_time`	`int \| None`	`None`	Max seconds per run
`max_retry_limit`	`int`	`2`	Max retries on failure
`code_execution`	`bool`	`False`	Enable code execution (`code_mode="safe"` by default)
`max_budget`	`float \| None`	`None`	Hard 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.")

ExecutionConfig.parallel_tool_calls is the single source of truth for running batched LLM tool calls in parallel. ToolConfig.parallel is a deprecated alias for it — prefer this spelling, and never set both to conflicting values (that raises TypeError).

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

Use presets as a starting point

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.

Set max_budget for cost control

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.

Enable parallel_tool_calls for speed

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. This is the single source of truth for parallel tool calls; ToolConfig.parallel is a deprecated alias for it.

Code execution safety

code_mode="safe" is the right default for code_execution=True. Agent(sandbox=…) only isolates explicit agent.execute_code(...) calls — it does not give the model a tool. For isolation of code the model runs, use AgentFlow(run_on="docker") / run_on="e2b" (whole workflow) or LocalAgent(compute="docker") (per-agent). See Placement.

Scope code_tools with an explicit allow-list

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.

Detecting truncated runs

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.

Where Does It Run

Ask any agent where its thinking and tools actually execute

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

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

Execution Presets

How It Works

Configuration Options

Common Patterns

Pattern 1 — Budget-capped agent

Pattern 2 — Code execution agent

Pattern 3 — Parallel tool calls for speed

Pattern 4 — Code that calls your tools

Best Practices

Where Does It Run

​Quick Start

​Execution Presets

​How It Works

​Configuration Options

​Common Patterns

​Pattern 1 — Budget-capped agent

​Pattern 2 — Code execution agent

​Pattern 3 — Parallel tool calls for speed

​Pattern 4 — Code that calls your tools

​Best Practices

​Related

Where Does It Run

Quick Start

Execution Presets

How It Works

Configuration Options

Common Patterns

Pattern 1 — Budget-capped agent

Pattern 2 — Code execution agent

Pattern 3 — Parallel tool calls for speed

Pattern 4 — Code that calls your tools

Best Practices

Related