Agent Configuration

Complete reference for agent configuration parameters

Agent Configuration

This page provides detailed documentation for all agent configuration parameters, including execution controls, context management, and output formatting options.

Core Parameters

Execution Control Parameters

`max_iter`

Type: int
Default: 15
Description: Maximum number of iterations an agent will attempt to complete a task
Range: 1-100 (recommended: 10-25)

The max_iter parameter controls how many times an agent can iterate through its execution loop when working on a task. This prevents infinite loops and ensures tasks complete within reasonable bounds.

python

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    name="Researcher",
    execution=ExecutionConfig(max_iter=20),  # Allow up to 20 iterations
)

Best Practices:

Set lower values (5-10) for simple tasks
Use higher values (20-30) for complex research or analysis tasks
Monitor iteration count to optimize performance

`max_retry_limit`

Type: int
Default: 2
Description: Maximum number of times to retry a failed operation
Range: 0-10 (recommended: 2-5)

Controls how many times an agent will retry operations that fail due to transient errors like network issues or API rate limits.

python

agent = Agent(
    name="DataAnalyst",
    max_retry_limit=3,  # Retry failed operations up to 3 times
    # other parameters...
)

Use Cases:

API calls that may face rate limits
Network operations that may timeout
Tool executions that may fail intermittently

`max_budget`

Type: float | None
Default: None
Description: Hard USD cap on the agent run. Set via execution=ExecutionConfig(max_budget=...). Budget enforcement runs after each LLM call returns — in stop mode BudgetExceededError is raised, in warn mode a warning is logged and the agent continues.

Set a dollar limit via ExecutionConfig:

python

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    name="BudgetedAgent",
    instructions="Complete task within budget",
    execution=ExecutionConfig(max_budget=0.50),  # Stop at $0.50
)

result = agent.start("Research AI trends")

Benefits:

Prevents runaway costs in production — the guard fires before each LLM call in stop mode (default), so the over-budget call is never dispatched
Clean error handling in CLI mode
Zero overhead when not set

Mode behaviour: stop (default) enforces a pre-call hard ceiling; warn and callable modes check post-call and always let the call run. Pass on_budget_exceeded via ExecutionConfig to change the mode.

Context Management

`context_length`

Type: int
Default: None (uses model default)
Description: Maximum context window size in tokens
Common Values:
GPT-4: 128000
GPT-3.5: 16385
Claude 3: 200000

Defines the maximum amount of context (in tokens) that can be included in a single LLM request.

python

from praisonaiagents import ManagerConfig

agent = Agent(
    name="Analyzer",
    context=ManagerConfig(
        auto_compact=True,  # Automatically manage context window
        compact_threshold=0.8,  # Trigger at 80% usage
    ),
    # other parameters...
)

Important Considerations:

Larger context windows allow more information but increase costs
Some models perform better with focused context
Always validate against your LLM’s maximum context size

Output Formatting

`markdown`

Type: bool
Default: True
Description: Enable markdown formatting in agent outputs

Controls whether the agent formats its responses using markdown syntax for better readability.

python

agent = Agent(
    name="Reporter",
    instructions="Format your responses using markdown with headers, lists, and code blocks",
    templates={
        "response": """
        ## Analysis Report

        {content}

        ### Key Findings
        {findings}
        """
    }
)

Features When Enabled:

Headers using #, ##, etc.
Bold text with text
Code blocks with `
Lists and tables
Links and images

Advanced Execution Controls

Performance Optimization

python

agent = Agent(
    name="HighPerformanceAgent",
    instructions="Complete tasks efficiently",

    # Context optimization
    context=True,  # Enable context management

    # Caching configuration
    caching={"enabled": True},

    # Rate limiting (via ExecutionConfig)
    execution=ExecutionConfig(max_rpm=60)
)

Error Handling Configuration

python

from praisonaiagents.config import ExecutionConfig

agent = Agent(
    name="ResilientAgent",
    instructions="Handle tasks with error recovery",

    # Code execution via ExecutionConfig
    execution=ExecutionConfig(
        code_execution=True,
        code_mode="safe",  # Safe mode with restrictions
        # Enable tool bridge so model-generated code can call registered tools
        code_tools=True,
        code_tools_allow=["fetch", "parse"],  # Explicit per-run allow-list
    ),

    # LLM configuration
    model="gpt-4o-mini"
)

Configuration Patterns

Research Agent Configuration

python

research_agent = Agent(
    name="ResearchSpecialist",
    role="Senior Research Analyst",
    goal="Conduct thorough research and provide comprehensive reports",
    backstory="Expert researcher with 10 years of experience",

    # Enable reflection for quality
    reflection=True,

    # Enable planning for complex tasks
    planning=True,

    # LLM with large context
    llm="gpt-4o"  # Supports 128k context
)

Quick Task Agent Configuration

python

quick_agent = Agent(
    name="QuickResponder",
    role="Rapid Task Handler",

    # Optimized for speed using execution= config
    execution="fast",  # Uses ExecutionConfig(max_iter=5, max_retry_limit=1)

    # Minimal output using output= config
    output="silent"  # Disables verbose, markdown, stream
)

Environment Variable Overrides

Agent parameters can be overridden using environment variables:

bash

# Override default iteration limit
export PRAISONAI_AGENT_MAX_ITER=20

# Override retry limit
export PRAISONAI_AGENT_MAX_RETRY_LIMIT=5

# Set context length
export PRAISONAI_AGENT_CONTEXT_LENGTH=100000

# Disable markdown
export PRAISONAI_AGENT_MARKDOWN=false

Validation and Constraints

Parameter Validation Rules

Parameter	Validation	Error Handling
`max_iter`	Must be > 0	Defaults to 15 if invalid
`max_retry_limit`	Must be >= 0	Defaults to 2 if invalid
`context_length`	Must be greater than 0 and less than or equal to model max	Uses model default if invalid
`markdown`	Must be boolean	Defaults to True if invalid

Interaction Between Parameters

Context Length and Max Iterations
Higher max_iter may require larger context_length
Each iteration adds to context usage

Retry Limit and Execution Time
Higher max_retry_limit extends total execution time
Consider both when setting timeouts

Markdown and Response Templates
“ enables template formatting
Templates should use markdown syntax when enabled

Troubleshooting

Common Issues

Task taking too long

python

# Solution: Use a faster model or simplify the task
agent = Agent(
    instructions="Complete tasks concisely",
    llm="gpt-4o-mini"  # Faster model
)

Context window exceeded

python

# Solution: Enable context management
agent = Agent(
    instructions="...",
    context=True  # Enable context management
)

Need better quality responses

python

# Solution: Enable reflection
agent = Agent(
    instructions="...",
    reflection=True,
    planning=True
)

Agent Configuration